Configurare la pubblicazione delle Durable Functions su Griglia di eventi di Azure

La pubblicazione di eventi del ciclo di vita dell'orchestrazione in Griglia di eventi di Azure abilita l'automazione DevOps (ad esempio distribuzioni blu/verde), i dashboard di monitoraggio in tempo reale e il rilevamento dei processi in background a esecuzione prolungata.

Prerequisites

• Un progetto di Durable Functions distribuito in Azure. Se non è disponibile, crearne uno usando l'avvio rapido per la lingua preferita:

  • C# (modello di lavoro isolato) | JavaScript | Python | PowerShell | Java

• Versione corretta dell'estensione Durable Functions. Per .NET, aggiornare l'estensione alla versione più recente:

  • 2.7.0+ (in corso)

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

  • 1.1.0+ (lavoratore isolato)

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

  Per altre lingue, controllare package.json, requirements.txt, pom.xmlo requirements.psd1.

• Identità gestita abilitata e configurata nell'app per le funzioni.

• Provider di archiviazione in esecuzione o emulatore di archiviazione Azurite locale.

• interfaccia della riga di comando di Azure o Azure Cloud Shell.

• Strumento di test HTTP che protegge i dati.

Creare un argomento personalizzato di Griglia di eventi

È possibile creare un argomento di Griglia di eventi per l'invio di eventi da Durable Functions usando il interfaccia della riga di comando di Azure, PowerShell o il portale Azure.

Questa guida usa il interfaccia della riga di comando di Azure.

Creare un gruppo di risorse

Creare un gruppo di risorse con il comando az group create. Selezionare un percorso che supporti Griglia di eventi e corrisponda alla posizione in cui si vogliono distribuire le risorse.

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

Abilitare il provider di risorse Event Grid

1. Se è la prima volta che si usa Griglia di eventi nella sottoscrizione di Azure, potrebbe essere necessario registrare il provider di risorse di Griglia di eventi. Eseguire il comando seguente per registrare il provider:

   az provider register --namespace Microsoft.EventGrid
   

2. La registrazione può richiedere qualche secondo. Eseguire il comando seguente per verificare lo stato:

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

   Quando registrationState è Registered, è possibile continuare.

Creare un argomento personalizzato

Un argomento di Griglia di eventi fornisce un endpoint definito dall'utente a cui si pubblica l'evento. Sostituire <topic-name> nel comando seguente con un nome univoco per l'argomento. Il nome dell'argomento deve essere univoco perché diventa una voce DNS.

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

Ottenere l'endpoint del topic

Ottenere l'endpoint dell'argomento. Sostituire <topic-name> nei comandi seguenti con il nome scelto.

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

Salvare questo endpoint per un secondo momento.

Configurare la pubblicazione di Griglia di eventi con Identità gestita (scelta consigliata)

Le identità gestite in Azure consentono alle risorse di eseguire l'autenticazione ai servizi di Azure senza archiviare le credenziali, semplificando la sicurezza e la gestione delle identità. Assegnare l'identità gestita associata all'app Durable Function all'argomento personalizzato di Griglia di eventi.

Configurare l'app di pubblicazione Durable Functions

Anche se l'app Durable Functions pubblica automaticamente gli eventi del ciclo di vita dell'orchestrazione in Griglia di eventi, è necessario configurare le impostazioni di connessione. Aggiungere quanto segue nella sezione extensions.durableTask nel host.json:

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

Assegnare il ruolo Mittente di dati di Griglia di eventi

Concedere all'identità gestita l'autorizzazione per pubblicare eventi nell'argomento Griglia di eventi.

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

Configurare le impostazioni applicazione

Dopo aver abilitato l'identità gestita per l'app per funzioni e l'argomento, configurare le impostazioni dell'applicazione Griglia di eventi sull'app per funzioni 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>"

Sottoscrivere eventi

Per ricevere gli eventi di ciclo di vita pubblicati, creare una sottoscrizione di Event Grid che instrada gli eventi da un argomento personalizzato a un sottoscrittore. I tipi di sottoscrittori comuni includono Funzioni di Azure (con un trigger di Event Grid), Logic Apps e webhook.

Nel'esempio seguente viene creata un'app per le funzioni sottoscrittore con un trigger di Griglia di eventi usando l'interfaccia della riga di comando di Azure. Se si ha già un sottoscrittore, passare a Crea una sottoscrizione di Griglia di eventi.

Creare un'app per le funzioni del listener

Creare un'applicazione di funzioni per ospitare il trigger di Event Grid. Il listener deve trovarsi nella stessa area del topic di Event Grid.

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

Creare e distribuire una funzione trigger di Griglia di eventi

Eseguire lo scaffolding di un progetto locale, aggiungere un trigger di Griglia di eventi e pubblicarlo:

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>

Creare una sottoscrizione di Griglia di eventi

Creare la sottoscrizione usando il azurefunction tipo di endpoint, che gestisce automaticamente la convalida del 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

Schema eventi

Quando uno stato di orchestrazione cambia, il runtime di Durable Functions pubblica un evento con la struttura seguente. Gli eventi vengono generati automaticamente per ogni transizione di stato. Non è necessario aggiungere codice.

Event Grid garantisce la consegna almeno una volta, pertanto è possibile ricevere eventi duplicati in rari scenari di guasto. Considerare l'aggiunta della logica di deduplicazione utilizzando instanceId se necessario.

Verificare la consegna degli eventi

Per verificare la configurazione end-to-end, implementare l'app Durable Functions e avviare un'orchestrazione:

1. Pubblicare il codice della funzione per Azure e verificare che l'app per le funzioni mostri "In esecuzione" nel portale di Azure.

2. Nel portale di Azure, verifica che le impostazioni dell'app in Settings>Environment variables includano EventGrid__topicEndpoint e (se si usa l'identità gestita) EventGrid__credential.

3. Attivare un'orchestrazione usando un client HTTP:

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

4. Nel portale di Azure passare all'app per le funzioni listener>EventGridTrigger>Monitor per visualizzare gli eventi ricevuti. Dovrebbero essere visualizzati eventi con soggetti come durable/orchestrator/Running e durable/orchestrator/Completed.

Verificare in Application Insights (facoltativo)

Per una visualizzazione più completa, eseguire questa query KQL nei log di Application Insights dell'app per le funzioni:

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

Risoluzione dei problemi

Gli eventi non vengono pubblicati in Griglia di eventi

Problema: la funzione listener non riceve eventi.

Soluzioni:

• Verificare che l'app di Durable Functions abbia le impostazioni corrette:
  • EventGrid__topicEndpoint deve puntare all'endpoint dell'argomento personalizzato
  • EventGrid__credential deve essere impostato su managedidentity
  • EventGrid__clientId deve essere impostato se si usa un'identità assegnata dall'utente
• Verificare che l'identità gestita abbia il ruolo Mittente di dati EventGrid assegnato all'argomento personalizzato di Griglia di eventi.
• Controllare i log dell'app per le funzioni Durable Functions in Application Insights per verificare la presenza di errori.
• Verificare che l'argomento di Griglia di eventi esista e sia accessibile nella stessa sottoscrizione.

La funzione listener non viene attivata

Problema: la funzione listener esiste ma non è in esecuzione quando vengono pubblicati gli eventi.

Soluzioni:

• Verificare che la sottoscrizione di Griglia di eventi sia stata creata e che sia abilitata:
  • Nel portale di Azure passare all'argomento griglia di eventi → Subscriptions
  • Verificare che la sottoscrizione della funzione listener sia elencata con lo stato Abilitato
• Verificare che la sottoscrizione di Griglia di eventi usi il tipo di endpoint corretto:
  • Per Funzioni di Azure, usare --endpoint-type azurefunction con l'ID risorsa della funzione
  • Se è stato usato --endpoint-type webhook, verificare che l'URL del webhook sia nel formato corretto: https://<function-app>.azurewebsites.net/runtime/webhooks/eventgrid?functionName=<function-name>&code=<system-key>
• Controllare i log dell'applicazione listener per individuare errori o problemi di recapito.
• Nell'argomento Griglia di eventi → Metriche verificare la presenza di eventi eliminati che possono indicare errori di recapito.

Errori di autenticazione o "Accesso negato" nei log

Problema: errori di autenticazione durante la pubblicazione in Griglia di eventi.

Soluzioni:

• Verificare che l'identità gestita sia configurata correttamente e abilitata nell'app per le funzioni Durable Functions:
  • Nel portale di Azure passare all'app per le funzioni → Identity
  • Confermare che lo stato mostri Attivo per l'identità assegnata dal sistema o assegnata dall'utente
• Verificare che l'assegnazione di ruolo sia corretta:
  • Passare all'argomento di Griglia di eventi → Controllo di accesso (IAM)
  • Verificare che l'identità gestita abbia il ruolo Mittente di dati EventGrid (nota: nessuno spazio tra "Event" e "Grid")
  • La propagazione dell'assegnazione di ruolo può richiedere da 5 a 10 minuti

Errori di tipo "Connessione rifiutata" o "Endpoint non trovato"

Problema: errori di connessione all'argomento griglia di eventi.

Soluzioni:

• Verificare che l'endpoint dell'argomento di Griglia di eventi nelle impostazioni dell'app sia corretto e includa l'URL completo (ad esempio, https://my-topic.eventgrid.azure.net/api/events)
• Verificare che la risorsa dell'argomento di Event Grid esista nella stessa sottoscrizione e nella stessa regione
• Verificare che l'app Durable Functions abbia accesso di rete all'endpoint di Griglia di eventi

Testare localmente

Per testare localmente, vedere Test locali con l'app web del visualizzatore. Quando si esegue il test in locale con identità gestita, usare le credenziali dello sviluppatore per eseguire l'autenticazione nell'argomento Griglia di eventi. Per informazioni dettagliate, vedere Configurare Durable Functions con identità gestita - Sviluppo locale.

Pulire le risorse

Se non si intende continuare a usare le risorse create in questa esercitazione, eliminarle per evitare addebiti.

Eliminare i gruppi di risorse

Eliminare sia i gruppi di risorse che tutte le risorse contenute:

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

Eliminare singole risorse

Per conservare alcune risorse, è possibile eliminarle singolarmente:

1. Eliminare la sottoscrizione di Griglia di eventi:

   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. Eliminare l'argomento griglia di eventi:

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

3. Eliminare le app per le funzioni:

   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. Eliminare gli account di archiviazione:

   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
   

Passaggi successivi

Altre informazioni su:

• Gestione delle istanze
• Controllo delle versioni in Durable Functions