Publicação do Durable Functions na Grade de Eventos do Azure

Este artigo mostra como configurar o Durable Functions para publicar eventos de ciclo de vida de orquestração (como criado, concluído e com falha) em um tópico da Grade de Eventos do Azure personalizado.

A seguir estão alguns cenários em que esse recurso é útil:

• Cenários de DevOps, como implantações azul/verde: talvez você queira saber se alguma tarefa está em execução antes de implementar a estratégia de implantação lado a lado.

• Suporte avançado de monitoramento e diagnóstico: você pode acompanhar as informações de status de orquestração em um repositório externo otimizado para consultas, como o Banco de Dados SQL do Azure ou o Azure Cosmos DB.

• Atividade em segundo plano de execução prolongada: se você usar As Funções Duráveis para uma atividade em segundo plano de longa execução, esse recurso ajudará você a saber o status atual.

Pré-requisitos

• Instale Microsoft.Azure.WebJobs.Extensions.DurableTask no seu projeto de Durable Functions.
• Instale o emulador de armazenamento do Azurite ou use uma conta de Armazenamento do Azure existente.
• Instalar a CLI do Azure ou usar o Azure Cloud Shell

Criar um tópico personalizado da Grade de Eventos

Crie um tópico do Event Grid para enviar eventos do Durable Functions. As instruções a seguir mostram como criar um tópico usando a CLI do Azure. Você também pode criar o tópico usando o PowerShell ou usando o portal do Azure.

Criar um grupo de recursos

Crie um grupo de recursos com o comando az group create. Atualmente, a Grade de Eventos do Azure não dá suporte a todas as regiões. Para obter informações sobre quais regiões têm suporte, consulte a visão geral da Grade de Eventos do Azure.

az group create --name eventResourceGroup --location westus2

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> 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> -l westus2 -g eventResourceGroup

Obter o ponto de extremidade e a chave

Obtenha o ponto de extremidade do tópico. Substitua <topic_name> pelo nome escolhido.

az eventgrid topic show --name <topic_name> -g eventResourceGroup --query "endpoint" --output tsv

Obtenha a chave do tópico se você estiver usando a autenticação baseada em chave. Substitua <topic_name> pelo nome escolhido.

az eventgrid topic key list --name <topic_name> -g eventResourceGroup --query "key1" --output tsv

Agora você pode enviar eventos para o tópico.

Configurar a publicação da Grade de Eventos com autenticação baseada em chave

Em seu projeto Durable Functions, localize o arquivo host.json.

Funções Duráveis 1.x

Adicionar eventGridTopicEndpoint e eventGridKeySettingName em uma durableTask propriedade.

{
  "durableTask": {
    "eventGridTopicEndpoint": "https://<topic_name>.westus2-1.eventgrid.azure.net/api/events",
    "eventGridKeySettingName": "EventGridKey"
  }
}

Funções Duráveis 2.x

Adicione uma notifications seção à durableTask propriedade do arquivo, substituindo <topic_name> pelo nome escolhido. Se as propriedades durableTask ou extensions não existirem, crie-as conforme este exemplo:

{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "notifications": {
        "eventGrid": {
          "topicEndpoint": "https://<topic_name>.westus2-1.eventgrid.azure.net/api/events",
          "keySettingName": "EventGridKey"
        }
      }
    }
  }
}

As possíveis propriedades de configuração da Grade de Eventos do Azure podem ser encontradas na documentação dohost.json. Após a configuração do arquivo host.json, seu aplicativo de funções envia eventos de ciclo de vida ao tópico da Grade de Eventos. Essa ação começa quando você executa seu aplicativo de funções localmente e no Azure.

Defina a configuração do aplicativo para a chave do tópico no Aplicativo de Funções e local.settings.json. O JSON a seguir é um exemplo do local.settings.json para depuração local usando um emulador do Armazenamento do Azure. Substitua <topic_key> pela chave do tópico.

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "EventGridKey": "<topic_key>"
    }
}

Se você estiver usando o Emulador de Armazenamento em vez de uma conta real do Armazenamento do Azure, verifique se ele está em execução. É uma boa ideia limpar todos os dados de armazenamento existentes antes da execução.

Se você estiver usando uma conta real do Armazenamento do Azure, substitua UseDevelopmentStorage=true em local.settings.json por sua cadeia de conexão.

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

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. A identidade gerenciada atribuída pelo sistema é criada automaticamente quando você a habilita em um recurso do Azure e está vinculada ao ciclo de vida desse recurso. Se o recurso for excluído, a identidade também será removida. A identidade gerenciada atribuída pelo usuário é criada como um recurso autônomo do Azure e pode ser atribuída a vários recursos. Ele persiste independentemente de qualquer recurso, oferecendo flexibilidade para acesso compartilhado e gerenciamento centralizado de identidades. É recomendável que você use a identidade atribuída pelo usuário porque ela não está anexada ao ciclo de vida do aplicativo.

Para obter mais informações, visite Usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions.

Identidade atribuída pelo sistema

Para configurar a identidade atribuída pelo sistema, siga as instruções abaixo:

Configuração

1. Ativar a identidade atribuída pelo sistema para o aplicativo de funções

   • Vá para a seção Identidade do aplicativo de funções e, na guia Sistema Atribuído , ative a opção Status .

     

2. No recurso de tópico da Grade de Eventos, forneça ao aplicativo de função a função de Remetente de Dados do EventGrid.

   • Vá para a seção Controle de Acesso (IAM), clique em + Adicionar.

     

   • Selecione a função EventGrid Data Sender e clique em Avançar.

     

   • Escolha Identidade Gerenciada na seção Atribuir acesso , clique em + Selecionar Membros na seção Membros , selecione a identidade gerenciada e clique em Examinar + Atribuir.

     

Configurações do aplicativo

Adicione uma configuração EventGrid__topicEndpoint de aplicativo com o valor como o ponto de extremidade do tópico da Grade de Eventos.

Você pode usar o seguinte comando: az functionapp config appsettings set --name <function app name> --resource-group <resource group name> --settings EventGrid__topicEndpoint="<topic endpoint>"

Identidade atribuída pelo usuário

Para configurar a identidade gerenciada atribuída pelo usuário, siga as instruções abaixo:

Configuração

1. Criar uma identidade gerenciada atribuída pelo usuário.

   • No portal do Azure, pesquise identidades gerenciadas na barra de pesquisa global.

   • Crie uma UAMI (identidade gerenciada) atribuída pelo usuário e selecione Examinar + criar.

     

2. Anexar a UAMI ao recurso do aplicativo de funções

   • Vá para o aplicativo de funções, seção Identidade , clique em Adicionar +.

     

   • Escolha o UAMI criado acima e clique em Adicionar.

     

3. Anexe o UAMI ao recurso de tópico da Grade de Eventos.

   • Vá para o recurso de tópico da Grade de Eventos, seção Identidade, escolha a guia Atribuição do Usuário e clique em Adicionar +. Escolha a identidade gerenciada atribuída pelo usuário e clique em Adicionar.

     

4. Crie uma assinatura da Event Grid e selecione um ponto de extremidade.

   • Na guia Visão geral do recurso Tópico da Grade de Eventos, selecione + Assinatura de Evento e crie a assinatura do evento.

     

   • Com base no endpoint escolhido nos Detalhes do Endpoint, você verá uma seção Identidade Gerenciada para Entrega. Escolha Usuário Atribuído para o tipo Identidade Gerenciada e selecione a UAMI.

     

5. No recurso de tópico da Grade de Eventos, atribua a função Remetente de Dados do EventGrid à UAMI.

   • Vá para a seção Controle de Acesso (IAM), clique em + Adicionar.

     

   • Selecione a função EventGrid Data Sender e clique em Avançar.

     

   • Escolha Identidade Gerenciada na seção Atribuir acesso, clique + Selecionar Membros na seção Membros, selecione o UAMI e clique em Examinar + Atribuir.

     

Configurações do aplicativo

• Adicione uma configuração de aplicativo EventGrid__topicEndpoint com o valor definido como o ponto de extremidade do tópico da Grade de Eventos.
• Adicione uma configuração EventGrid__credential de aplicativo com o valor managedidentity.
• Adicione uma configuração EventGrid__clientId de aplicativo com o valor da ID do cliente de identidade gerenciada atribuída pelo usuário.

Criar funções que escutam eventos

Usando o portal do Azure, crie outro aplicativo de funções para escutar eventos publicados pelo aplicativo Durable Functions. É melhor localizá-lo na mesma região que o tópico da Grade de Eventos.

Criar uma função de disparador do Event Grid

1. Em seu aplicativo de funções, selecione Funções e, em seguida, selecione + Adicionar

   

2. Pesquise por Event Grid e, em seguida, selecione o modelo de disparador do Azure Event Grid.

   

3. Nomeie o novo gatilho e selecione Criar Função.

   

   Uma função com o seguinte código é criada:

   • C# Script
   • JavaScript

   #r "Newtonsoft.Json"
   using Newtonsoft.Json;
   using Newtonsoft.Json.Linq;
   using Microsoft.Extensions.Logging;
   
   public static void Run(JObject eventGridEvent, ILogger log)
   {
       log.LogInformation(eventGridEvent.ToString(Formatting.Indented));
   }
   

Adicionar uma assinatura da Grade de Eventos

Agora você pode adicionar uma assinatura da Grade de Eventos para o tópico da Grade de Eventos que você criou. Para obter mais informações, consulte Conceitos na Grade de Eventos do Azure.

1. Na sua nova função, selecione Integração e, em seguida, escolha Gatilho da Grade de Eventos (eventGridEvent).

   

2. Selecione Criar Descrição da Grade de Eventos.

   

3. Nomeie sua assinatura de evento e selecione o tipo de tópico Tópicos da Grade de Eventos .

4. Selecione a assinatura. Em seguida, selecione o grupo de recursos e o recurso que você criou para o tópico da Grade de Eventos.

5. Selecione Criar.

   

Agora, você está pronto para receber eventos de ciclo de vida.

Executar o aplicativo Durable Functions para enviar os eventos

No projeto de Durable Functions que você configurou anteriormente, comece a depuração no computador local e inicie uma orquestração. O aplicativo publica eventos de ciclo de vida do Durable Functions na Grade de Eventos. Verifique se a Grade de Eventos dispara a função de ouvinte que você criou verificando seus logs no portal do Azure.

2019-04-20T09:28:21.041 [Info] Function started (Id=3301c3ef-625f-40ce-ad4c-9ba2916b162d)
2019-04-20T09:28:21.104 [Info] {
    "id": "054fe385-c017-4ce3-b38a-052ac970c39d",
    "subject": "durable/orchestrator/Running",
    "data": {
        "hubName": "DurableFunctionsHub",
        "functionName": "Sample",
        "instanceId": "055d045b1c8a415b94f7671d8df693a6",
        "reason": "",
        "runtimeStatus": "Running"
    },
    "eventType": "orchestratorEvent",
    "eventTime": "2019-04-20T09:28:19.6492068Z",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "topic": "/subscriptions/<your_subscription_id>/resourceGroups/eventResourceGroup/providers/Microsoft.EventGrid/topics/durableTopic"
}

2019-04-20T09:28:21.104 [Info] Function completed (Success, Id=3301c3ef-625f-40ce-ad4c-9ba2916b162d, Duration=65ms)
2019-04-20T09:28:37.098 [Info] Function started (Id=36fadea5-198b-4345-bb8e-2837febb89a2)
2019-04-20T09:28:37.098 [Info] {
    "id": "8cf17246-fa9c-4dad-b32a-5a868104f17b",
    "subject": "durable/orchestrator/Completed",
    "data": {
        "hubName": "DurableFunctionsHub",
        "functionName": "Sample",
        "instanceId": "055d045b1c8a415b94f7671d8df693a6",
        "reason": "",
        "runtimeStatus": "Completed"
    },
    "eventType": "orchestratorEvent",
    "eventTime": "2019-04-20T09:28:36.5061317Z",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "topic": "/subscriptions/<your_subscription_id>/resourceGroups/eventResourceGroup/providers/Microsoft.EventGrid/topics/durableTopic"
}
2019-04-20T09:28:37.098 [Info] Function completed (Success, Id=36fadea5-198b-4345-bb8e-2837febb89a2, Duration=0ms)

Esquema de eventos

A lista a seguir explica o esquema de eventos do ciclo de vida:

• id: identificador exclusivo para o evento da Grade de Eventos.
• subject: caminho para o assunto do evento. durable/orchestrator/{orchestrationRuntimeStatus}. {orchestrationRuntimeStatus} será Running, Completed, Failede Terminated.
• data: parâmetros específicos de funções duráveis.
  • hubName: TaskHub nome.
  • functionName: nome da função orchestrator.
  • instanceId : instanceId de Durable Functions.
  • reason: dados adicionais associados ao evento de acompanhamento. Para obter mais informações, consulte Diagnóstico em Funções Duráveis (Azure Functions)
  • runtimeStatus: Status de Runtime de Orquestração. Em Execução, Concluído, Falha, Cancelado.
• eventType: "orchestratorEvent"
• eventTime: hora do evento (UTC).
• dataVersion: versão do esquema de eventos do ciclo de vida.
• metadataVersion: versão dos metadados.
• topic: recurso de tópico da Grade de Eventos.

Como testar localmente

Para testar localmente, leia o teste local com o aplicativo Web visualizador.

Próximas etapas