Guia de referência do desenvolvedor do Azure Functions para aplicativos Python

O Azure Functions é um serviço de computação sem servidor que permite executar código controlado por eventos sem provisionar ou gerenciar a infraestrutura. As execuções de função são disparadas por eventos como solicitações HTTP, mensagens de fila, temporizadores ou alterações no armazenamento e são dimensionadas automaticamente com base na demanda.

Este guia se concentra especificamente na criação do Azure Functions baseado em Python e ajuda você a:

• Criar e executar aplicativos de funções localmente
• Entender o modelo de programação do Python
• Organizar e configurar seu aplicativo
• Implantar e monitorar seu aplicativo no Azure
• Aplicar práticas recomendadas para dimensionamento e desempenho

Procurando uma visão geral conceitual? Consulte a referência do desenvolvedor do Azure Functions.

Interessado em casos de uso do mundo real? Explore a página Cenários & Exemplos .

Como começar

Escolha o ambiente que se ajusta ao fluxo de trabalho e vá para o Azure Functions para Python:

• Início Rápido do Visual Studio Code
• Início Rápido das Principais Ferramentas

Compilando seu aplicativo de funções

Esta seção aborda os componentes essenciais para criar e estruturar seu aplicativo de funções python. Os tópicos incluem o modelo de programação, a estrutura do projeto, os gatilhos e as associações e o gerenciamento de dependências.

Modelo de programação

O Functions dá suporte a duas versões do modelo de programação do Python:

Versão	Descrição
2.x	Use uma abordagem baseada em decorador para definir gatilhos e associações diretamente no arquivo de código do Python. Você implementa cada função como um método global sem estado em um function_app.py arquivo ou um arquivo de blueprint referenciado. Essa versão do modelo é recomendada para novos aplicativos Python.
1.x	Você define gatilhos e associações para cada função em um arquivo separado function.json . Implemente cada função como um método global sem estado no arquivo de código do Python. Esta versão do modelo dá suporte a aplicativos herdados.

Este artigo tem como destino uma versão específica do modelo do Python. Escolha a versão desejada na parte superior do artigo.

Importante

Use o modelo de programação v2 para uma abordagem orientada a decoradores a fim de definir gatilhos e vinculações diretamente no seu código.

No modelo de programação do Python v1, cada função é definida como um método global sem main() estado dentro de um arquivo chamado __init__.py. Os gatilhos e associações da função são configurados separadamente em um function.json arquivo e os valores de associação name são usados como parâmetros em seu main() método.

Exemplo

Aqui está uma função simples que responde a uma solicitação HTTP:

# __init__.py
def main(req):
    user = req.params.get('user')
    return f'Hello, {user}!'

Este é o arquivo correspondente function.json :

{
    "scriptFile": "__init__.py",
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req",
            "methods": [
                "get",
                "post"
            ]
        },
        {
            "type": "http",
            "direction": "out",
            "name": "$return"
        }
    ]
}

Conceitos principais

• A função tem um único gatilho HTTP.
• O objeto HttpRequest contém cabeçalhos de solicitação, parâmetros de consulta, parâmetros de rota e o corpo da mensagem. Essa função obtém o valor do parâmetro de consulta name a partir do parâmetro params do objeto HttpRequest.
• Para enviar um nome neste exemplo, acrescente ?name={name} à URL da função exposta. Por exemplo, se estiver em execução localmente, a URL completa poderá ser semelhante a http://localhost:7071/api/http_trigger?name=Test. Para obter exemplos usando vínculos, consulte Gatilhos e Vínculos.

Use o azure-functions SDK e inclua anotações de tipo para melhorar o suporte ao IntelliSense e ao editor:

# __init__.py
import azure.functions as func

def http_trigger(req: func.HttpRequest) -> str:

# requirements.txt
azure-functions

A azure-functions biblioteca

A azure-functions biblioteca Python fornece os principais tipos usados para interagir com o runtime do Azure Functions. Para ver todos os tipos e métodos disponíveis, visite a azure-functions API. Seu código de função pode usar azure-functions para:

• Acessar dados de entrada do gatilho (por exemplo, HttpRequest, TimerRequest)
• Criar valores de saída (como HttpResponse)
• Interagir com dados de associação e contexto fornecidos por runtime

Se você estiver usando azure-functions no seu aplicativo, ele deverá ser incluído nas dependências do projeto.

Observação

A azure-functions biblioteca define a superfície de programação para o Python Azure Functions, mas não é um SDK de uso geral. Use-o especificamente para criar e executar funções no runtime do Azure Functions.

Ponto de entrada alternativo

Você pode alterar o comportamento padrão de uma função especificando as propriedades scriptFile e entryPoint no arquivo function.json. Por exemplo, o arquivo a seguir function.json direciona o runtime para usar o custom_entry() método no main.py arquivo como o ponto de entrada para sua função do Azure.

{
  "scriptFile": "main.py",
  "entryPoint": "custom_entry",
  "bindings": [
      ...
  ]
}

Estrutura de pastas

Use a seguinte estrutura para um projeto do Python Azure Functions:

<project_root>/
│
├── .venv/                   # (Optional) Local Python virtual environment
├── .vscode/                 # (Optional) VS Code workspace settings
│
├── my_first_function/       # Function directory
│   └── __init__.py          # Function code file
│   └── function.json        # Function binding configuration file
│
├── my_second_function/
│   └── __init__.py  
│   └── function.json 
│
├── shared/                  # (Optional) Pure helper code with no triggers/bindings
│   └── utils.py
│
├── additional_functions/    # (Optional) Contains blueprints for organizing related Functions
│   └── blueprint_1.py  
│
├── tests/                   # (Optional) Unit tests for your functions
│   └── test_my_function.py
│
├── .funcignore              # Excludes files from being published
├── host.json                # Global function app configuration
├── local.settings.json      # Local-only app settings (not published)
├── requirements.txt         # (Optional) Defines Python dependencies for remote build
├── Dockerfile               # (Optional) For custom container deployment

Arquivos e pastas de chave

Arquivo / Pasta	Descrição	Necessário para que o aplicativo seja executado no Azure
my_first_function/	Diretório para uma única função.	✅
__init__.py/	Script principal em que o código da my_first_function função é definido.	✅
function.json/	Contém a configuração de associação para a my_first_function função.	✅
host.json	Configuração global para todas as funções no aplicativo.	✅
requirements.txt	Dependências do Python instaladas durante a publicação ao usar o build remoto.	❌ (recomendado para o gerenciamento de pacotes)
local.settings.json	Configurações e segredos de aplicativo de uso local apenas (que nunca são publicados).	❌ (necessário para desenvolvimento local)
.funcignore	Especifica arquivos e pastas a serem excluídos da implantação (por exemplo, .venv/, , tests/). local.settings.json	❌ (recomendada)
.venv/	Ambiente virtual local para Python (excluído da implantação).	❌
.vscode/	Configuração do editor para Visual Studio Code. Não é necessário para implantação.	❌
shared/	Contém o código auxiliar compartilhado no projeto aplicativo de funções	❌
additional_functions/	Usado para a organização de código modular, normalmente com blueprints.	❌
tests/	Testes de unidade para seu aplicativo de funções. Não publicado no Azure.	❌
Dockerfile	Define um contêiner personalizado para implantação.	❌

No modelo de programação do Python v2, o Azure Functions usa uma abordagem baseada em decorador para definir gatilhos e associações diretamente em seu código. Cada função é implementada como um método global sem estado em um function_app.py arquivo.

Exemplo

Aqui está uma função simples que responde a uma solicitação HTTP:

import azure.functions as func

app = func.FunctionApp()

@app.route("hello")
def http_trigger(req):
    user = req.params.get("user")
    return f"Hello, {user}!"

# requirements.txt
azure-functions

Conceitos principais

• O código importa o azure-functions pacote e usa decoradores e tipos para definir o aplicativo de funções.
• A função tem um único gatilho HTTP.
• O objeto HttpRequest contém cabeçalhos de solicitação, parâmetros de consulta, parâmetros de rota e o corpo da mensagem. Essa função obtém o valor do parâmetro de consulta name a partir do parâmetro params do objeto HttpRequest.
• Para enviar um nome neste exemplo, acrescente ?name={name} à URL da função exposta. Por exemplo, se estiver em execução localmente, a URL completa poderá ser semelhante a http://localhost:7071/api/http_trigger?name=Test. Para obter exemplos usando vínculos, consulte Gatilhos e Vínculos.

A azure-functions biblioteca

A azure-functions biblioteca python é uma parte central do modelo de programação do Azure Functions. Ele fornece os decoradores, tipos de gatilho e associação e objetos de solicitação/resposta usados para definir e interagir com funções em runtime. Para ver todos os tipos e decoradores disponíveis, visite azure-functions API. O código do aplicativo de funções depende dessa biblioteca para:

• Definir todas as funções usando o FunctionApp objeto
• Declarar gatilhos e associações (por exemplo, @app.route, @app.timer_trigger)
• Acesse entradas e saídas tipadas (como HttpRequest e HttpResponse, e Out`)

O azure-functions deve ser incluído nas dependências do seu projeto. Para saber mais, confira o gerenciamento de pacotes.

Observação

A azure-functions biblioteca define a superfície de programação para o Python Azure Functions, mas não é um SDK de uso geral. Use-o especificamente para criar e executar funções no runtime do Azure Functions.

Use anotações de tipo para melhorar o suporte ao IntelliSense e ao editor:

def http_trigger(req: func.HttpRequest) -> str:

Organizando com blueprints

Para aplicativos maiores ou modulares, use blueprints para definir funções em arquivos Python separados e registrá-los no aplicativo principal. Essa separação mantém seu código organizado e reutilizável.

Para definir e registrar um blueprint:

1. Defina um blueprint em outro arquivo python, como http_blueprint.py:

   import azure.functions as func
   
   bp = func.Blueprint()
   
   @bp.route(route="default_template")
   def default_template(req: func.HttpRequest) -> func.HttpResponse:
       return func.HttpResponse("Hello World!")
   

2. Registre o projeto no arquivo principal function_app.py :

   import azure.functions as func
   from http_blueprint import bp
   
   app = func.FunctionApp()
   app.register_functions(bp)
   

Usando blueprints (esquemas), você pode:

• Dividir seu aplicativo em módulos reutilizáveis
• Manter funções relacionadas agrupadas por arquivo ou recurso
• Estender ou compartilhar modelos entre projetos

Observação

O Durable Functions também dá suporte a blueprints usando azure-functions-durable. Ver exemplo →

Estrutura de pastas

Use a seguinte estrutura para um projeto do Python Azure Functions:

<project_root>/
│
├── .venv/                   # (Optional) Local Python virtual environment
├── .vscode/                 # (Optional) VS Code workspace settings
│
├── function_app.py          # Main function entry point (decorator model)
├── shared/                  # (Optional) Pure helper code with no triggers/bindings
│   └── utils.py
│
├── additional_functions/    # (Optional) Contains blueprints for organizing related Functions
│   └── blueprint_1.py  
│
├── tests/                   # (Optional) Unit tests for your functions
│   └── test_my_function.py
│
├── .funcignore              # Excludes files from being published
├── host.json                # Global function app configuration
├── local.settings.json      # Local-only app settings (not published)
├── requirements.txt         # (Optional) Defines Python dependencies for remote build
├── Dockerfile               # (Optional) For custom container deployment

Arquivos e pastas de chave

Arquivo/Pasta	Descrição	Necessário para que o aplicativo seja executado no Azure
function_app.py	Script principal onde as Azure Functions e seus gatilhos são definidos usando decoradores.	✅
host.json	Configuração global para todas as funções no aplicativo.	✅
requirements.txt	Dependências do Python instaladas durante a publicação ao usar o build remoto.	❌ (recomendado para o gerenciamento de pacotes)
local.settings.json	Configurações e segredos locais do aplicativo (nunca publicados).	❌ (necessário para desenvolvimento local)
.funcignore	Especifica arquivos e pastas a serem excluídos da implantação (por exemplo, .venv/, , tests/). local.settings.json	❌ (recomendada)
.venv/	Ambiente virtual local para Python (excluído da implantação).	❌
.vscode/	Configuração do editor para Visual Studio Code. Não é necessário para implantação.	❌
shared/	Contém o código auxiliar compartilhado no projeto Function App	❌
additional_functions/	Usado para a organização de código modular, normalmente com blueprints.	❌
tests/	Testes de unidade para seu aplicativo de funções. Não publicado no Azure.	❌
Dockerfile	Define um contêiner personalizado para implantação.	❌

[OBSERVAÇÃO!] Inclua um requirements.txt arquivo quando você implementa com o build remoto. Se você não usar o build remoto ou quiser usar outro arquivo para definir dependências de aplicativo, poderá executar um build local e implantar o aplicativo com dependências pré-criadas.

Para obter diretrizes sobre testes de unidade, consulte Teste de Unidade. Para implantações de contêiner, consulte Implantar com contêineres personalizados.

---

Gatilhos e associações

O Azure Functions usa gatilhos para iniciar a execução de funções e associações para conectar seu código a outros serviços, como armazenamento, filas e bancos de dados. No modelo de programação do Python v2, você declara associações usando decoradores.

Existem dois tipos principais de associações:

• Gatilhos (entrada de dados que inicia a execução da função)
• Entradas e saídas (fontes de dados ou destinos extras)

Para obter mais informações sobre os gatilhos e associações disponíveis, consulte Gatilhos e Associações no Azure Functions.

Exemplo: gatilho de temporizador com entrada de blob

Esta função:

• É acionado a cada 10 minutos
• Lê a partir de um blob usando vínculos de tipo SDK
• Armazena em cache resultados e gravações em um arquivo temporário

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob
import logging
import tempfile

CACHED_BLOB_DATA = None

app = func.FunctionApp()

@app.function_name(name="TimerTriggerWithBlob")
@app.schedule(schedule="0 */10 * * * *", arg_name="mytimer")
@app.blob_input(arg_name="client",
                path="PATH/TO/BLOB",
                connection="BLOB_CONNECTION_SETTING")
def timer_trigger_with_blob(mytimer: func.TimerRequest,
                            client: blob.BlobClient,
                            context: func.Context) -> None:
    global CACHED_BLOB_DATA
    if CACHED_BLOB_DATA is None:
        # Download blob and save as a global variable
        CACHED_BLOB_DATA = client.download_blob().readall()

        # Create temp file prefix
        my_prefix = context.invocation_id
        temp_file = tempfile.NamedTemporaryFile(prefix=my_prefix)
        temp_file.write(CACHED_BLOB_DATA)
        logging.info(f"Cached data written to {temp_file.name}")

Conceitos principais

• Use associações de tipo SDK para trabalhar com tipos avançados. Para obter mais informações, consulte associações de tipo do SDK.
• Você pode usar variáveis globais para armazenar em cache cálculos caros, mas seu estado não tem garantia de persistir entre execuções de função.
• Arquivos temporários são armazenados em tmp/ e não têm garantia de permanência entre invocações ou instâncias escaláveis.
• Você pode acessar o contexto de invocação de uma função por meio da classe Context.

Exemplo: gatilho HTTP com entrada do Cosmos DB e saída do Hub de Evento

Esta função:

• Gatilhos em uma solicitação HTTP
• Leituras de um Cosmos DB
• Grava em uma saída do Hub de Evento
• Retorna uma resposta HTTP

# __init__.py
import azure.functions as func

def main(req: func.HttpRequest,
         documents: func.DocumentList,
         event: func.Out[str]) -> func.HttpResponse:

    # Content from HttpRequest and Cosmos DB input
    http_content = req.params.get("body")
    doc_id = documents[0]["id"] if documents else "No documents found"

    event.set(f"HttpRequest content: {http_content} | CosmosDB ID: {doc_id}")

    return func.HttpResponse(
        "Function executed successfully.",
        status_code=200
    )

// function.json
{
  "scriptFile": "__init__.py",
  "entryPoint": "main",
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"],
      "route": "file"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "cosmosDB",
      "direction": "in",
      "name": "documents",
      "databaseName": "test",
      "containerName": "items",
      "id": "cosmosdb-input-test",
      "connection": "COSMOSDB_CONNECTION_SETTING"
    },
    {
      "type": "eventHub",
      "direction": "out",
      "name": "event",
      "eventHubName": "my-test-eventhub",
      "connection": "EVENTHUB_CONNECTION_SETTING"
    }
  ]
}

Principais conceitos

• Cada função tem um único gatilho, mas pode ter várias associações.
• Adicione entradas especificando o direction como "in" em function.json. As saídas têm um direction de out.
• Você pode acessar os detalhes da solicitação por meio do HttpRequest objeto e construir um personalizado HttpResponse com cabeçalhos, código de status e corpo.

import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="HttpTriggerWithCosmosDB")
@app.route(route="file")
@app.cosmos_db_input(arg_name="documents",
                     database_name="test",
                     container_name="items",
                     connection="COSMOSDB_CONNECTION_SETTING")
@app.event_hub_output(arg_name="event",
                      event_hub_name="my-test-eventhub",
                      connection="EVENTHUB_CONNECTION_SETTING")
def http_trigger_with_cosmosdb(req: func.HttpRequest,
                               documents: func.DocumentList,
                               event: func.Out[str]) -> func.HttpResponse:
    # Content from HttpRequest and Cosmos DB input
    http_content = req.params.get('body')
    doc_id = documents[0]['id']

    event.set("HttpRequest content: " + http_content
              + " | CosmosDB ID: " + doc_id)

    return func.HttpResponse(
        f"Function executed successfully.",
        status_code=200
    )

Conceitos principais

• Use @route() ou decoradores específicos do gatilho (@timer_trigger@queue_triggere outros) para definir como sua função é invocada.
• Adicione entradas usando decoradores como @blob_input, @queue_inpute outros.
• As saídas podem ser:
  • Retornado diretamente (se houver apenas uma saída)
  • Atribuído usando Out associações e o .set() método para várias saídas.
• Você pode acessar os detalhes da solicitação por meio do HttpRequest objeto e construir um personalizado HttpResponse com cabeçalhos, código de status e corpo.

Vinculações de tipo SDK

Para selecionar gatilhos e associações, você pode trabalhar com tipos de dados implementados pelos SDKs e estruturas subjacentes do Azure. Usando essas associações de tipo SDK, você pode interagir com dados de associação como se estivesse usando o SDK do serviço subjacente. Para obter mais informações, consulte tipos de associação de SDK suportados.

Importante

O suporte a associações de tipo SDK para Python só está disponível no modelo de programação python v2.

Variáveis de ambiente

As variáveis de ambiente no Azure Functions permitem gerenciar com segurança valores de configuração, cadeias de conexão e segredos do aplicativo sem codificar em seu código de função.

Você pode definir variáveis de ambiente:

• Localmente: no arquivo local.settings.json, durante o desenvolvimento local.
• No Azure: como Configurações de Aplicativo na página de configuração do aplicativo de funções no portal do Azure.

Acesse as variáveis diretamente em seu código usando os.environ ou os.getenv.

setting_value = os.getenv("myAppSetting", "default_value")

Observação

O Azure Functions também reconhece variáveis de ambiente do sistema que configuram o runtime do Functions e o comportamento do trabalho do Python. Essas variáveis não são usadas explicitamente em seu código de função, mas afetam a forma como seu aplicativo é executado. Para obter uma lista completa de variáveis de ambiente do sistema, veja a referência de configurações do aplicativo.

Gerenciamento de pacotes

Para usar outros pacotes do Python em seu aplicativo do Azure Functions, liste-os em um requirements.txt arquivo na raiz do projeto. Esses pacotes são importados pelo sistema de importação do Python e, em seguida, você pode referenciar esses pacotes como de costume. Para saber mais sobre opções de criação e implantação com dependências externas, consulte Opções de build para aplicativos de funções do Python.

Por exemplo, o exemplo a seguir mostra como o requests módulo é incluído e usado no aplicativo de funções.

<requirements.txt>
requests==2.31.0

Instale o pacote localmente com pip install -r requirements.txt.

Depois que o pacote for instalado, você poderá importá-lo e usá-lo no código da função:

import azure.functions as func
import requests

def main(req: func.HttpRequest) -> func.HttpResponse:
    r = requests.get("https://api.github.com")
    return func.HttpResponse(f"Status: {r.status_code}")

import azure.functions as func
import requests

app = func.FunctionApp()

@app.function_name(name="HttpExample")
@app.route(route="call_api")
def main(req: func.HttpRequest) -> func.HttpResponse:
    r = requests.get("https://api.github.com")
    return func.HttpResponse(f"Status: {r.status_code}")

Considerações

• Conflitos com módulos internos:
  • Evite nomear suas pastas de projeto após bibliotecas padrão do Python (por exemplo, email/, ). json/
  • Não inclua bibliotecas nativas do Python (como logging, asyncioou uuid) em requirements.txt.
• Implantação:
  • Para evitar ModuleNotFound erros, verifique se todas as dependências necessárias estão listadas em requirements.txt.
  • Se você atualizar a versão do Python do aplicativo, recompile e reimplante seu aplicativo na nova versão do Python para evitar conflitos de dependência com pacotes criados anteriormente.
• Dependências não PyPI:
  • Você pode incluir dependências que não estão disponíveis no PyPI em seu aplicativo, como pacotes locais, arquivos de roda ou feeds privados. Consulte dependências personalizadas no Python Azure Functions para obter instruções de instalação.
• Dependências do ambiente de trabalho do Python no Azure Functions:
  • Se o pacote contiver determinadas bibliotecas que podem colidir com as dependências do trabalho (por exemplo, protobuf ou grpcio), defina PYTHON_ISOLATE_WORKER_DEPENDENCIES para 1 nas configurações do aplicativo para impedir que seu aplicativo se refira às dependências do trabalhador. Para Python 3.13 e superior, esse recurso é habilitado por padrão.

Executando e implantando

Esta seção fornece informações sobre como executar funções localmente, suporte à versão do Python, opções de build e implantação e configuração de runtime. Use essas informações para executar com êxito seu aplicativo de funções em ambientes locais e do Azure.

Execução local

Você pode executar e testar seu aplicativo de funções Python em seu computador local antes de implantar no Azure.

Usando ferramentas principais do Azure Functions

Instale as Ferramentas Principais do Azure Functions e inicie o runtime local executando o func start comando na raiz do projeto:

func start

Quando você inicia o aplicativo de funções localmente, o Core Tools exibe todas as funções encontradas para seu aplicativo:

Functions:
        http_trigger:  http://localhost:7071/api/http_trigger

Você pode saber mais sobre como usar as Ferramentas Principais visitando o Develop Azure Functions localmente usando o Core Tools.

Invocando a função diretamente

Ao usar azure-functions >= 1.21.0, você também pode chamar funções diretamente usando o interpretador do Python sem executar o Core Tools. Essa abordagem é útil para testes rápidos de unidade:

# function_app.py
import azure.functions as func

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@app.route(route="http_trigger")
def http_trigger(req: func.HttpRequest) -> func.HttpResponse:
    return "Hello, World!"

# Test the function directly
print(http_trigger(None))

Para ver a saída, execute o arquivo diretamente com o Python:

> python function_app.py

Hello, World!

# __init__.py
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse("Hello, World!")

# Test the function directly
print(main(None))

Para ver a saída, execute o arquivo diretamente com o Python:

> python __init__.py

Hello, World!

Essa abordagem não requer nenhum pacote ou configuração extra e é ideal para validação rápida durante o desenvolvimento. Para obter testes mais detalhados, consulte Teste de Unidade

Versões do Python com suporte

O Azure Functions dá suporte às versões do Python listadas em idiomas com suporte no Azure Functions. Para obter mais informações gerais, consulte a política de suporte de runtime do Azure Functions.

Importante

Se você alterar a versão do Python para seu aplicativo de funções, deverá recompilar e reimplantar o aplicativo usando a nova versão. Artefatos e dependências de implantação existentes não são recriados automaticamente quando a versão do Python é alterada.

Compilação e Implantação

Para saber mais sobre o mecanismo de build recomendado para seu cenário, consulte Opções de Build. Para obter uma visão geral da implantação, consulte As tecnologias de implantação no Azure Functions.

Comparação rápida de mecanismos de implantação

Ferramenta/Plataforma	Comando/ação	Melhor caso de uso
Ferramentas principais do Azure Functions	func azure functionapp publish <APP_NAME>	Ideal para execuções de CI, automação local ou ao trabalhar entre plataformas.
AZ CLI	az functionapp deployment source config-zip	Útil ao criar scripts de implantações fora das Ferramentas Principais. Funciona bem em pipelines automatizados ou terminais baseados em nuvem (Azure Cloud Shell).
Visual Studio Code (Extensão do Azure Functions)	Paleta de comandos → "Azure Functions: Implantar no Azure..."	Melhor para iniciantes ou implantações interativas. Manipula automaticamente o empacotamento e a compilação.
Ações do GitHub	Azure/functions-action@v1	Ideal para CI/CD baseado no GitHub. Habilita implantações automatizadas em mesclagens por push ou PR.
Azure Pipelines	AzureFunctionApp@2 Tarefa	CI/CD Empresarial usando o Azure DevOps. Melhor indicado para fluxos de trabalho de lançamento controlados, builds com restrições e pipelines de múltiplos estágios.
Implantação de contêiner personalizado	Contêiner por push → az functionapp create --image <container>	Necessário quando você precisa de pacotes no nível do sistema operacional, compilações personalizadas do Python, tempos de execução fixos ou dependências não suportadas (por exemplo, bibliotecas do sistema, binários locais).
Criação de função baseada em portal	Criar função no portal do Azure → editor embutido	Use apenas para funções simples e sem dependência. Ótimo para demonstrações ou aprendizado, mas não recomendado para aplicativos que exigem pacotes de terceiros.

Observação

A Criação de Funções baseada em portal não dá suporte a dependências de terceiros e não é recomendada para criar aplicativos de produção. Não é possível instalar ou fazer referência a pacotes externos azure-functions e à biblioteca padrão interna do Python.

Importante

Após 30 de setembro de 2028, a opção de hospedar seu aplicativo de funções no Linux em um plano de consumo será desativada. Para evitar interrupções, migre seus aplicativos de plano de consumo existentes que são executados no Linux para o plano de consumo flex antes dessa data. Os aplicativos em execução no Windows em um plano de consumo não são afetados por essa alteração. Para obter mais informações, consulte o aviso de desativação do plano de consumo do Linux.

Atualizações do Python 3.13+

A partir do Python 3.13, o Azure Functions apresenta várias melhorias principais de desempenho e runtime que afetam a forma como você cria e executa seus aplicativos. As principais alterações incluem:

• Controle de versão de runtime: agora você pode opcionalmente fixar ou atualizar seu aplicativo para versões específicas do executador Python, referenciando o pacote azure-functions-runtime em seu requirements.txt.

  • Sem o controle de versão habilitado, seu aplicativo é executado em uma versão padrão do runtime do Python, que o Functions gerencia. Você deve modificar o arquivo requirements.txt para solicitar a versão mais recente lançada, uma versão pré-lançada ou para fixar seu aplicativo a uma versão específica do runtime do Python.

  • Habilite o controle de versão do runtime adicionando uma referência ao pacote de runtime do Python ao arquivo requirements.txt , em que o valor atribuído ao pacote determina a versão de runtime usada.

  • Evite fixar qualquer aplicativo de produção em versões de execução pré-lançamento (alfa, beta ou desenvolvimento).

  • Para estar ciente das alterações, examine as notas de versão do runtime do Python regularmente.

  • A tabela a seguir indica o comportamento de controle de versão com base no valor de versão dessa configuração em seu arquivo derequirements.txt :

    Versão	Example	Comportamento
    Nenhum conjunto de valores	azure-functions-runtime	Seu aplicativo Python 3.13+ é executado na versão mais recente disponível do runtime do Python do Functions. Essa opção é melhor para se manter atualizado com melhorias e recursos da plataforma, já que seu aplicativo recebe automaticamente as atualizações de runtime estáveis mais recentes.
    Fixado em uma versão específica	azure-functions-runtime==1.2.0	Seu aplicativo Python 3.13+ permanece na versão de runtime fixada e não recebe atualizações automáticas. Em vez disso, você deve atualizar manualmente sua versão fixada para aproveitar novos recursos, correções e melhorias no runtime. A fixação é recomendada para cargas de trabalho de produção críticas em que a estabilidade e a previsibilidade são essenciais. A ancoragem também permite que você teste seu aplicativo em versões de runtime pré-lançadas durante o desenvolvimento.
    Nenhuma referência de pacote	n/a	Ao não definir o azure-functions-runtime, o aplicativo Python 3.13+ é executado em uma versão padrão do ambiente de execução do Python que é anterior à versão mais recente lançada. As atualizações são feitas periodicamente pelo Functions. Essa opção garante estabilidade e ampla compatibilidade. No entanto, o acesso aos recursos e correções mais recentes é adiado até que a versão padrão seja atualizada.

• Isolamento de dependências: as dependências do aplicativo (como grpcio ou protobuf) são totalmente isoladas das dependências do trabalhador, evitando conflitos de versão. A configuração PYTHON_ISOLATE_WORKER_DEPENDENCIES do aplicativo não terá impacto para aplicativos em execução no Python 3.13 ou posterior.

• Configuração simplificada de streaming HTTP – nenhuma configuração de aplicativo especial necessária.

• Foi removido o suporte para extensões de trabalho e recursos de memória compartilhada.

• Controle de versão de runtime: agora você pode opcionalmente fixar ou atualizar seu aplicativo para versões específicas do trabalhador Python referenciando o azure-functions-runtime-v1 pacote em seu requirements.txt.

  • Sem o controle de versão habilitado, seu aplicativo é executado em uma versão padrão do runtime do Python, que o Functions gerencia. Você deve modificar o arquivo requirements.txt para solicitar a última versão lançada, uma versão pré-lançada, ou fixar seu aplicativo a uma versão específica do tempo de execução do Python.

  • Habilite o controle de versão do runtime adicionando uma referência ao pacote de runtime do Python ao arquivo requirements.txt , em que o valor atribuído ao pacote determina a versão de runtime usada.

  • Evite fixar qualquer aplicativo de produção em versões de runtime em pré-lançamento (alfa, beta ou de desenvolvimento).

  • Para estar ciente das alterações, examine as notas de versão do runtime do Python regularmente.

  • A tabela a seguir indica o comportamento de controle de versão com base no valor de versão dessa configuração em seu arquivo derequirements.txt :

    Versão	Example	Comportamento
    Nenhum conjunto de valores	azure-functions-runtime-v1	Seu aplicativo Python 3.13+ é executado na versão mais recente disponível do runtime do Python do Functions. Essa opção é melhor para se manter atualizado com melhorias e recursos da plataforma, já que seu aplicativo recebe automaticamente as atualizações de runtime estáveis mais recentes.
    Fixado em uma versão específica	azure-functions-runtime-v1==1.2.0	Seu aplicativo Python 3.13+ permanece na versão de runtime fixada e não recebe atualizações automáticas. Em vez disso, você deve atualizar manualmente sua versão fixada para aproveitar novos recursos, correções e melhorias no runtime. A fixação é recomendada para cargas de trabalho de produção críticas em que a estabilidade e a previsibilidade são essenciais. A ancoragem também permite que você teste seu aplicativo em versões de runtime pré-lançadas durante o desenvolvimento.
    Nenhuma referência de pacote	n/a	Ao não definir o azure-functions-runtime-v1, seu aplicativo Python 3.13+ é executado em uma versão padrão do runtime do Python que está atrás da versão mais recente lançada. As atualizações são feitas periodicamente pelo Functions. Essa opção garante estabilidade e ampla compatibilidade. No entanto, o acesso aos recursos e correções mais recentes é adiado até que a versão padrão seja atualizada.

• Isolamento de dependência: as dependências do aplicativo (como grpcio ou protobuf) são totalmente isoladas das dependências do trabalhador, evitando conflitos de versões. A configuração PYTHON_ISOLATE_WORKER_DEPENDENCIES do aplicativo não terá impacto para aplicativos em execução no Python 3.13 ou posterior.

• Foi removido o suporte para extensões de trabalho e recursos de memória compartilhada.

Observabilidade e teste

Esta seção aborda os recursos de registro em log, monitoramento e teste para ajudá-lo a depurar problemas, acompanhar o desempenho e garantir a confiabilidade dos aplicativos de funções do Python.

Registro e monitoramento

O Azure Functions expõe um agente raiz que você pode usar diretamente com o módulo embutido do próprio Python logging. Todas as mensagens escritas usando esse agente são enviadas automaticamente ao Application Insights quando seu aplicativo está em execução no Azure.

O registro em log permite capturar informações de runtime e diagnosticar problemas sem precisar de mais nenhuma configuração.

Exemplo de registro em log com um gatilho HTTP

import logging
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.debug("Example debug log")
    logging.info("Example info log")
    logging.warning("Example warning")
    logging.error("Example error log")
    return func.HttpResponse("OK")

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="http_trigger")
def http_trigger(req) -> func.HttpResponse:
    logging.debug("Example debug log")
    logging.info("Example info log")
    logging.warning("Example warning")
    logging.error("Example error log")
    return func.HttpResponse("OK")

Você pode usar o conjunto completo de níveis de log (debug, info, warning, error, critical), e eles são exibidos no portal do Azure em Logs ou Application Insights.

Para saber mais sobre como monitorar o Azure Functions no portal, consulte Monitorar o Azure Functions.

Observação

Para exibir logs de depuração no Application Insights, mais configuração é necessária. Você pode habilitar esse recurso definindo PYTHON_ENABLE_DEBUG_LOGGING1 e definindo logLevel para trace ou debug em seu arquivohost.json. Por padrão, os logs de depuração não são visíveis no Application Insights.

Registro de threads em segundo plano

Se a sua função iniciar um novo thread e precisar registrar a partir desse thread, certifique-se de passar o context argumento no thread. Contém context o armazenamento local de thread e o atual invocation_id, que deve ser definido no thread de trabalho para que os logs sejam associados corretamente à execução da função.

import logging
import threading
import azure.functions as func

def main(req: func.HttpRequest, context) -> func.HttpResponse:
    logging.info("Function started")
    t = threading.Thread(target=log_from_thread, args=(context,))
    t.start()
    return "okay"

def log_from_thread(context):
    # Associate the thread with the current invocation
    context.thread_local_storage.invocation_id = context.invocation_id  
    logging.info("Logging from a background thread")

import azure.functions as func
import logging
import threading

app = func.FunctionApp()

@app.route(route="http_trigger")
def http_trigger(req, context) -> func.HttpResponse:
    logging.info("Function started")
    t = threading.Thread(target=log_from_thread, args=(context,))
    t.start()
    return "okay"

def log_from_thread(context):
    # Associate the thread with the current invocation
    context.thread_local_storage.invocation_id = context.invocation_id  
    logging.info("Logging from a background thread")

Configurando registradores personalizados

Você pode configurar agentes personalizados no Python quando precisar de mais controle sobre o comportamento de log, como formatação personalizada, filtragem de log ou integrações de terceiros. Para configurar um agente personalizado, use o Python logging.getLogger() com um nome personalizado e adicione manipuladores ou formatadores conforme necessário.

import logging

custom_logger = logging.getLogger('my_custom_logger')

Suporte ao OpenTelemetry

O Azure Functions para Python também dá suporte ao OpenTelemetry, que permite emitir rastreamentos, métricas e logs em um formato padronizado. O uso do OpenTelemetry é especialmente valioso para aplicativos distribuídos ou cenários em que você deseja exportar telemetria para ferramentas fora do Application Insights (como Grafana ou Jaeger).

Consulte nosso Início Rápido do OpenTelemetry para Azure Functions (Python) para obter instruções de instalação e código de exemplo.

Teste de unidade

Escreva e execute testes de unidade para suas funções usando pytest. Você pode testar funções do Python como outro código Python usando estruturas de teste padrão. Para a maioria das associações, você pode criar um objeto de entrada fictício criando uma instância de uma classe apropriada a partir do azure.functions pacote.

my_function Usando como exemplo, o exemplo a seguir é um teste simulado de uma função disparada por HTTP:

Primeiro, crie o <arquivo project_root>/function_app.py e implemente a my_function função como o gatilho HTTP.

# <project_root>/function_app.py
import azure.functions as func
import logging

app = func.FunctionApp()

# Define the HTTP trigger that accepts the ?value=<int> query parameter
# Double the value and return the result in HttpResponse
@app.function_name(name="my_function")
@app.route(route="hello")
def my_function(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Executing myfunction.')

    initial_value: int = int(req.params.get('value'))
    doubled_value: int = initial_value * 2

    return func.HttpResponse(
        body=f"{initial_value} * 2 = {doubled_value}",
        status_code=200
    )

Comece gravando casos de teste para seu gatilho HTTP.

# <project_root>/test_my_function.py
import unittest
import azure.functions as func

from function_app import my_function

class TestFunction(unittest.TestCase):
  def test_my_function(self):
    # Construct a mock HTTP request.
    req = func.HttpRequest(method='GET',
                           body=None,
                           url='/api/my_function',
                           params={'value': '21'})
    # Call the function.
    func_call = main.build().get_user_function()
    resp = func_call(req)
    # Check the output.
    self.assertEqual(
        resp.get_body(),
        b'21 * 2 = 42',
    )

Dentro da pasta de ambiente virtual do Python, você pode executar os seguintes comandos para testar o aplicativo:

pip install pytest
pytest test_my_function.py

Você verá os pytest resultados no terminal, desta forma:

============================================================================================================ test session starts ============================================================================================================
collected 1 item                                                                                                                                                                                                                             

test_my_function.py .                                                                                                                                                                                                                  [100%] 
============================================================================================================= 1 passed in 0.24s ============================================================================================================= 

Otimização e tópicos avançados

Para saber mais sobre como otimizar seus aplicativos de funções do Python, confira estes artigos:

• Dimensionamento & Desempenho
• Usando o Flask Framework com o Azure Functions
• Funções duráveis
• HTTP Streaming

Artigos relacionados

Para obter mais informações sobre funções, consulte estes artigos:

• Documentação da API do pacote do Azure Functions
• Práticas recomendadas para o Azure Functions
• Gatilhos e associações de Azure Functions
• Associações do Armazenamento de Blobs
• Associações HTTP e webhook
• Associações de Armazenamento de Filas
• Gatilhos de temporizador

Problemas com o uso do Python? Informe-nos e registre um problema.