Configurar a publicação das funções do Durable Functions no Azure Event Grid

Publicar eventos do ciclo de vida da orquestração em Azure Event Grid permite a automação DevOps (como implementações azuis/verdes), painéis de monitorização em tempo real e o rastreio de processos em segundo plano de longa duração.

Pré-requisitos

• Um projeto Durable Functions implementado no Azure. Se não tiveres um, cria um usando o quickstart da tua língua preferida:

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

• A versão correta da extensão Durable Functions. Para .NET, atualize a 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+ (trabalhador isolado)

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

  Para outras línguas, verifique o seu package.json, requirements.txt, pom.xml, ou requirements.psd1.

• Identidade gerida ativada e configurada na tua aplicação de funções.

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

• CLI do Azure ou Azure Cloud Shell.

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

Crie um tópico personalizado para a Grelha de Eventos

Pode criar um tópico de Grade de Eventos para enviar eventos a partir de Durable Functions usando a CLI do Azure, PowerShell ou o portal do Azure.

Este guia utiliza a CLI do Azure.

Criar um grupo de recursos

Crie um grupo de recursos com o comando az group create. Escolhe um local que suporte a Grade de Eventos e que corresponda ao local onde queres investir os teus recursos.

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

Habilitar o provedor de recursos da Grade de Eventos

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 registar o fornecedor:

   az provider register --namespace Microsoft.EventGrid
   

2. Pode demorar algum tempo até que o registo termine. Para verificar o status, execute o seguinte comando:

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

   Quando registrationState está Registered, ficas pronto para continuar.

Criar um tópico personalizado

Um tópico de Grelha de Eventos fornece um endpoint definido pelo utilizador onde publica o seu evento. Substitua <topic-name> no comando seguinte por um nome único para o seu tema. O nome do tópico tem de ser único porque se torna uma entrada DNS.

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

Obtém o ponto final do tema

Percebe o ponto final do tema. Substitua <topic-name> nos seguintes comandos pelo nome que escolheu.

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

Guarde este endpoint para mais tarde.

Configurar a publicação do Event Grid com Identidade Gerenciada (recomendado)

As identidades geridas no Azure permitem que os recursos se autentiquem nos serviços do Azure sem armazenar credenciais, simplificando a segurança e a gestão de identidades. Atribui a identidade gerida associada à tua aplicação Durable Function ao tópico personalizado da tua Grade de Eventos.

Configurar a aplicação editora Durable Functions

Embora a sua aplicação Durable Functions publique automaticamente os eventos do ciclo de vida da orquestração no Event Grid, precisa de configurar as definições de ligação. Adicione o seguinte à secção extensions.durableTask do seu host.json:

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

Atribuir papel de Transmissor de Dados da Event Grid

Conceda à sua identidade gerida permissão para publicar eventos no tópico do Event Grid.

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

Configurar as definições da aplicação

Depois de ativar a identidade gerida para a sua aplicação de funções e tópico, configure as definições da aplicação Event Grid na sua aplicação 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>"

Inscrever-se em eventos

Para receber os eventos do ciclo de vida publicados, crie uma subscrição do Event Grid que encaminhe os eventos do seu tópico personalizado para um assinante. Tipos comuns de subscritores incluem, por exemplo, Funções do Azure (com um gatilho do Event Grid), Logic Apps e webhooks.

O exemplo seguinte cria uma função de aplicação de assinante com um gatilho do Event Grid usando a CLI do Azure. Se já tem assinante, salte para Criar uma subscrição do Event Grid.

Crie uma aplicação de função de ouvinte

Cria uma aplicação de funções para alojar o gatilho da Grelha de Eventos. O ouvinte deve estar na mesma região do tema da Grelha 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>

Crie e implemente uma função de gatilho do Event Grid

Apoie um projeto local, adicione um gatilho de Grelha de Eventos 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 subscrição do Event Grid

Crie a subscrição usando o azurefunction tipo de endpoint, que gere automaticamente a validação do 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 de eventos

Quando um estado de orquestração muda, o runtime das Durable Functions publica um evento com a seguinte estrutura. Os eventos são gerados automaticamente para cada transição de estado — não precisa de adicionar código.

A Grade de Eventos assegura uma entrega pelo menos uma vez, pelo que pode receber eventos duplicados em cenários raros de falha. Considere adicionar lógica de deduplicação usando a instanceId se necessário.

Validar a entrega do evento

Para verificar a configuração de ponta a ponta, implemente a sua aplicação Durable Functions e acione uma orquestração:

1. Publique o código da função para o Microsoft Azure e verifique se a sua aplicação de funções indica "Em execução" no portal Azure.

2. No portal Azure, verifique as definições da sua aplicação em Settings>Variáveis de ambiente incluem EventGrid__topicEndpoint e (se usar identidade gerida) EventGrid__credential.

3. Acione uma orquestração usando um cliente HTTP:

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

4. No portal Azure, navegue até à sua aplicação de funções listener>EventGridTrigger>Monitor para ver os eventos recebidos. Deves ver eventos com temas como durable/orchestrator/Running e durable/orchestrator/Completed.

Verificar no Application Insights (opcional)

Para uma visão mais abrangente, execute esta consulta KQL nos Logs do Application Insights da sua funcionalidade de aplicação:

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

Troubleshooting

Os eventos não estão a ser publicados no Event Grid

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

Soluções:

• Verifique se a aplicação Durable Functions tem as definições corretas:
  • EventGrid__topicEndpoint deve apontar para o endpoint do teu tópico personalizado
  • EventGrid__credential deve ser definido como managedidentity
  • EventGrid__clientId deve ser definido se usar uma identidade atribuída pelo utilizador
• Verifique se a identidade gerida tem o papel Remetente de Dados EventGrid atribuído ao tópico personalizado do Event Grid.
• Verifique os registos da aplicação de funções Durable Functions no Application Insights para encontrar erros.
• Verifique se o tema Event Grid existe e está acessível na mesma subscrição.

A função do ouvinte não está a ser ativada

Problema: A função de ouvinte existe mas não está a ser executada quando os eventos são publicados.

Soluções:

• Verifique se a subscrição do Event Grid foi criada e está ativada:
  • No portal Azure, navegue até ao tópico da Grelha de Eventos → Subscrições
  • Confirme que a subscrição da sua função de ouvinte está listada com o estado Ativado
• Verifique se a subscrição do Event Grid está a usar o tipo de endpoint correto:
  • Para Funções do Azure, utilize --endpoint-type azurefunction com o ID do recurso da função específica
  • Se usou --endpoint-type webhook, certifique-se de que 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 da aplicação de função de escuta para erros ou problemas de entrega.
• No tópico Grelha de Eventos → Métricas, verifique se há Eventos Abandonados que possam indicar falhas na entrega.

Erros "proibidos" ou de autenticação nos registos

Problema: Erros de autenticação ao publicar no Event Grid.

Soluções:

• Verifique se a identidade gerida está devidamente configurada e ativada na aplicação Durable Functions function:
  • No portal Azure, navegue até à sua aplicação de funções → Identidade
  • Confirmar que o "Estado" indica Ligado para identidade atribuída pelo sistema ou pelo utilizador.
• Verifique se a atribuição de funções está correta:
  • Navegue até ao tópico da Grelha de Eventos → Controlo de Acesso (IAM)
  • Confirme que a sua identidade gerida tem o papel EventGrid Data Sender (nota: não há espaço entre "Event" e "Grid")
  • A atribuição do papel pode demorar entre 5 e 10 minutos a propagar-se

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

Problema: Erros de ligação ao tópico Event Grid.

Soluções:

• Verifique se o endpoint do tópico da Grade de Eventos nas definições da sua aplicação está correto e inclui o URL completo (por exemplo, https://my-topic.eventgrid.azure.net/api/events)
• Verifique se o recurso de tópicos Event Grid existe na mesma subscrição e região
• Verifique se a sua aplicação Durable Functions tem acesso em rede ao endpoint Event Grid

Testar localmente

Para testar localmente, consulte Teste Local com aplicação web do visualizador. Ao testar localmente com identidade gerida, use as suas credenciais de programador para autenticar contra o tópico Event Grid. Consulte Configure Durable Functions com identidade gerida - Desenvolvimento local para obter mais informações.

Limpeza de recursos

Se não vais continuar a usar os recursos criados neste tutorial, apaga-os para evitar incorrer em custos.

Eliminar os grupos de recursos

Elimine ambos os grupos de recursos e todos os seus recursos contidos:

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

Eliminar recursos individuais

Se quiseres manter alguns recursos, podes apagá-los individualmente:

1. Eliminar a subscrição do Event Grid:

   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. Eliminar o tópico da Grelha de Eventos:

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

3. Apague as aplicações de função:

   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. Apagar 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
   

Passos seguintes

Saiba mais sobre:

• Gestão de instâncias
• Versionamento em Durable Functions