Implantação de zip para o Azure Functions
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.
Requisitos de implantação de arquivo .zip
O arquivo .zip que você usa para a implantação de push precisa conter todos os arquivos necessários para executar sua função.
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.
O código para todas as funções em um aplicativo de funções específico está localizado em uma pasta do projeto raiz que contém um arquivo de configuração do host. O arquivo host.json contém configurações específicas de runtime, além de estar na pasta raiz do aplicativo de funções. Uma pasta bin contém pacotes e outros arquivos de biblioteca que o aplicativo de funções requer. As estruturas de pastas específicas exigidas pelo aplicativo de funções dependem da linguagem:
Todas as funções no aplicativo de função devem compartilhar a mesma pilha de linguagem.
Um aplicativo de funções contém todos os arquivos e pastas no diretório wwwroot. Uma implantação de arquivo. zip inclui o conteúdo do diretório wwwroot, mas não o diretório em si. Ao implantar um projeto de biblioteca de classes C#, você deve incluir os arquivos de biblioteca compilados e as dependências em uma subpasta bin em seu pacote .zip.
Ao desenvolver em um computador local, você pode criar manualmente um arquivo .zip da pasta de projeto do aplicativo de funções usando a funcionalidade de compactação .zip interna ou ferramentas de terceiros.
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:
Conecte-se no Portal do Azure e, em seguida, vá para o seu aplicativo de funções.
Na guia Visão Geral, selecione Baixar conteúdo do aplicativo. Selecione as opções de download e, em seguida, selecione Baixar.
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.