Compartilhar via

Implantação de zip para o Azure Functions

  • Artigo

Este artigo descreve como implantar seus arquivos de projeto de aplicativo de função para o Azure de um arquivo .zip (compactado). Você aprenderá a realizar uma implantação de envio por push, usando a CLI do Azure e usando as APIs REST. As Ferramentas básicas do Azure Functions também usam essas APIs de implantação ao publicar um projeto local no Azure.

A implantação de zip também é uma forma fácil de executar suas funções por meio do pacote de implantação. Para saber mais, confira Executar suas funções por meio de um arquivo de pacote no Azure.

O Azure Functions tem a gama completa de opções de implantação e integração contínuas que são fornecidas pelo Serviço de Aplicativo do Azure. Para saber mais, confira Implantação contínua do Azure Functions.

Para acelerar o desenvolvimento, talvez seja mais fácil implantar seus arquivos de projeto do aplicativo de funções diretamente de um arquivo .zip. A API de implantação do .zip extrai o conteúdo de um arquivo .zip para a pasta wwwroot do seu aplicativo de funções. Essa implantação de arquivo .zip usa o mesmo serviço Kudu que alimenta implementações baseadas em integração contínua, incluindo:

  • Exclusão de arquivos que foram mantidos de implantações anteriores.
  • Personalização da implantação, incluindo execução de scripts de implantação.
  • Logs de implantação.
  • Gatilhos de função de sincronização em um aplicativo de funções de Plano de consumo.

Para obter mais informações, consulte a referência de implantação do .zip.

Importante

Quando você usa a implantação de .zip, todos os arquivos de uma implantação existente que não são encontrados no arquivo .zip são excluídos do seu aplicativo de funções.

Requisitos de implantação de arquivo .zip

O arquivador zip implantado deve conter todos os arquivos necessários para executar seu aplicativo de funções. Você pode criar manualmente um arquivador zip com base no conteúdo de uma pasta de projeto do Functions usando a funcionalidade de compactação .zip interna ou ferramentas de terceiros.

O arquivador deve incluir o arquivo host.json na raiz da pasta extraída. A pilha de idiomas selecionada para o aplicativo de funções cria requisitos adicionais:

Importante

Para linguagens que geram saída compilada para implantação, certifique-se de compactar o conteúdo da pasta de saída que você planeja publicar e não de toda a pasta do projeto. Quando o Functions extrai o conteúdo do arquivo zip, o arquivo host.json deve existir na raiz do pacote.

Um processo de implantação zip extrai os arquivos e pastas do arquivo zip no diretório wwwroot. Se você incluir o diretório pai ao criar o arquivo morto, o sistema não encontrará os arquivos que ele espera ver em wwwroot.

Implantar usando a CLI do Azure

Você pode usar a CLI do Azure para disparar uma implantação de envio por push. Implante o arquivo .zip em seu aplicativo de funções usando o comando az functionapp deployment source config-zip. Para usar esse comando, você deve usar a CLI do Azure versão 2.0.21 ou posterior. Para ver qual versão do CLI do Azure que você está usando, use o comando az --version.

No comando a seguir, substitua o espaço reservado <zip_file_path> pelo caminho para o local do seu arquivo .zip. Além disso, substitua <app_name> pelo nome exclusivo do seu aplicativo de funções e substitua <resource_group> pelo nome do seu grupo de recursos.

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

Esse comando implanta os arquivos de projeto do arquivo .zip baixado para seu aplicativo de funções no Azure. Em seguida, ele reinicia o aplicativo. Para visualizar a lista de implantações para o aplicativo, é necessário usar as APIs REST.

Quando você estiver usando a CLI do Azure em seu computador local, <zip_file_path> é o caminho para o arquivo .zip em seu computador. Você também pode executar a CLI do Azure no Azure Cloud Shell. Quando você usa o Cloud Shell, você deve primeiro carregar seu arquivo .zip de implantação para a conta do Azure Files associada com o seu Cloud Shell. Nesse caso, <zip_file_path> é o local de armazenamento que a sua conta do Cloud Shell usa. Para obter mais informações, consulte Persistir arquivos no Azure Cloud Shell.

Implantar o arquivo ZIP com APIs REST

Você pode usar as APIs REST do serviço de implantação para implantar o arquivo .zip ao seu aplicativo no Azure. Para implantar, envie uma solicitação POST para https://<app_name>.scm.azurewebsites.net/api/zipdeploy. A solicitação POST deve conter o arquivo .zip no corpo da mensagem. As credenciais de implantação para seu aplicativo são fornecidas na solicitação usando a autenticação BÁSICA HTTP. Para obter mais informações, consulte a referência de implantação por push do .zip.

Para a autenticação HTTP BÁSICA, você precisa das credenciais de implantação do Serviço de Aplicativo. Para ver como definir as credenciais de implantação, consulte Definir e redefinir as credenciais de usuário.

Com o cURL

O exemplo a seguir usa a ferramenta cURL para implantar um arquivo .zip. Substitua os espaços reservados <deployment_user>, <zip_file_path> e <app_name>. Quando solicitado pelo cURL, digite a senha.

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

Essa solicitação dispara a implantação de envio do arquivo .zip carregado. Você pode examinar as implantações atuais e anteriores, usando o ponto de extremidade https://<app_name>.scm.azurewebsites.net/api/deployments, conforme mostrado no exemplo de cURL a seguir. Novamente, substitua <app_name> com o nome do seu aplicativo e <deployment_user> com o nome de usuário de suas credenciais de implantação.

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

Implantação da zip assíncrona

Ao implantar de forma síncrona, você pode receber erros relacionados a tempos limite de conexão. Adicione ?isAsync=true à URL para implantar de forma assíncrona. Você receberá uma resposta assim que o arquivo zip for carregado com um cabeçalho Location apontando para a URL de status de implantação pollable. Ao sondar a URL fornecida no cabeçalho Location, você receberá uma resposta HTTP 202 (Aceita) enquanto o processo estiver em andamento e uma resposta HTTP 200 (OK) depois que o arquivo tiver sido expandido e a implantação tiver sido concluída com êxito.

autenticação do Microsoft Entra

Uma alternativa ao uso da autenticação HTTP BASIC para a implantação do zip é usar uma identidade do Microsoft Entra. A identidade do Microsoft Entra pode ser necessária se a autenticação HTTP BASIC estiver desabilitada para o site SCM.

O usuário ou a entidade de serviço que fará a implantação precisará ter um token de acesso válido do Microsoft Entra. Um token de acesso pode ser recuperado usando o comando az account get-access-token da CLI do Azure. O token de acesso será usado no cabeçalho Autenticação da solicitação HTTP POST.

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

Com o PowerShell

O exemplo a seguir usa Publish-AzWebapp para carregar o arquivo .zip. Substitua os espaços reservados <group-name>, <app-name> e <zip-file-path>.

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

Essa solicitação dispara a implantação de envio do arquivo .zip carregado.

Para examinar as implantações atuais e anteriores, execute os comandos a seguir. Novamente, substitua os espaços reservados <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

Implantação usando o modelo do ARM

Use a extensão de modelo do ARM ZipDeploy para enviar o arquivo .zip por push ao aplicativo de funções.

Exemplo de modelo do ARM do ZipDeploy

Esse modelo inclui um slot de produção e de preparo e é implantado em um ou outro. Normalmente, você usará esse modelo para implantá-lo no slot de preparo e, em seguida, trocá-lo para que o novo pacote zip seja executado no slot de produção.

{
  "$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
      }
    }
  ]
}

Para a implantação inicial, você o implantará diretamente no slot de produção. Para obter mais informações, confira Implantações de slot.

Executar funções do pacote de implantação

Você também pode optar por executar suas funções diretamente do arquivo do pacote de implantação. Este método ignora a etapa de implantação de copiar os arquivos do pacote para o diretório wwwroot de seu aplicativo de funções. Em vez disso, o arquivo de pacote é montado pelo runtime do Azure Functions e o conteúdo do diretório wwwroot se torna somente leitura.

A implantação de zip integra-se com esse recurso, que você pode habilitar definindo a configuração do aplicativo de funções WEBSITE_RUN_FROM_PACKAGE com um valor de 1. Para obter mais informações, veja Executar suas funções de um arquivo de pacote de implantação.

Personalização da implantação

O processo de implantação presume que o arquivo .zip em que você efetua push contém um aplicativo pronto para execução. Por padrão, nenhuma personalização é executada. Para habilitar os mesmos processos de compilação que você obtém com a integração contínua, adicione o seguinte para as configurações do aplicativo:

SCM_DO_BUILD_DURING_DEPLOYMENT=true

Quando você usar a implantação por push do .zip, essa configuração é falsa por padrão. O padrão é verdadeiro para implantações de integração contínua. Quando definido como verdadeiras, as configurações de implantação são usadas durante a implantação. Você pode configurar essas configurações como configurações de aplicativo ou em um arquivo de configuração de .deployment localizado na raiz do seu arquivo .zip. Para obter mais informações, consulte Repositório e configurações relacionadas à implantação na referência de implantação.

Baixe seus arquivos de aplicativo de funções

Se você criou suas funções usando o editor no portal do Azure, você pode baixar seu projeto de aplicativo de funções existente como um arquivo. zip de uma das seguintes maneiras:

  • No Portal do Azure:

    1. Conecte-se no Portal do Azure e, em seguida, vá para o seu aplicativo de funções.

    2. Na guia Visão Geral, selecione Baixar conteúdo do aplicativo. Selecione as opções de download e, em seguida, selecione Baixar.

      Baixe o projeto de aplicativo de funções

      O arquivo .zip baixado está no formato correto para ser republicado no seu aplicativo de funções usando a implantação por push do .zip. O download do portal também pode adicionar os arquivos necessários para abrir o aplicativo de funções diretamente no Visual Studio.

  • Usando APIs REST:

    Use a seguinte API GET de implantação para baixar os arquivos de seu projeto <function_app>:

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

    Incluir /site/wwwroot/ assegura que o arquivo zip inclua somente os arquivos de projeto do aplicativo de funções e não todo o site. Se ainda não tiver se conectado ao Azure, será solicitado que você faça isso.

Você também pode baixar um arquivo .zip de um repositório do GitHub. Quando você baixa um repositório GitHub como um arquivo .zip, o GitHub adiciona um nível extra de pasta para o branch. Esse nível extra de pasta significa que você não pode implantar o arquivo .zip diretamente como baixou do GitHub. Se você estiver usando um repositório GitHub para manter seu aplicativo de funções, você deve usar a integração contínua para implantar seu aplicativo.

Próximas etapas

Executar funções por meio de um arquivo de pacote no Azure