Distribuzione con file ZIP per Funzioni di Azure

  • Articolo

Questo articolo descrive come distribuire i file di progetto dell'app per le funzioni in Azure da un file ZIP (compresso). Vengono fornite informazioni su come eseguire una distribuzione push sia utilizzando l'interfaccia della riga di comando di Azure sia le API REST. Strumenti di base di Funzioni di Azure usa anche le API di distribuzione quando pubblica un progetto locale in Azure.

La distribuzione zip è anche un modo semplice per eseguire le funzioni dal pacchetto di distribuzione. Per altre informazioni, vedere Eseguire le funzioni da un file di pacchetto in Azure.

Funzioni di Azure include l'intera gamma di opzioni di integrazione e distribuzione continua offerte dal Servizio app di Azure. Per altre informazioni, vedere Distribuzione continua per Funzioni di Azure.

Per velocizzare lo sviluppo, potrebbe risultare più semplice distribuire i file di progetto dell'app per le funzioni direttamente da un file .zip. L'API della distribuzione con estensione zip prende il contenuto di un file con estensione zip e lo estrae nella cartella wwwroot dell'app per le funzioni. La distribuzione tramite file ZIP utilizza lo stesso servizio Kudu usato per le distribuzioni basate su integrazione continua, che include:

  • Eliminazione di file rimasti da distribuzioni precedenti.
  • Personalizzazione della distribuzione, inclusa l'esecuzione di script di distribuzione.
  • Log di distribuzione.
  • La funzione di sincronizzazione si attiva in un'app per le funzioni del Piano A consumo.

Per altre informazioni, vedere le informazioni di riferimento sulla distribuzione tramite file ZIP.

Importante

Quando si usa la distribuzione con file ZIP, vengono eliminati dall'app per le funzioni i file della distribuzione esistente che non sono presenti nel file ZIP.

Requisiti di distribuzione con file ZIP

L'archivio ZIP distribuito deve contenere tutti i file necessari per eseguire l'app per le funzioni. È possibile creare manualmente un archivio ZIP dal contenuto di una cartella del progetto di Funzioni usando la funzionalità di compressione .zip predefinita o strumenti di terze parti.

L'archivio deve includere il file host.json nella radice della cartella estratta. Lo stack di linguaggio selezionato per l'app per le funzioni crea requisiti aggiuntivi:

Importante

Per i linguaggi che generano l'output compilato per la distribuzione, assicurarsi di comprimere il contenuto della cartella di output che si vuole pubblicare e non l'intera cartella del progetto. Quando Funzioni estrae il contenuto dell'archivio ZIP, il file host.json deve esistere nella radice del pacchetto.

Un processo di distribuzione ZIP estrae i file e le cartelle dell'archivio ZIP nella directory wwwroot. Se si include la directory padre durante la creazione dell'archivio, il sistema non troverà i file che si prevede di visualizzare in wwwroot.

Eseguire la distribuzione usando l'interfaccia della riga di comando di Azure

Per attivare una distribuzione push, è possibile utilizzare l'interfaccia della riga di comando di Azure. Eseguire la distribuzione push di un file ZIP nell'app per le funzioni usando il comando az functionapp deployment source config-zip. Per usare questo comando, è necessario utilizzare l'interfaccia della riga di comando di Azure 2.0.21 o versione successiva. Per visualizzare la versione dell'interfaccia della riga di comando di Azure in uso, utilizzare il comando az --version.

Nel comando seguente sostituire il segnaposto <zip_file_path> con il percorso del file ZIP. Sostituire anche <app_name> con il nome univoco dell'app per le funzioni e sostituire <resource_group> con il nome del gruppo di risorse.

az functionapp deployment source config-zip -g <resource_group> -n \
<app_name> --src <zip_file_path>

Questo comando distribuisce i file di progetto del file ZIP scaricato nell'app per le funzioni in Azure. Riavvia quindi l'app. Per visualizzare l'elenco delle distribuzioni per questa app per le funzioni, è necessario utilizzare le API REST.

Quando si utilizza l'interfaccia della riga di comando di Azure nel computer locale, <zip_file_path> è il percorso del file ZIP nel computer in uso. È anche possibile eseguire l'interfaccia della riga di comando di Azure in Azure Cloud Shell. Quando si utilizza Cloud Shell, è innanzitutto necessario caricare il file ZIP per la distribuzione nell'account File di Azure associato a Cloud Shell. In tal caso <zip_file_path> è il percorso di archiviazione utilizzato dall'account Cloud Shell. Per altre informazioni, vedere Rendere persistenti i file in Azure Cloud Shell.

Distribuire il file con estensione zip con le API REST

È possibile usare le API REST del servizio distribuzione per distribuire il file ZIP nella propria app in Azure. Per eseguire la distribuzione, inviare una richiesta POST a https://<app_name>.scm.azurewebsites.net/api/zipdeploy. La richiesta POST deve contenere il file ZIP nel corpo del messaggio. Le credenziali di distribuzione per l'app vengono fornite nella richiesta usando l'autenticazione di base HTTP. Per altre informazioni, vedere le informazioni di riferimento sulla distribuzione push tramite file ZIP.

Per l'autenticazione HTTP di base sono necessarie le credenziali di distribuzione del servizio app. Per informazioni su come impostare le credenziali di distribuzione, vedere Impostare e reimpostare le credenziali a livello di utente.

Con cURL

L'esempio seguente usa lo strumento cURL per distribuire un file con estensione zip. Sostituire i segnaposto <deployment_user>, <zip_file_path> e <app_name>. Quando richiesto da cURL, digitare la password.

curl -X POST -u <deployment_user> --data-binary "@<zip_file_path>" https://<app_name>.scm.azurewebsites.net/api/zipdeploy

Questa richiesta attiva la distribuzione push dal file ZIP caricato. È possibile esaminare le distribuzioni correnti e passate usando l'endpoint https://<app_name>.scm.azurewebsites.net/api/deployments, come illustrato nell'esempio cURL seguente. Anche in questo caso, sostituire il segnaposto <app_name> con il nome dell'app e <deployment_user> con il nome utente delle credenziali di distribuzione.

curl -u <deployment_user> https://<app_name>.scm.azurewebsites.net/api/deployments

Distribuzione zip asincrona

Durante la distribuzione in modo sincrono, è possibile che vengano visualizzati errori correlati ai timeout di connessione. Aggiungere ?isAsync=true all'URL per distribuire in modo asincrono. Si riceverà una risposta non appena il file ZIP viene caricato con un'intestazione Location che punta all'URL dello stato della distribuzione pollable. Quando si esegue il polling dell'URL fornito nell'intestazione Location, si riceve una risposta HTTP 202 (accettata) mentre il processo è in corso e una risposta HTTP 200 (OK) una volta che l'archivio è stato espanso e la distribuzione è stata completata correttamente.

Autenticazione Microsoft Entra

Un'alternativa all'uso dell'autenticazione HTTP BASIC per la distribuzione zip consiste nell'usare un'identità Microsoft Entra. L'identità di Microsoft Entra può essere necessaria se l'autenticazione HTTP BASIC è disabilitata per il sito SCM.

È necessario un token di accesso Microsoft Entra valido per l'utente o l'entità servizio che esegue la distribuzione. È possibile recuperare un token di accesso usando il comando az account get-access-token dell'interfaccia della riga di comando di Azure. Il token di accesso verrà usato nell'intestazione di autenticazione della richiesta HTTP POST.

curl -X POST \
    --data-binary "@<zip_file_path>" \
    -H "Authorization: Bearer <access_token>" \
    "https://<app_name>.scm.azurewebsites.net/api/zipdeploy"

Con PowerShell

L'esempio seguente usa Publish-AzWebapp per caricare il file .zip. Sostituire i segnaposto <group-name>, <app-name> e <zip-file-path>.

Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath <zip-file-path>

Questa richiesta attiva la distribuzione push dal file ZIP caricato.

Per esaminare le distribuzioni correnti e precedenti, eseguire i comandi seguenti. Anche in questo caso, sostituire i segnaposto <deployment-user>, <deployment-password>e <app-name>.

$username = "<deployment-user>"
$password = "<deployment-password>"
$apiUrl = "https://<app-name>.scm.azurewebsites.net/api/deployments"
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username, $password)))
$userAgent = "powershell/1.0"
Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -UserAgent $userAgent -Method GET

Eseguire la distribuzione usando il modello di ARM

È possibile usare l'estensione del modello di ARM ZipDeploy per eseguire il push del file .zip nell'app per le funzioni.

Esempio di modello ARM ZipDeploy

Questo modello include sia uno slot di produzione che quello di staging e viene distribuito in uno o nell'altro. In genere, si usa questo modello per eseguire la distribuzione nello slot di staging e quindi si scambia per ottenere il nuovo pacchetto ZIP in esecuzione nello slot di produzione.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServiceName": {
      "type": "string"
    },
    "deployToProduction": {
      "type": "bool",
      "defaultValue": false
    },
    "slot": {
      "type": "string",
      "defaultValue": "staging"
    },
    "packageUri": {
      "type": "secureString"
    }
  },
  "resources": [
    {
      "condition": "[parameters('deployToProduction')]",
      "type": "Microsoft.Web/sites/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/ZipDeploy', parameters('appServiceName'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    },
    {
      "condition": "[not(parameters('deployToProduction'))]",
      "type": "Microsoft.Web/sites/slots/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/{1}/ZipDeploy', parameters('appServiceName'), parameters('slot'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    }
  ]
}

Per la distribuzione iniziale, si distribuisce direttamente nello slot di produzione. Per altre informazioni, vedere Distribuzioni di slot.

Eseguire le funzioni dal pacchetto di distribuzione

È anche possibile scegliere di eseguire le funzioni direttamente dal file di pacchetto di distribuzione. Questo metodo ignora il passaggio di distribuzione relativo alla copia dei file dal pacchetto alla directory wwwroot dell'app per le funzioni. Il file del pacchetto è invece montato dal runtime di funzioni e il contenuto della directory wwwroot diventa di sola lettura.

La distribuzione ZIP si integra con questa funzionalità che può essere attivata impostando l'impostazione dell'app per le funzioni WEBSITE_RUN_FROM_PACKAGE su un valore di 1. Per altre informazioni, vedere Run your Functions from a deployment package file (Esecuzione di funzioni da un file di pacchetto di distribuzione).

Personalizzazione della distribuzione

Il processo di distribuzione presuppone che il file ZIP di cui si esegue il push contenga un'app pronta da eseguire. Per impostazione predefinita, non vengono eseguite personalizzazioni. Per abilitare gli stessi processi di compilazione ottenuti con l'integrazione continua, aggiungere quanto segue alle impostazione applicazione:

SCM_DO_BUILD_DURING_DEPLOYMENT=true

Quando si usa la distribuzione push tramite file ZIP, questa impostazione è false per impostazione predefinita. L'impostazione predefinita è true per le distribuzioni tramite integrazione continua. Se impostata su true, durante la distribuzione vengono usate le impostazioni relative alla distribuzione. È possibile configurare queste impostazioni come impostazioni app o in un file di configurazione con estensione deployment disponibile nella radice del file ZIP. Per altre informazioni, vedere Repository and deployment-related settings (Repository e impostazioni relative alla distribuzione) nelle informazioni di riferimento sulla distribuzione.

Scaricare i file dell'app per le funzioni

Se le funzioni sono state create usando l'editor nel portale di Azure, è possibile scaricare il progetto dell'app per le funzioni esistente come file .zip in uno dei modi seguenti:

  • Dal portale di Azure:

    1. Accedere al portale di Azure e passare all'app per le funzioni.

    2. Nella scheda Panoramica selezionare Scarica contenuto dell'app. Selezionare le opzioni di download, quindi Scarica.

      Scaricare il progetto dell'app per le funzioni

      Il file ZIP scaricato è nel formato corretto per essere ripubblicato nell'app per le funzioni utilizzando la distribuzione push con file ZIP. Il download dal portale consente anche di aggiungere i file necessari per aprire l'app per le funzioni direttamente in Visual Studio.

  • Tramite API REST:

    Usare l'API GET di distribuzione seguente per scaricare i file dal progetto <function_app>:

    https://<function_app>.scm.azurewebsites.net/api/zip/site/wwwroot/

    Includendo /site/wwwroot/ ci si assicura che il file ZIP contenga solo i file di progetto dell'app per le funzioni e non l'intero sito. Se l'accesso ad Azure non è ancora stato eseguito, verrà richiesto di farlo.

È anche possibile scaricare un file ZIP da un repository GitHub. Quando si scarica un repository GitHub come file ZIP, GitHub aggiunge un livello di cartelle aggiuntivo per il ramo. Questo livello di cartelle aggiuntivo implica che non è possibile distribuire direttamente il file ZIP così come è stato scaricato da GitHub. Se si usa un repository GitHub per mantenere l'app per le funzioni, è necessario utilizzare l'integrazione continua per distribuire l'app.

Passaggi successivi

Eseguire le funzioni da un file di pacchetto in Azure