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

Artigo
06/01/2023

No Azure, você pode executar suas funções diretamente de um arquivo de pacote de implantação no aplicativo de funções. A outra opção é implantar os arquivos no diretório d:\home\site\wwwroot (Windows) ou /home/site/wwwroot (Linux) do aplicativo de funções.

Este artigo descreve os benefícios de executar suas funções de um pacote. Ele também mostra como habilitar essa funcionalidade em seu aplicativo de funções.

Benefícios da execução de um arquivo de pacote

Há vários benefícios na execução de um arquivo de pacote:

Reduz o risco de problemas de bloqueio de cópia de arquivo.
Pode ser implantado em um aplicativo de produção (com reinicialização).
Você pode ter certeza dos arquivos que estão em execução no seu aplicativo.
Melhora o desempenho das implantações do Azure Resource Manager.
Pode reduzir os tempos de inicialização a frio, particularmente para as funções de JavaScript com árvores de pacote npm grandes.

Para saber mais, veja este comunicado.

Habilitar funções para execução por meio de um pacote

Para habilitar seu aplicativo de funções para execução por meio de um pacote, adicione a configuração WEBSITE_RUN_FROM_PACKAGE às configurações do aplicativo de funções. A configuração WEBSITE_RUN_FROM_PACKAGE pode ter um dos seguintes valores:

Valor	Descrição
`1`	Indica que o aplicativo de funções é executado de um arquivo de pacote local implantado na pasta `d:\home\data\SitePackages` (Windows) ou `/home/data/SitePackages` (Linux) do aplicativo de funções.
`<URL>`	Define uma URL que é a localização remota do arquivo de pacote específico que você deseja executar. Necessária para aplicativos de funções em execução no Linux em um plano de Consumo.

A seguinte tabela indica as opções de WEBSITE_RUN_FROM_PACKAGE recomendadas para implantação em um sistema operacional e um plano de hospedagem específicos:

Plano de hospedagem	Windows	Linux
Consumo	`1` é altamente recomendado.	Apenas `<URL>` tem suporte.
Premium	O`1` é recomendado.	O`1` é recomendado.
Dedicado	O`1` é recomendado.	O`1` é recomendado.

Considerações gerais

O arquivo de pacote precisa ser formatado em .zip. No momento, não há suporte para os formatos Tar nem gzip.
A implantação do zip é recomendada.
Ao implantar seu aplicativo de funções no Windows, você deve definir WEBSITE_RUN_FROM_PACKAGE como 1 e publicar com a implantação de zip.
Quando você fizer a execução por meio de um pacote, a pasta wwwroot se tornará somente leitura e você receberá um erro ao gravar arquivos nesse diretório. Os arquivos também são somente leitura no portal do Azure.
No momento, o tamanho máximo de um arquivo de pacote de implantação é de 1 GB.
Não é possível usar o cache local durante a execução por meio de um pacote de implantação.
Se o projeto precisar usar o build remoto, não use a configuração de aplicativo WEBSITE_RUN_FROM_PACKAGE. Em vez disso, adicione a configuração de aplicativo SCM_DO_BUILD_DURING_DEPLOYMENT=true de personalização da implantação. No Linux, adicione também a configuração ENABLE_ORYX_BUILD=true. Para saber mais, confira Build remoto.

Observação

WEBSITE_RUN_FROM_PACKAGE não funciona com MSDeploy, conforme descrito aqui. Você receberá um erro durante a implantação, como ARM-MSDeploy Deploy Failed. Altere /MSDeploy para /ZipDeploy e esse erro será resolvido.

Adicionando a configuração WEBSITE_RUN_FROM_PACKAGE

Há várias maneiras de adicionar, atualizar e excluir configurações do aplicativo de funções:

As alterações nas configurações do aplicativo de funções exigem que o seu aplicativo de funções seja reiniciado.

Como usar WEBSITE_RUN_FROM_PACKAGE = 1

Esta seção fornece informações sobre como executar seu aplicativo de funções por meio de um arquivo de pacote local.

Considerações sobre a implantação por meio de um pacote local

O uso de um pacote local é a opção recomendada para execução do pacote de implantação, exceto no Linux hospedado em um plano de Consumo.
A implantação do zip é a maneira recomendada de carregar um pacote de implantação no seu site.
Quando você não estiver usando a implantação do zip, verifique se a pasta d:\home\data\SitePackages (Windows) ou /home/data/SitePackages (Linux) tem um arquivo chamado packagename.txt. Esse arquivo contém apenas o nome, sem nenhum espaço em branco, do arquivo de pacote na pasta que está em execução no momento.

Integração com a implantação do zip

Implantação do zip é um recurso do Serviço de Aplicativo do Azure que permite que você implante seu projeto de aplicativo de funções no diretório wwwroot. O projeto é empacotado como um arquivo de implantação .zip. As mesmas APIs podem ser usadas para implantar seu pacote na pasta d:\home\data\SitePackages (Windows) ou /home/data/SitePackages (Linux).

Com o valor de configuração de aplicativo WEBSITE_RUN_FROM_PACKAGE igual a 1, as APIs de implantação do zip copiam seu pacote para a pasta d:\home\data\SitePackages (Windows) ou /home/data/SitePackages (Linux) em vez de extrair os arquivos para d:\home\site\wwwroot (Windows) ou /home/site/wwwroot (Linux). Ele também cria o arquivo packagename.txt. Após uma reinicialização, o pacote é montado wwwroot como um sistema de arquivos somente leitura. Para obter mais informações sobre a implantação do zip, consulte Implantação de zip para o Azure Functions.

Observação

Quando ocorre uma implantação, uma reinicialização do aplicativo de funções é disparada. As execuções de função em execução durante a implantação são encerradas. Examine Melhore o desempenho e a confiabilidade do Azure Functions para aprender a gravar funções sem estado e defensivas.

Como usar WEBSITE_RUN_FROM_PACKAGE = URL

Esta seção fornece informações sobre como executar seu aplicativo de funções por meio de um pacote implantado em um ponto de extremidade de URL. Essa opção é a única com suporte para execução por meio de um pacote no Linux hospedado em um plano de Consumo.

Considerações sobre a implantação por meio de uma URL

Ao executar um aplicativo de funções no Windows, a configuração de aplicativo WEBSITE_RUN_FROM_PACKAGE = <URL> oferece um desempenho pior de inicialização a frio e não é recomendada.
Ao especificar uma URL, você também precisa sincronizar gatilhos manualmente depois de publicar um pacote atualizado.
O runtime do Functions precisa ter permissões para acessar a URL do pacote.
Você não deve implantar seu pacote no Armazenamento de Blobs do Azure como um blob público. Em vez disso, use um contêiner privado com uma SAS (Assinatura de Acesso Compartilhado) ou use uma identidade gerenciada para permitir que o runtime do Functions acesse o pacote.
Mantenha todas as URLs SAS usadas para implantação. Quando uma SAS expira, o pacote não pode mais ser implantado. Nesse caso, você deve gerar uma nova SAS e atualizar a configuração no aplicativo de funções. Você pode eliminar essa carga de gerenciamento usando uma identidade gerenciada.
Na execução em um plano Premium, lembre-se de eliminar a inicialização a frio.
Na execução em um plano Dedicado, verifique se você habilitou o Always On.
Você pode usar o Gerenciador de Armazenamento do Azure para carregar arquivos de pacote em contêineres de blob na sua conta de armazenamento.

Carregar um pacote manualmente no Armazenamento de Blobs

Para implantar um pacote compactado ao usar a opção URL, crie um pacote de implantação .zip compactado e carregue-o no destino. Este exemplo é implantado em um contêiner do Armazenamento de Blobs.

Crie um pacote .zip do projeto usando o utilitário de sua escolha.
No portal do Microsoft Azure, pesquise pelo nome da conta de armazenamento ou navegue até ele nas contas de armazenamento.
Na conta de armazenamento, selecione Contêineres em Armazenamento de dados.
Selecione + Contêiner para criar um novo contêiner de Armazenamento de Blobs do Azure em sua conta.
Na página Novo container, forneça um Nome (por exemplo, "implantações"), certifique-se de que o nível de acesso Público seja Particular e selecione Criar.
Selecione o contêiner criado, selecione Upload, navegue até o local do arquivo .zip criado com seu projeto e selecione Upload.
Após a conclusão do upload, selecione o arquivo de blob carregado e copie a URL. Talvez seja necessário gerar uma URL de SAS se você não está usando uma identidade
Pesquise pelo aplicativo de funções ou navegue até ele na página Aplicativo de funções.
No aplicativo de funções, selecione Configurações em Configurações.
Na guia Configurações de aplicativo, selecione Nova configuração de aplicativo
Insira o valor WEBSITE_RUN_FROM_PACKAGE em Nome e cole a URL do pacote no Armazenamento de Blobs do Azure como o Valor.
Selecione OK. Em seguida, selecione Salvar>Continuar para salvar a configuração e reiniciar o aplicativo.

Agora é possível executar a função no Azure para verificar se a implantação foi bem-sucedida usando o arquivo .zip do pacote de implantação.

O exemplo a seguir mostra um aplicativo de funções configurado para ser executado de um arquivo .zip hospedado no armazenamento de Blobs do Azure:

WEBSITE_RUN_FROM_ZIP app setting

Buscar um pacote do Armazenamento de Blobs do Azure usando uma identidade gerenciada

Os Armazenamento de Blobs do Azure pode ser configurado para autorizar solicitações com o Microsoft Entra ID. Isso significa que, em vez de gerar uma chave SAS com uma expiração, você pode usar a identidade gerenciada do aplicativo. Por padrão, será usada a identidade do aplicativo atribuída pelo sistema. Se você quiser especificar uma identidade atribuída pelo usuário, defina a configuração de aplicativo WEBSITE_RUN_FROM_PACKAGE_BLOB_MI_RESOURCE_ID como a ID do recurso dessa identidade. A configuração também pode aceitar "SystemAssigned" como um valor, embora isso seja o mesmo que omitir completamente a configuração.

Para permitir que o pacote seja buscado usando a identidade:

Verifique se o blob está configurado para acesso privado.
Conceda à identidade à função Leitor de Dados do Blob do Armazenamento com escopo no blob do pacote. Confira Atribuir uma função do Azure para acesso aos dados do blob para obter detalhes sobre como criar a atribuição de função.
Defina a configuração de aplicativo WEBSITE_RUN_FROM_PACKAGE como a URL do blob do pacote. O formato seria provavelmente "https://{nome-da-conta-de-armazenamento}.blob.core.windows.net/{nome-do-contêiner}/{caminho-do-pacote}" ou semelhante.

Próximas etapas

Implantação contínua para Azure Functions