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

Como começar

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

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

No modelo de programação Python v1, cada função é definida como um método main() global sem 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 biblioteca azure-functions Python fornece os tipos principais usados para interagir com o runtime 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.

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 function.json a seguir direciona o runtime para usar o método custom_entry() no arquivo main.py como o ponto de entrada para sua função de Azure.

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

Estrutura de pastas

Use a seguinte estrutura para um projeto de 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

No modelo de programação Python v2, Azure Functions usa uma abordagem baseada em decorator 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 biblioteca azure-functions Python é uma parte central do modelo de programação 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.

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á-las 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

Estrutura de pastas

Use a seguinte estrutura para um projeto de 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

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.

# __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 Azure SDKs e estruturas subjacentes. 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.

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}")

# 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 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 Python:

> python __init__.py

Hello, World!

• Controle de versão de runtime: agora, opcionalmente, você pode fixar ou atualizar seu aplicativo para versões específicas de trabalho Python fazendo referência ao 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 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 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 regularmente as notas de versão do tempo de execução do Python.

  • 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	Exemplo	Comportamento
    Nenhum conjunto de valores	azure-functions-runtime	Seu aplicativo Python 3.13+ é executado na versão mais recente disponível do runtime do Functions Python. 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, seu aplicativo Python 3.13+ é executado em uma versão padrão do runtime Python que está por trá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ê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 do aplicativo PYTHON_ISOLATE_WORKER_DEPENDENCIES 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, opcionalmente, você pode fixar ou atualizar seu aplicativo para versões específicas de trabalho Python fazendo referência ao pacote azure-functions-runtime-v1 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 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 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 regularmente as notas de versão do tempo de execução do Python.

  • 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	Exemplo	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 Functions Python. 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 Python que está por trá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ê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 do aplicativo PYTHON_ISOLATE_WORKER_DEPENDENCIES 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.

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")

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")