Criar sua primeira Durable Function em Python

  • Artigo

Durable Functions são uma extensão do Azure Functions que permitem que você escreva funções com estado em um ambiente sem servidor. A extensão gerencia estado, pontos de verificação e reinicializações para você.

Neste artigo, você aprenderá a usar a extensão do Azure Functions do Visual Studio Code para criar e testar localmente uma função durável "hello world". Essa função orquestrará e encadeará chamadas para outras funções. Em seguida, você poderá publicar o código de função no Azure.

Captura de tela da função durável em execução no Azure.

Pré-requisitos

Para concluir este tutorial:

  • Instale o Visual Studio Code.

  • Instale a extensão Azure Functions para Visual Studio Code.

  • Verifique se você tem a última versão do Azure Functions Core Tools.

  • As Durable Functions requerem uma conta de armazenamento do Azure. É necessária uma assinatura do Azure.

  • Certifique-se de que você tenha a versão 3.7, 3.8, 3.9 ou 3.10 do Python instalada.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Criar seu projeto local

Nesta seção, você usará o Visual Studio Code para criar um projeto local do Azure Functions.

  1. No Visual Studio Code, pressione F1 (ou CTRL/Cmd + SHIFT + P) para abrir a paleta de comandos. Na paleta de comandos, pesquise e selecione Azure Functions: Create New Project....

    Captura de tela da janela Criar função.

  2. Escolha um local em uma pasta vazia para o projeto e escolha Selecionar.

  1. Siga os avisos e forneça as seguintes informações:

    Prompt Valor Descrição
    Selecione uma linguagem de programação para o seu projeto de aplicativo de função. Python Criar um projeto local do Functions em Python.
    Selecione uma versão Azure Functions v4 Você verá essa opção somente quando o Core Tools ainda não estiver instalado. Nesse caso, o Core Tools é instalado na primeira vez em que você executa o aplicativo.
    Versão do Python Python 3.7, 3.8, 3.9 ou 3.10 O Visual Studio Code criará um ambiente virtual com a versão selecionada.
    Selecione um modelo para a primeira função do projeto Ignorar por enquanto
    Selecione como você gostaria de abrir seu projeto Abrir na janela atual Reabre o Visual Studio Code na pasta selecionada.

  1. Siga os avisos e forneça as seguintes informações:

    Prompt Valor Descrição
    Selecionar um idioma Python (Modelo de programação V2) Criar um projeto local do Python Functions usando o modelo de programação V2.
    Selecione uma versão Azure Functions v4 Você verá essa opção somente quando o Core Tools ainda não estiver instalado. Nesse caso, o Core Tools é instalado na primeira vez em que você executa o aplicativo.
    Versão do Python Python 3.7, 3.8, 3.9 ou 3.10 O Visual Studio Code criará um ambiente virtual com a versão selecionada.
    Selecione como você gostaria de abrir seu projeto Abrir na janela atual Reabre o Visual Studio Code na pasta selecionada.

O Visual Studio Code instalará o Azure Functions Core Tools se necessário. Ele também cria o projeto de aplicativo de funções em uma pasta. Este projeto contém os arquivos de configuração host.json e local.settings.json.

Um arquivo requirements.txt também será criado na pasta raiz. Ele especifica os pacotes do Python necessários para a execução do aplicativo de funções.

Instalar o azure-functions-durable de PyPI

Quando você criou o projeto, a extensão Azure Functions do Visual Studio Code criou automaticamente um ambiente virtual com a versão do Python selecionada. Em seguida, você precisará ativar o ambiente virtual em um terminal e instalar algumas dependências necessárias para o Azure Functions e as Durable Functions.

  1. Abra o arquivo requirements.txt no editor e altere o conteúdo dele para o seguinte código:

    azure-functions
azure-functions-durable

  2. Abra o terminal integrado do editor na pasta atual (Ctrl+Shift+`).

  3. No terminal integrado, ative o ambiente virtual na pasta atual, dependendo do sistema operacional:

    source .venv/bin/activate

  4. No terminal integrado em que o ambiente virtual está ativado, use o pip para instalar os pacotes definidos.

    python -m pip install -r requirements.txt

Criar suas funções

Um aplicativo básico de Durable Functions contém três funções:

  • Função de orquestrador: descreve um fluxo de trabalho que orquestra outras funções.
  • Função de atividade: chamada pela função de orquestrador, executa o trabalho e, opcionalmente, retorna um valor.
  • Função de cliente: uma Função do Azure comum que inicia uma função de orquestrador. Este exemplo usa uma função disparada por HTTP.

Função de orquestrador

Use um modelo para criar o código da função durável no projeto.

  1. Na paleta de comandos, pesquise e selecione Azure Functions: Create Function....

  2. Siga os avisos e forneça as seguintes informações:

    Prompt Valor Descrição
    Selecione um modelo para a função Orquestrador das Durable Functions Crie uma orquestração das Durable Functions
    Forneça um nome de função HelloOrchestrator Nome da função durável

Você adicionou um orquestrador para coordenar as funções de atividade. Abra HelloOrchestrator/__init__.py para ver a função de orquestrador. Cada chamada para context.call_activity invoca uma função de atividade chamada Hello.

A seguir, vamos adicionar a função de atividade Hello referenciada.

Função de atividade

  1. Na paleta de comandos, pesquise e selecione Azure Functions: Create Function....

  2. Siga os avisos e forneça as seguintes informações:

    Prompt Valor Descrição
    Selecione um modelo para a função Atividade das Durable Functions Crie uma função de atividade
    Forneça um nome de função Olá Nome da função de atividade

Você adicionou a função de atividade Hello, que é invocada pelo orquestrador. Abra Hello/__init__.py para ver que ele aceita um nome como entrada e retorna uma saudação. Uma função de atividade é onde você executará ações como fazer uma chamada de banco de dados ou executar um cálculo.

Por fim, você adicionará uma função disparada por HTTP que inicia a orquestração.

Função de cliente (iniciador de HTTP)

  1. Na paleta de comandos, pesquise e selecione Azure Functions: Create Function....

  2. Siga os avisos e forneça as seguintes informações:

    Prompt Valor Descrição
    Selecione um modelo para a função Iniciador de HTTP das Durable Functions Crie uma função de iniciador de HTTP
    Forneça um nome de função DurableFunctionsHttpStart Nome da função do cliente
    Nível de autorização Anônima Para fins de demonstração, permita que a função seja chamada sem autenticação

Você adicionou uma função disparada por HTTP que inicia uma orquestração. Abra DurableFunctionsHttpStart/__init__.py para ver que ele usa client.start_new para iniciar uma nova orquestração. Em seguida, ela usa client.create_check_status_response para retornar uma resposta HTTP contendo URLs que podem ser usadas para monitorar e gerenciar a nova orquestração.

Agora, você tem um aplicativo das Durable Functions que pode ser executado localmente e implantado no Azure.

Requisitos

A versão 2 do modelo de programação Python requer as seguintes versões mínimas:

Habilitar o modelo de programação v2

A seguinte configuração de aplicativo é necessária para executar o modelo de programação v2:

  • Nome: AzureWebJobsFeatureFlags
  • Valor: EnableWorkerIndexing

Se você estiver executando localmente com o Azure Functions Core Tools, deverá adicionar essa configuração ao arquivo local.settings.json. Se você estiver executando no Azure, siga essas etapas com a ferramenta de sua preferência:

Substitua <FUNCTION_APP_NAME> e <RESOURCE_GROUP_NAME> pelo nome do seu aplicativo de funções e grupo de recursos, respectivamente.

az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings AzureWebJobsFeatureFlags=EnableWorkerIndexing

Para criar um aplicativo de Durable Functions básico usando esses três tipos de funções, substitua o conteúdo de function_app.py pelo código Python a seguir.

import azure.functions as func
import azure.durable_functions as df

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

# An HTTP-Triggered Function with a Durable Functions Client binding
@myApp.route(route="orchestrators/{functionName}")
@myApp.durable_client_input(client_name="client")
async def http_start(req: func.HttpRequest, client):
    function_name = req.route_params.get('functionName')
    instance_id = await client.start_new(function_name)
    response = client.create_check_status_response(req, instance_id)
    return response

# Orchestrator
@myApp.orchestration_trigger(context_name="context")
def hello_orchestrator(context):
    result1 = yield context.call_activity("hello", "Seattle")
    result2 = yield context.call_activity("hello", "Tokyo")
    result3 = yield context.call_activity("hello", "London")

    return [result1, result2, result3]

# Activity
@myApp.activity_trigger(input_name="city")
def hello(city: str):
    return f"Hello {city}"

Revise a tabela abaixo para obter uma explicação de cada função e sua finalidade na amostra.

Método Descrição
hello_orchestrator A função de orquestrador, que descreve o fluxo de trabalho. Nesse caso, a orquestração é iniciada, invoca três funções em uma sequência e retorna os resultados ordenados de todas as três funções em uma lista.
hello A função de atividade, que executa o trabalho que está sendo orquestrado. A função retorna uma saudação simples para a cidade passada como um argumento.
http_start Uma função disparada por HTTP que inicia uma instância da orquestração e retorna uma resposta de status de verificação.

Observação

Durable Functions também dá suporte aos blueprints do Python V2. Para usá-los, você precisará registrar suas funções de blueprint usando a classe azure-functions-durableBlueprint, conforme mostrado aqui. O blueprint resultante pode ser registrado normalmente. Confira nossa amostra para obter um exemplo.

Testar a função localmente

As Ferramentas Principais do Azure Functions permitem executar um projeto do Azure Functions no seu computador de desenvolvimento local. Se você não as instalou ainda, precisará instalar essas ferramentas na primeira vez em que iniciar uma função no Visual Studio Code.

  1. Para testar a função, defina um ponto de interrupção no Hellocódigo da função de atividade (Hello/__init__.py). Pressione F5 ou selecione Debug: Start Debugging na paleta de comandos para iniciar o projeto do aplicativo de funções. A saída do Core Tools é exibida no painel Terminal.
  1. Para testar a função, defina um ponto de interrupção no código da função de atividade hello. Pressione F5 ou selecione Debug: Start Debugging na paleta de comandos para iniciar o projeto do aplicativo de funções. A saída do Core Tools é exibida no painel Terminal.

Observação

Para obter mais informações sobre depuração, confira Diagnóstico das Durable Functions.

  1. As Durable Functions exigem uma conta de armazenamento do Azure para serem executadas. Quando o Visual Studio Code solicitar a seleção de uma conta de armazenamento, escolha Selecionar conta de armazenamento.

    Captura de tela de como criar uma conta de armazenamento.

  2. Siga os prompts e forneça as seguintes informações para criar uma conta de armazenamento no Azure:

    Prompt Valor Descrição
    Selecionar uma assinatura nome da sua assinatura Selecionar sua assinatura do Azure
    Selecione uma conta de armazenamento Criar uma nova conta de armazenamento
    Insira o nome da nova conta de armazenamento nome exclusivo Nome da conta de armazenamento a ser criada
    Selecionar um grupo de recursos nome exclusivo Nome do grupo de recursos a ser criado
    Selecione um local região Selecione uma região próxima de você

  3. No painel Terminal, copie o ponto de extremidade de URL da sua função disparada por HTTP.

    Captura de tela da saída local do Azure.

  1. Use o navegador ou uma ferramenta como o Postman ou o cURL e envie uma solicitação HTTP para o ponto de extremidade de URL. Substitua o último segmento pelo nome da função de orquestrador (HelloOrchestrator). A URL precisa ser semelhante a http://localhost:7071/api/orchestrators/HelloOrchestrator.

    A resposta é o resultado inicial da função HTTP informando que a orquestração durável foi iniciada com êxito. Ela ainda não é o resultado final da orquestração. A resposta inclui algumas URLs úteis. Por enquanto, vamos consultar o status da orquestração.

  1. Use o navegador ou uma ferramenta como o Postman ou o cURL e envie uma solicitação HTTP para o ponto de extremidade de URL. Substitua o último segmento pelo nome da função de orquestrador (hello_orchestrator). A URL precisa ser semelhante a http://localhost:7071/api/orchestrators/hello_orchestrator.

    A resposta é o resultado inicial da função HTTP informando que a orquestração durável foi iniciada com êxito. Ela ainda não é o resultado final da orquestração. A resposta inclui algumas URLs úteis. Por enquanto, vamos consultar o status da orquestração.

  1. Copie o valor da URL para statusQueryGetUri, cole-o na barra de endereços do navegador e execute a solicitação. Como alternativa, você também pode continuar usando o Postman para emitir a solicitação GET.

    A solicitação consultará a instância de orquestração do status. Você obterá uma resposta eventual, o que mostra que a instância foi concluída e inclui as saídas ou os resultados da função durável. Ele tem esta aparência:

{
    "name": "HelloOrchestrator",
    "instanceId": "9a528a9e926f4b46b7d3deaa134b7e8a",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2020-03-18T21:54:49Z",
    "lastUpdatedTime": "2020-03-18T21:54:54Z"
}

{
    "name": "hello_orchestrator",
    "instanceId": "9a528a9e926f4b46b7d3deaa134b7e8a",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2020-03-18T21:54:49Z",
    "lastUpdatedTime": "2020-03-18T21:54:54Z"
}
  1. Para interromper a depuração, pressione SHIFT + F5 no Visual Studio Code.

Após verificar se a função foi executada corretamente no computador local, é hora de publicar o projeto no Azure.

Entrar no Azure

Para criar recursos do Azure ou publicar seu aplicativo, você deve entrar no Azure.

  1. Se você ainda não tiver entrado, escolha o ícone do Azure na barra de Atividades. Em seguida, na área Recursos, escolha Entrar no Azure….

    Captura de tela da janela de entrada no Azure no VS Code.

    Se você já estiver conectado e puder ver suas assinaturas existentes, vá para a próxima seção. Caso ainda não tenha uma conta do Azure, escolha Criar uma conta do Azure…. Os alunos podem escolher Criar uma Conta do Microsoft Azure for Students….

  2. Quando solicitado no navegador, escolha sua conta do Azure e entre usando suas credenciais de conta do Azure. Se você criar uma conta, poderá se conectar depois que a conta for criada.

  3. Após entrar com êxito, você poderá fechar a nova janela do navegador. As assinaturas que pertencem à sua conta do Azure são exibidas na barra lateral.

Criar o aplicativo de funções no Azure

Nesta seção, você criará um aplicativo de funções e os recursos relacionados na sua assinatura do Azure.

  1. Escolha o ícone do Azure na barra de atividades. Em seguida, na área Recursos, selecione o ícone + e escolha a opção Criar Aplicativo de Funções no Azure.

    Crie um recurso em sua assinatura do Azure

  2. Forneça as seguintes informações nos prompts:

    Prompt Seleção
    Selecionar uma assinatura Escolha a assinatura a ser usada. Você não verá esse aviso quando tiver apenas uma assinatura visível em Recursos.
    Insira um nome exclusivo globalmente para o aplicativo de funções Digite um nome que seja válido em um caminho de URL. O nome que você digitar é validado para ter certeza de que ele é exclusivo no Azure Functions.
    Selecionar uma pilha de runtime Escolha a versão da linguagem em que você está fazendo a execução localmente.
    Selecione uma localização para novos recursos Para obter um melhor desempenho, escolha uma região perto de você.

    A extensão mostra o status de recursos individuais conforme eles são criados no Azure no painel Azure: Log de Atividades.

    Log da criação de recursos do Azure

  3. Quando a criação for concluída, os recursos do Azure a seguir serão criados na sua assinatura. Os recursos são nomeados com base no nome do aplicativo de funções:

    • Um grupo de recursos, que é um contêiner lógico para recursos relacionados.
    • Uma conta de armazenamento do Azure padrão, que mantém o estado e outras informações sobre seus projetos.
    • Um aplicativo de funções, que fornece o ambiente para a execução do código de função. Um aplicativo de funções lhe permite agrupar funções como uma unidade lógica para facilitar o gerenciamento, a implantação e o compartilhamento de recursos dentro do mesmo plano de hospedagem.
    • Um Plano do Serviço de Aplicativo, que define o host subjacente do aplicativo de funções.
    • Uma instância do Application Insights conectada ao aplicativo de funções, que controla o uso das suas funções no aplicativo.

    Uma notificação é exibida depois que seu aplicativo de funções é criado e o pacote de implantação é aplicado.

    Dica

    Por padrão, os recursos do Azure necessários para o aplicativo de funções são criados com base no nome do aplicativo de funções fornecido por você. Por padrão, eles também são criados no mesmo grupo de recursos com o aplicativo de funções. Se desejar personalizar os nomes desses recursos ou reutilizar os recursos existentes, você precisará publicar o projeto com opções de criação avançadas.

Implantar o projeto no Azure

Importante

A implantação em um aplicativo de funções existente sempre substitui o conteúdo do aplicativo no Azure.

  1. Na área Recursos da atividade do Azure, localize o recurso do aplicativo de funções que você acabou de criar, clique com o botão direito do mouse no recurso e selecione Implantar no aplicativo de funções....

  2. Quando solicitado sobre a substituição de implantações anteriores, selecione Implantar para implantar seu código de função no novo recurso do aplicativo de funções.

  3. Após a conclusão da implantação, escolha Exibir Saída para ver a criação e os resultados da implantação, incluindo os recursos do Azure que você criou. Se você perder a notificação, selecione o ícone de sino no canto inferior direito para vê-lo novamente.

    Captura de tela da janela Exibir saída

Testar sua função no Azure

  1. Copie a URL do gatilho de HTTP do painel Saída. A URL que chama a função disparada por HTTP precisa estar neste formato: https://<functionappname>.azurewebsites.net/api/orchestrators/HelloOrchestrator
  1. Copie a URL do gatilho de HTTP do painel Saída. A URL que chama a função disparada por HTTP precisa estar neste formato: https://<functionappname>.azurewebsites.net/api/orchestrators/hello_orchestrator
  1. Cole essa nova URL para a solicitação HTTP na barra de endereços do navegador. Você precisa obter a mesma resposta de status de antes ao usar o aplicativo publicado.

Próximas etapas

Você usou o Visual Studio Code para criar e publicar um aplicativo de funções duráveis em Python.

Saiba mais sobre os padrões comuns de função durável