Configurar a publicação de Durable Functions no Grade de Eventos do Azure

A publicação de eventos de ciclo de vida de orquestração para a Grade de Eventos do Azure permite a automação de DevOps (como implantações azul/verde), painéis de monitoramento em tempo real e acompanhamento de processos em segundo plano de longa execução.

Pré-requisitos

• Um projeto Durable Functions implantado no Azure. Se você não tiver um, crie um usando o início rápido para seu idioma preferido:

  • C# (modelo de trabalho isolado) | JavaScript | Python | PowerShell | Java

• A versão correta da extensão Durable Functions. Para .NET, atualize sua extensão para a versão mais recente:

  • 2.7.0+ (em processo)

    dotnet add package Microsoft.Azure.WebJobs.Extensions.DurableTask
    

  • 1.1.0+ (trabalho isolado)

    dotnet add package Microsoft.Azure.Functions.Worker.Extensions.DurableTask
    

  Para outros idiomas, verifique seu package.json, requirements.txt, pom.xml ou requirements.psd1.

• Identidade gerenciada foi habilitada e configurada em seu aplicativo de função.

• Um provedor de armazenamento em execução ou o emulador de armazenamento do Azurite local.

• CLI do Azure ou Azure Cloud Shell.

• Uma ferramenta de teste para HTTP que mantém seus dados seguros.

Criar um tópico personalizado da Grade de Eventos

Você pode criar um tópico da Grade de Eventos para enviar eventos de Durable Functions usando o CLI do Azure, PowerShell ou o portal Azure.

Este guia usa o CLI do Azure.

Criar um grupo de recursos

Crie um grupo de recursos com o comando az group create. Escolha um local que dê suporte à Grade de Eventos e corresponda ao local em que você deseja implantar seus recursos.

az group create --name <resource-group-name> --location <location>

Habilitar o provedor de recursos do Event Grid

1. Se esta for a primeira vez que você estiver usando a Grade de Eventos em sua assinatura do Azure, talvez seja necessário registrar o provedor de recursos da Grade de Eventos. Execute o seguinte comando para registrar o provedor:

   az provider register --namespace Microsoft.EventGrid
   

2. A conclusão do registro pode demorar um pouco. Para verificar o status, execute o seguinte comando:

   az provider show --namespace Microsoft.EventGrid --query "registrationState"
   

   Quando registrationState for Registered, você está pronto para continuar.

Criar um tópico personalizado

Um tópico da Grade de Eventos fornece um ponto de extremidade definido pelo usuário para o qual você posta seu evento. Substitua <topic-name> no comando a seguir por um nome exclusivo para o tópico. O nome do tópico deve ser exclusivo porque se torna uma entrada DNS.

az eventgrid topic create --name <topic-name> --location <location> --resource-group <resource-group-name>

Obter o ponto de extremidade do tópico

Obtenha o ponto de extremidade do tópico. Substitua <topic-name> nos comandos a seguir pelo nome escolhido.

az eventgrid topic show --name <topic-name> --resource-group <resource-group-name> --query "endpoint" --output tsv

Salve este ponto de acesso para utilizar posteriormente.

Configurar a publicação da Grade de Eventos com a Identidade Gerenciada (recomendado)

As identidades gerenciadas no Azure permitem que os recursos se autentiquem nos serviços do Azure sem armazenar credenciais, simplificando a segurança e o gerenciamento de identidades. Atribua a identidade gerenciada associada ao aplicativo de funções duráveis ao tópico personalizado da Grade de Eventos.

Configurar o aplicativo Durable Functions editor

Embora seu aplicativo Durable Functions publique automaticamente eventos de ciclo de vida de orquestração na Grade de Eventos, você precisa definir as configurações de conexão. Adicione o seguinte na seção extensions.durableTask em seu host.json:

{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "eventGridTopicEndpoint": "%EventGrid__topicEndpoint%",
      "eventGridKeySettingName": "EventGrid__credential"
    }
  }
}

Atribuir função de Remetente de Dados do Event Grid

Conceda permissão à identidade gerenciada para publicar eventos no tópico da Grade de Eventos.

az role assignment create \
  --assignee <client-id-of-managed-identity> \
  --assignee-principal-type ServicePrincipal \
  --role "EventGrid Data Sender" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.EventGrid/topics/<topic-name>

az role assignment create \
  --assignee-object-id <object-id-of-function-app-identity> \
  --assignee-principal-type ServicePrincipal \
  --role "EventGrid Data Sender" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.EventGrid/topics/<topic-name>

az functionapp identity show \
  --name <function-app-name> \
  --resource-group <resource-group-name> \
  --query principalId --output tsv

Definir configurações de aplicativo

Depois de habilitar a identidade gerenciada para seu aplicativo de funções e tópico, defina as configurações do aplicativo da Grade de Eventos em seu aplicativo de funções Durable Functions.

az functionapp config appsettings set --name <function app name> --resource-group <resource group name> --settings EventGrid__topicEndpoint="<topic endpoint>" EventGrid__credential="managedidentity" EventGrid__clientId="<client id>"

az functionapp config appsettings set --name <function app name> --resource-group <resource group name> --settings EventGrid__topicEndpoint="<topic endpoint>"

Assinar eventos

Para receber os eventos de ciclo de vida publicados, crie uma assinatura da Grade de Eventos que roteia eventos do tópico personalizado para um assinante. Os tipos comuns de assinante incluem Azure Functions (com um gatilho da Grade de Eventos), Aplicativos Lógicos e webhooks.

O exemplo a seguir cria um aplicativo de funções de assinante com um gatilho da Grade de Eventos usando a CLI do Azure. Se você já tiver uma assinatura, pule para Criar uma assinatura da Grade de Eventos.

Criar um aplicativo de funções do ouvinte

Crie um aplicativo de funções para hospedar o gatilho da Grade de Eventos. O ouvinte deve estar na mesma região que o tópico da Grade de Eventos.

# Create a resource group
az group create --name <listener-resource-group-name> --location <location>

# Create a storage account
az storage account create \
  --name <storage-account-name> \
  --resource-group <listener-resource-group-name> \
  --location <location> \
  --sku Standard_LRS \
  --allow-blob-public-access false

# Create the function app
az functionapp create \
  --resource-group <listener-resource-group-name> \
  --consumption-plan-location <location> \
  --runtime <preferred-runtime> \
  --functions-version 4 \
  --name <listener-function-app-name> \
  --storage-account <storage-account-name>

Criar e implantar uma função de disparo do Event Grid

Estruture um projeto local, adicione um disparador do Event Grid e publique-o:

mkdir EventGridListenerFunction && cd EventGridListenerFunction
func init --name EventGridListener --runtime dotnet-isolated
func new --template "Event Grid trigger" --name EventGridTrigger
func azure functionapp publish <listener-function-app-name>

Criar uma assinatura na Grade de Eventos

Crie a assinatura usando o tipo de endpoint azurefunction, que lida automaticamente com a validação de webhook.

az eventgrid event-subscription create \
  --name <subscription-name> \
  --source-resource-id /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.EventGrid/topics/<topic-name> \
  --endpoint /subscriptions/<subscription-id>/resourceGroups/<listener-resource-group-name>/providers/Microsoft.Web/sites/<listener-function-app-name>/functions/EventGridTrigger \
  --endpoint-type azurefunction

Esquema do evento

Quando um estado de orquestração é alterado, o runtime do Durable Functions publica um evento com a estrutura a seguir. Os eventos são gerados automaticamente para cada transição de estado. Você não precisa adicionar nenhum código.

A Grade de Eventos garante uma entrega pelo menos uma vez, portanto, você pode receber eventos duplicados em cenários de falha raros. Considere adicionar lógica de eliminação de duplicação usando o instanceId se necessário.

Verificar a entrega de eventos

Para verificar a configuração de ponta a ponta, implante seu aplicativo Durable Functions e dispare uma orquestração:

1. Publique o código da função no Azure e verifique se seu aplicativo de função exibe "Em execução" no portal do Azure.

2. No portal do Azure, verifique as configurações do aplicativo em Configurações>Variáveis de ambiente, incluindo EventGrid__topicEndpoint e (se estiver usando identidade gerenciada) EventGrid__credential.

3. Iniciar uma orquestração de tarefas usando um cliente HTTP:

   curl -X POST https://<function_app_name>.azurewebsites.net/api/HelloOrchestration_HttpStart
   

4. No portal Azure, navegue até o aplicativo de funções listener>EventGridTrigger>Monitor para exibir os eventos recebidos. Você deve ver eventos com assuntos como durable/orchestrator/Running e durable/orchestrator/Completed.

Verifique no Application Insights (opcional)

Para uma exibição mais abrangente, execute esta consulta KQL nos Logs do Application Insights do aplicativo de funções:

traces
| where message contains "Event type" or message contains "Event subject"
| project timestamp, message
| order by timestamp desc

Solução de problemas

Os eventos não estão sendo publicados na Grade de Eventos

Problema: a função de ouvinte não está recebendo eventos.

Soluções:

• Verifique se o aplicativo de funções Durable Functions tem as configurações corretas do aplicativo:
  • EventGrid__topicEndpoint deve apontar para o endpoint do tópico personalizado
  • Defina EventGrid__credential como managedidentity
  • EventGrid__clientId deve ser definido se estiver usando uma identidade atribuída pelo usuário
• Verifique se a identidade gerenciada tem a função EventGrid Data Sender atribuída ao tópico personalizado da Grade de Eventos.
• Verifique os logs do aplicativo de funções Durable Functions no Application Insights para identificar erros.
• Verifique se o tópico da Grade de Eventos existe e se está acessível na mesma assinatura.

A função listener não está sendo ativada

Problema: a função de ouvinte existe, mas não está em execução quando os eventos são publicados.

Soluções:

• Verifique se a assinatura da Grade de Eventos foi criada e se está habilitada:
  • No portal Azure, navegue até o tópico da Grade de Eventos → Subscriptions
  • Confirme se a assinatura da função de ouvinte está listada com o status Habilitado
• Verifique se a assinatura da Grade de Eventos está usando o tipo de ponto de extremidade correto:
  • Para o Azure Functions, use --endpoint-type azurefunction com o identificador de recurso da função
  • Se você usou --endpoint-type webhook, verifique se a URL do webhook está no formato correto: https://<function-app>.azurewebsites.net/runtime/webhooks/eventgrid?functionName=<function-name>&code=<system-key>
• Verifique os logs do aplicativo de função Listener em busca de erros ou problemas de entrega.
• No tópico da Grade de Eventos → Métricas, verifique se há eventos descartados que podem indicar falhas de entrega.

"Erro de proibição" ou erros de autenticação em logs

Problema: erros de autenticação ao publicar na Grade de Eventos.

Soluções:

• Verifique se a identidade gerenciada está configurada e habilitada corretamente no aplicativo de funções Durable Functions:
  • No portal Azure, navegue até o aplicativo de funções → Identity
  • Confirme se "Status" mostra Ativado para identidade atribuída pelo sistema ou atribuída pelo usuário
• Verifique se a atribuição de função está correta:
  • Navegue até o tópico da Grade de Eventos → Controle de Acesso (IAM)
  • Confirme se sua identidade gerenciada tem a função EventGrid Data Sender (observação: sem espaço entre "Evento" e "Grade")
  • A atribuição de função pode levar de 5 a 10 minutos para ser propagada

Erros de "Conexão recusada" ou "ponto de extremidade não encontrado"

Problema: erros de conexão com o tópico da Grade de Eventos.

Soluções:

• Verifique se o ponto de extremidade do tópico da Grade de Eventos nas configurações do aplicativo está correto e inclui a URL completa (por exemplo, https://my-topic.eventgrid.azure.net/api/events)
• Verifique se o recurso de tópico da Grade de Eventos existe na mesma assinatura e região
• Verifique se o aplicativo Durable Functions tem acesso à rede ao ponto de extremidade da Grade de Eventos

Testar localmente

Para testar localmente, consulte o teste local com o aplicativo Web visualizador. Ao testar localmente com a identidade gerenciada, use suas credenciais de desenvolvedor para se autenticar no tópico da Grade de Eventos. Consulte Configure Durable Functions com identidade gerenciada – Desenvolvimento local para obter detalhes.

Limpar os recursos

Se você não quiser continuar a usar os recursos criados neste tutorial, exclua-os para evitar incorrer em encargos.

Excluir os grupos de recursos

Exclua os grupos de recursos e todos os recursos contidos:

az group delete --name <resource-group-name> --yes
az group delete --name <listener-resource-group-name> --yes

Excluir recursos individuais

Se você quiser manter alguns recursos, poderá excluí-los individualmente:

1. Exclua a assinatura da Grade de Eventos:

   az eventgrid event-subscription delete \
     --name <subscription-name> \
     --source-resource-id /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.EventGrid/topics/<topic-name>
   

2. Exclua o tópico da grade de eventos:

   az eventgrid topic delete --name <topic-name> --resource-group <resource-group-name>
   

3. Exclua os aplicativos de funções:

   az functionapp delete --name <publisher-function-app-name> --resource-group <resource-group-name>
   az functionapp delete --name <listener-function-app-name> --resource-group <listener-resource-group-name>
   

4. Exclua as contas de armazenamento:

   az storage account delete --name <storage-account-name> --resource-group <resource-group-name> --yes
   az storage account delete --name <listener-storage-account-name> --resource-group <listener-resource-group-name> --yes
   

Próximas Etapas 

Saiba mais sobre:

• Gerenciamento de instância
• Controle de versão no Durable Functions