Como definir as versões do runtime das Funções do Azure

Um aplicativo de função é executado em uma versão específica do tempo de execução do Funções do Azure. Por padrão, as aplicações de funções são criadas na versão mais recente 4.x do runtime de funções. As suas aplicações funcionais são suportadas apenas quando são executadas numa versão principal suportada. Este artigo explica como configurar uma aplicação de funções no Azure para direcionar, ou fixar a uma versão específica do runtime das Funções, quando necessário.

Considerações

Tenha estas considerações em mente ao considerar uma versão específica de tempo de execução:

O plano Flex Consumption apenas é compatível com a versão 4.x do runtime. Como o plano Flex Consumption não suporta a FUNCTIONS_EXTENSION_VERSION definição da aplicação, a sua aplicação não pode direcionar uma versão de execução específica ao correr neste plano.
A maneira como você segmenta uma versão específica depende se você está executando o Windows ou Linux.
Este artigo é específico para Windows ou Linux. Escolha o seu sistema operativo na parte superior do artigo.
Quando possível, execute sempre a sua aplicação na versão de execução mais recente suportada. Fixe a sua aplicação numa versão específica apenas se for instruído a fazê-lo devido a um problema com a versão mais recente. Sempre mude para a versão de tempo de execução mais recente assim que suas funções puderem ser executadas corretamente.
Durante o desenvolvimento local, sua versão instalada das Ferramentas Principais do Funções do Azure deve corresponder à versão principal do tempo de execução usada pelo aplicativo de função no Azure. Para obter mais informações, consulte Versões das ferramentas principais.

Atualize a sua versão do runtime

Quando possível, execute sempre as suas aplicações de funções na versão mais recente suportada do runtime Funções do Azure. Se a sua aplicação de funções estiver atualmente a correr numa versão mais antiga do runtime, migre a sua aplicação para a versão 4.x.

Quando seu aplicativo tiver funções existentes, você deve tomar precauções antes de passar para uma versão de tempo de execução principal posterior. Os artigos a seguir detalham as alterações de quebra entre as versões principais, incluindo alterações de quebra específicas do idioma. Eles também fornecem instruções passo a passo para uma migração bem-sucedida do seu aplicativo de função existente.

Para determinar sua versão atual do tempo de execução, consulte Exibir a versão atual do tempo de execução.

Ver a versão atual do runtime

Você pode exibir a versão atual do tempo de execução do seu aplicativo de função de uma destas maneiras:

Para exibir e atualizar a versão de tempo de execução atualmente usada por um aplicativo de função, siga estas etapas:

No portal do Azure, navegue até à sua aplicação de funções.
Expanda Configurações e selecione Configuração.
No separador Definições do runtime da função, tome nota da Versão do runtime. Neste exemplo, a versão é definida como ~4.

Você pode exibir a FUNCTIONS_EXTENSION_VERSION configuração do aplicativo na CLI do Azure.

Usando a CLI do Azure, exiba a versão atual do tempo de execução com o az functionapp config appsettings list comando:

az functionapp config appsettings list --name <function_app> \
--resource-group <my_resource_group>

Neste código, substitua <function_app> pelo nome do seu aplicativo de função. Substitua <my_resource_group> também pelo nome do grupo de recursos do seu aplicativo de função.

Você vê o FUNCTIONS_EXTENSION_VERSION na seguinte saída parcial:

[
  {
    "name": "FUNCTIONS_EXTENSION_VERSION",
    "slotSetting": false,
    "value": "~4"
  },
  {
    "name": "FUNCTIONS_WORKER_RUNTIME",
    "slotSetting": false,
    "value": "dotnet"
  },
  
  ...
]

Selecione Open Cloud Shell no exemplo de código anterior para executar o comando no Azure Cloud Shell. Você também pode executar a CLI do Azure localmente para executar esse comando. Ao executar localmente, você deve primeiro executar az login para entrar.

Para verificar o tempo de execução do Funções do Azure, use o seguinte cmdlet:

Get-AzFunctionAppSetting -Name "<FUNCTION_APP>" -ResourceGroupName "<RESOURCE_GROUP>"

Substitua <FUNCTION_APP> pelo nome do seu aplicativo de função e <RESOURCE_GROUP>. O valor atual da definição FUNCTIONS_EXTENSION_VERSION é devolvido na tabela hash.

Fixar em uma versão específica

O Funções do Azure permite utilizar a definição da aplicação FUNCTIONS_EXTENSION_VERSION para especificar a versão do runtime utilizada por uma determinada aplicação de funções. Se especificar apenas a versão principal (~4), a aplicação de funções atualiza-se automaticamente para novas versões menores do runtime à medida que estas ficam disponíveis. As atualizações de versões menores são automáticas porque as novas versões menores dificilmente vão introduzir alterações que quebrem as suas funções.

As aplicações Linux usam a linuxFxVersion configuração do site juntamente com FUNCTIONS_EXTENSION_VERSION para determinar a imagem base correta do Linux onde executam as suas funções. Quando cria uma nova aplicação de funções no Linux, o ambiente de execução escolhe automaticamente a imagem de base correta com base na versão do ambiente de execução da stack de linguagem.

Fixar numa versão específica em tempo de execução reinicia a tua aplicação de funções.

Quando especificas uma versão menor específica (como 4.0.12345) em FUNCTIONS_EXTENSION_VERSION, fixas a function app nessa versão específica do runtime até escolheres explicitamente voltar para atualizações automáticas de versão. Fixe apenas uma versão menor específica tempo suficiente para resolver quaisquer problemas da sua aplicação de funções que o impeça de direcionar a versão principal. As versões secundárias mais antigas são regularmente removidas do ambiente de produção. Quando a sua aplicação de funções é fixada a uma versão menor que mais tarde é removida, a sua aplicação de funções corre na versão existente mais próxima em vez da versão definida em FUNCTIONS_EXTENSION_VERSION. Anúncios do App Service comunicam a remoção de versões menores.

Nota

Quando tenta publicar, a partir do Visual Studio, para uma aplicação associada a uma versão secundária específica do runtime, é apresentada uma caixa de diálogo a pedir-lhe para atualizar para a versão mais recente ou cancelar a publicação. Para evitar esta verificação quando tiver de utilizar uma versão secundária específica, adicione a propriedade <DisableFunctionExtensionVersionUpdate>true</DisableFunctionExtensionVersionUpdate> ao seu ficheiro .csproj.

Use um destes métodos para fixar temporariamente seu aplicativo em uma versão específica do tempo de execução:

Para exibir e atualizar a versão de tempo de execução atualmente usada por um aplicativo de função, siga estas etapas:

No portal do Azure, navegue até à sua aplicação de funções.
Expanda Configurações e selecione Configuração.
No separador Definições do runtime da função, tome nota da Versão do runtime. Neste exemplo, a versão é definida como ~4.

Para fixar seu aplicativo em uma versão secundária específica, no painel esquerdo, expanda Configurações e selecione Variáveis de ambiente.
Na guia Configurações do aplicativo , selecione FUNCTIONS_EXTENSION_VERSION, altere Valor para a versão secundária necessária e selecione Aplicar.
Selecione Aplicar e, em seguida, selecione Confirmar para aplicar as alterações e reiniciar a aplicação.

Atualize as FUNCTIONS_EXTENSION_VERSION definições da aplicação na aplicação de funções usando o comando az-functionapp config appsettings.

az functionapp config appsettings set --name <FUNCTION_APP> \
--resource-group <RESOURCE_GROUP> \
--settings FUNCTIONS_EXTENSION_VERSION=<VERSION>

Substitua <FUNCTION_APP> pelo nome do seu aplicativo de função e <RESOURCE_GROUP> pelo nome do grupo de recursos do seu aplicativo de função. Além disso, substitua <VERSION> pela versão secundária específica que você precisa segmentar temporariamente.

Use este script para fixar o tempo de execução do Functions:

Update-AzFunctionAppSetting -Name "<FUNCTION_APP>" -ResourceGroupName "<RESOURCE_GROUP>" -AppSetting @{"FUNCTIONS_EXTENSION_VERSION" = "<VERSION>"} -Force

O aplicativo de função é reiniciado depois que a alteração é feita na configuração do aplicativo.

Para fixar a sua aplicação de funções a uma versão de runtime específica no Linux, defina uma URL de imagem base específica para a versão nas linuxFxVersion definições do site , no formato DOCKER|<PINNED_VERSION_IMAGE_URI>.

Importante

Os aplicativos de função fixa no Linux não recebem atualizações regulares de segurança e funcionalidade do host. Salvo recomendação de um profissional de suporte, utilize a configuração FUNCTIONS_EXTENSION_VERSION e um valor linuxFxVersion padrão para o seu idioma e versão, como Python|3.12. Para valores válidos, consulte o linuxFxVersion artigo de referência.

Atualmente, não há suporte para fixar em um tempo de execução específico para aplicativos de função Linux executados em um plano de consumo.

O exemplo seguinte mostra o valor linuxFxVersion necessário para fixar uma aplicação de funções Node.js 22 numa versão específica do runtime 4.14.0.3:

DOCKER|mcr.microsoft.com/azure-functions/node:4.14.0.3-node22

Quando necessário, um profissional de suporte pode fornecer um URI de imagem base válido para seu aplicativo.

Use os seguintes comandos da CLI do Azure para exibir e definir o linuxFxVersion. No momento, você não pode definir linuxFxVersion no portal ou usando o Azure PowerShell:

Para ver a versão atual do ambiente de execução, use o comando az functionapp config show:
```
az functionapp config show --name <function_app> \
--resource-group <my_resource_group> --query 'linuxFxVersion' -o tsv
```
Neste código, substitua <function_app> pelo nome do seu aplicativo de função. Além disso, substitua <my_resource_group> pelo nome do grupo de recursos do seu aplicativo de função. O valor atual de linuxFxVersion é retornado.
Para atualizar a configuração linuxFxVersion na aplicação Function App, use o comando az functionapp config set:
```
az functionapp config set --name <FUNCTION_APP> \
--resource-group <RESOURCE_GROUP> \
--linux-fx-version <LINUX_FX_VERSION>
```
Substitua <FUNCTION_APP> pelo nome do seu aplicativo de função. Além disso, substitua <RESOURCE_GROUP> pelo nome do grupo de recursos do seu aplicativo de função. Finalmente, substitua <LINUX_FX_VERSION> pelo valor de uma imagem específica fornecida a você por um profissional de suporte.

Você pode executar esses comandos do Azure Cloud Shell escolhendo Open Cloud Shell nos exemplos de código anteriores. Também pode usar a CLI do Azure localmente para executar este comando depois de executar az login e iniciar sessão.

O aplicativo de função é reiniciado depois que a alteração é feita na configuração do site.

Atualizar a imagem Linux gerida

Esta secção aplica-se apenas a aplicações Python 3.11 e Java 8, 11 ou 17 existentes em planos Linux Elastic Premium ou Dedicated (App Service) que utilizam uma imagem gerida pelo Debian Bullseye. Se a sua aplicação não cumprir todas estas condições, não tem de seguir este procedimento.

A imagem gerida mais recente permite que uma aplicação afetada permaneça temporariamente na sua versão linguística atual, ao mesmo tempo que é migrada para uma distribuição Linux suportada. Este procedimento não se aplica ao Flex Consumption nem a aplicações de contentores personalizados. Para uma aplicação no plano Linux Consumption, migre para o plano Flex Consumption.

Esta atualização seleciona a distribuição Linux para a versão de idioma existente utilizando um valor de três partes linuxFxVersion. Não fixa o host de Funções a uma imagem específica DOCKER|<IMAGE_URI> .

Escolha um valor Bookworm ou Noble `linuxFxVersion`

Primeiro, determine se pode atualizar a versão da língua ou se precisa de manter a versão atual e selecione uma distribuição Linux mais recente.

Considere atualizar a aplicação para uma versão de idioma mais recente suportada. Após uma atualização do idioma, a aplicação utiliza a imagem gerida predefinida atual para essa versão do idioma.

Se a aplicação tiver de se manter na versão atual da língua, escolha o valor de imagem mais recente correspondente:

Versão linguística	Valor de Debian Bullseye	Distribuição mais recente	Valor da imagem mais recente
Python 3.11	`Python\\|3.11\\|2.0`	Debian Bookworm	`Python\\|3.11\\|3.0`
Java 8	`Java\\|8\\|2.0`	Ubuntu Noble	`Java\\|8\\|4.0`
Java 11	`Java\\|11\\|2.0`	Ubuntu Noble	`Java\\|11\\|4.0`
Java 17	`Java\\|17\\|2.0`	Ubuntu Noble	`Java\\|17\\|4.0`

Estes valores em três partes selecionam explicitamente a imagem Linux gerida para estas imagens da era Bullseye. Eles não são devolvidos pelo az functionapp list-runtimes comando.

Teste a imagem Linux gerida mais recente

Teste a sua aplicação e as suas dependências da imagem mais recente antes de atualizar a aplicação de produção.

Crie uma aplicação de teste separada ou crie um slot de deployment.
Implementa o mesmo código e configuração que a tua aplicação de produção usa na app de teste ou no slot.
Defina o valor da imagem mais recente seguindo os passos em Atualizar o valor da imagem. Quando usares um slot, inclui --slot <SLOT_NAME> em cada comando do CLI do Azure.
Invoca cada função e verifica se a aplicação arranca com sucesso, os disparos correm como esperado e as dependências nativas ou do sistema operativo carregam corretamente.

Atualizar o valor da imagem

Alterar o valor da imagem reinicia a aplicação de funções. Atualize a produção durante uma janela de manutenção, ou use um slot de implementação.

Veja o valor atual linuxFxVersion :
```
az functionapp config show --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --query linuxFxVersion --output tsv
```
Este comando devolve o valor armazenado na configuração do site. O valor devolvido pode conter apenas a linguagem e a versão da língua, como Python|3.11, em vez do valor em três partes que identifica a distribuição Linux. Se o valor não incluir a versão da imagem, siga os passos em Verificar a distribuição Linux para confirmar que a aplicação utiliza atualmente o Debian Bullseye.
Definir linuxFxVersion para o valor da imagem mais recente:
```
az functionapp config set --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --linux-fx-version "<LANGUAGE|VERSION|IMAGE_VERSION>"
```
Para Python 3.11 no Debian Bookworm, utilize Python|3.11|3.0. Para Java no Ubuntu Noble, use Java|8|4.0, Java|11|4.0, ou Java|17|4.0.
Espera que a aplicação reinicie.

Verificar a distribuição Linux

Verifica tanto o valor configurado como a distribuição Linux que executa a tua aplicação.

Confirme o valor atualizado linuxFxVersion :
```
az functionapp config show --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --query linuxFxVersion --output tsv
```
Como defines explicitamente um valor de três partes, este comando devolve exatamente o valor Bookworm ou Noble que selecionaste.
Abra o site Kudu da aplicação em https://<APP_NAME>.scm.azurewebsites.net.
Selecione Ambiente e reveja KUDU_ENV, ou abra uma sessão SSH e execute:
```
cat /etc/os-release
```
Confirme que o resultado identifica o Debian Bookworm para Python 3.11 ou o Ubuntu Noble para Java 8, 11 ou 17.
Invoca cada função e confirma que os gatilhos e dependências continuam a funcionar como esperado.

Repor a atualização da imagem Linux gerida

Se a imagem atualizada causar um problema de compatibilidade, restaure temporariamente o valor anterior linuxFxVersion enquanto resolve o problema.

Warning

O Debian Bullseye deixou de ser suportado após a sua data de fim de vida útil e não recebe atualizações de segurança. Use o rollback apenas como mitigação temporária e volte a uma imagem suportada o mais rapidamente possível.

Na tabela em Escolher um valor Bookworm ou NoblelinuxFxVersion, encontre o valor Debian Bullseye para a sua versão do idioma.

Defina linuxFxVersion para esse valor de Bullseye:

az functionapp config set --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --linux-fx-version "<BULLSEYE_LINUX_FX_VERSION>"

Espera que a aplicação reinicie e depois repete as verificações em Verificar a distribuição Linux.

Próximos passos

Notas de versão para versões do ambiente de execução

Comentários

Esta página foi útil?

Last updated on 2026-09-17