Configuración de la publicación de Durable Functions en Azure Event Grid

La publicación de eventos de ciclo de vida de orquestación en Azure Event Grid permite la automatización de DevOps (como implementaciones azules o verdes), paneles de supervisión en tiempo real y seguimiento de procesos en segundo plano de larga duración.

Prerrequisitos

• Un proyecto de Durable Functions implementado en Azure. Si no tiene uno, cree uno con el inicio rápido para su idioma preferido:

  • C# (modelo de trabajo aislado) | JavaScript | Python | PowerShell | Java

• La versión correcta de la extensión de Durable Functions. Para .NET, actualice la extensión a la versión más reciente:

  • 2.7.0+ (en proceso)

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

  • 1.1.0+ (trabajo aislado)

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

  Para otros idiomas, compruebe package.json, requirements.txt, pom.xml o requirements.psd1.

• Identidad administrada habilitada y configurada en la aplicación de funciones.

• Un proveedor de almacenamiento en ejecución o el emulador de almacenamiento de Azurite local.

• CLI de Azure o Azure Cloud Shell.

• Una Herramienta de prueba HTTP que mantiene los datos seguros.

Creación de un tema personalizado de Event Grid

Puede crear un tema de Event Grid para enviar eventos desde Durable Functions mediante the CLI de Azure, PowerShell o the Azure portal.

En esta guía se usa el CLI de Azure.

Creación de un grupo de recursos

Cree un grupo de recursos con el comando az group create. Elija una ubicación que admita Event Grid y coincida con la ubicación en la que desea implementar los recursos.

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

Habilitar el proveedor de recursos de Event Grid

1. Si es la primera vez que usa Event Grid en su suscripción de Azure, es posible que tenga que registrar el proveedor de recursos de Event Grid. Ejecute el siguiente comando para registrar el proveedor:

   az provider register --namespace Microsoft.EventGrid
   

2. El registro puede tardar unos instantes en finalizar. Para comprobar el estado, ejecute el comando siguiente:

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

   Cuando registrationState sea Registered, estará preparado para continuar.

Creación de un tema personalizado

Un tema de Event Grid proporciona un punto de conexión definido por el usuario en el que se publica el evento. Reemplace <topic-name> en el comando siguiente por un nombre único para el tema. El nombre del tema debe ser único porque se convierte en una entrada DNS.

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

Obtención del punto de conexión del tema

Obtenga el punto de conexión del tema. Reemplace <topic-name> en los siguientes comandos por el nombre que eligió.

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

Guarde este punto de conexión para más adelante.

Configuración de la publicación de Event Grid con identidad administrada (recomendado)

Las identidades administradas en Azure permiten que los recursos se autentiquen en los servicios de Azure sin almacenar credenciales, lo que simplifica la seguridad y la administración de identidades. Asigne la identidad administrada asociada a la aplicación Durable Function al tema personalizado de Event Grid.

Configuración de la aplicación de publicador de Durable Functions

Aunque la aplicación Durable Functions publica automáticamente eventos de ciclo de vida de orquestación en Event Grid, debe configurar las opciones de conexión. Agregue lo siguiente a la sección extensions.durableTask en su host.json.

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

Asignación del rol remitente de datos de Event Grid

Conceda permiso a la identidad administrada para publicar eventos en el tema de 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

Configuración de aplicaciones

Una vez que haya habilitado la identidad administrada para la aplicación de funciones y el tema, configure las opciones de la aplicación de Event Grid en la aplicación de funciones de 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>"

Suscripción a los eventos

Para recibir los eventos de ciclo de vida publicados, cree una suscripción de Event Grid que enruta los eventos del tema personalizado a un suscriptor. Entre los tipos de suscriptor comunes se incluyen Azure Functions (con un desencadenador de Event Grid), Logic Apps y webhooks.

En el ejemplo siguiente se crea una aplicación de función de suscriptor con un desencadenador de Event Grid mediante el CLI de Azure. Si ya tiene un suscriptor, ir a Crear una suscripción de Event Grid.

Creación de una aplicación de función de agente de escucha

Cree una aplicación de funciones para hospedar el desencadenador de Event Grid. El suscriptor debe estar en la misma región que el tema de 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>

Creación e implementación de una función de desencadenador de Event Grid

Generar estructura para un proyecto local, agregar un disparador de Event Grid y publicarlo

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>

Creación de una suscripción de Event Grid

Cree la suscripción utilizando el tipo de endpoint azurefunction, que gestiona automáticamente la validación 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

Esquema del evento

Cuando cambia un estado de orquestación, el Durable Functions runtime publica un evento con la siguiente estructura. Los eventos se generan automáticamente para cada transición de estado; no es necesario agregar ningún código.

Event Grid garantiza la entrega al menos una vez, por lo que puede recibir eventos duplicados en escenarios de errores poco frecuentes. Considere agregar lógica de desduplicación mediante el instanceId si es necesario.

Verificar la entrega de eventos

Para comprobar la configuración de un extremo a otro, implemente la aplicación de Durable Functions y desencadene una orquestación:

1. Publicar el código de función en Azure y comprobar que la aplicación de funciones muestra "En ejecución" en el portal de Azure.

2. En el portal de Azure, compruebe la configuración de la aplicación en Settings> Variables de entorno incluya EventGrid__topicEndpoint y (si usa la identidad administrada) EventGrid__credential.

3. Desencadene una orquestación mediante un cliente HTTP:

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

4. En el portal de Azure, vaya a la aplicación de funciones listener>EventGridTrigger>Monitor para ver los eventos recibidos. Debería ver eventos con temas como durable/orchestrator/Running y durable/orchestrator/Completed.

Comprobación en Application Insights (opcional)

Para obtener una vista más completa, ejecute esta consulta KQL en los registros de Application Insights de la aplicación de funciones:

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

Solución de problemas

Los eventos no se publican en Event Grid

Problema: la función de escucha no recibe eventos.

Soluciones:

• Compruebe que la aplicación de funciones de Durable Functions tiene la configuración correcta de la aplicación:
  • EventGrid__topicEndpoint debe apuntar al punto de conexión del tema personalizado
  • EventGrid__credential se debe establecer en managedidentity
  • EventGrid__clientId debe establecerse si se usa una identidad asignada por el usuario.
• Compruebe que la identidad administrada tiene asignado el rol Remitente de datos de EventGrid al tema personalizado de Event Grid.
• Compruebe los registros de la aplicación de funciones de Durable Functions en Application Insights para ver si hay errores.
• Compruebe que el tema de Event Grid existe y es accesible en la misma suscripción.

La función de listener no se activa

Problema: la función de escucha existe, pero no se está ejecutando cuando se publican eventos.

Soluciones:

• Compruebe que se creó la suscripción a Event Grid y que está habilitada:
  • En el portal de Azure, vaya al tema de Event Grid → Subscriptions
  • Confirme que la suscripción de la función de escucha aparece con el estado Habilitado
• Compruebe que la suscripción de Event Grid usa el tipo de punto de conexión correcto:
  • Para Azure Functions, utilice --endpoint-type azurefunction con el identificador de recurso de la función.
  • Si ha usado --endpoint-type webhook, asegúrese de que la dirección URL del webhook tiene el formato correcto: https://<function-app>.azurewebsites.net/runtime/webhooks/eventgrid?functionName=<function-name>&code=<system-key>
• Revise los registros de la aplicación de la función de escucha para detectar errores o problemas de entrega.
• En el tema de Event Grid → Métricas, busque Eventos descartados que pueden indicar errores de entrega.

"Prohibido" o errores de autenticación en los registros

Problema: errores de autenticación al publicar en Event Grid.

Soluciones:

• Compruebe que la identidad administrada está configurada y habilitada correctamente en la aplicación de funciones de Durable Functions:
  • En el portal de Azure, vaya a la aplicación de funciones → Identity
  • Asegúrese de que el "Estado" muestra Activado para la identidad asignada por el sistema o por el usuario.
• Compruebe que la asignación de roles es correcta:
  • Vaya al tema de Event Grid → Access Control (IAM)
  • Confirme que la identidad administrada tiene el rol EventGrid Data Sender (nota: sin espacio entre "Event" y "Grid")
  • La asignación de roles puede tardar entre 5 y 10 minutos en propagarse.

Errores de "Conexión rechazada" o "punto de conexión no encontrado"

Problema: errores de conexión al tema de Event Grid.

Soluciones:

• Compruebe que el punto de conexión del tema de Event Grid en la configuración de la aplicación es correcto e incluye la dirección URL completa (por ejemplo, https://my-topic.eventgrid.azure.net/api/events).
• Compruebe que el recurso de tema de Event Grid existe en la misma suscripción y región.
• Compruebe que la aplicación de Durable Functions tenga acceso de red al punto de conexión de Event Grid.

Probar localmente

Para probar localmente, consulte Pruebas locales con la aplicación web visor. Al probar localmente con identidad administrada, use las credenciales de desarrollador para autenticarse en el tema de Event Grid. Consulte Configuración de Durable Functions con identidad administrada: desarrollo local para obtener más información.

Limpieza de recursos

Si no va a seguir usando los recursos creados en este tutorial, elimínelos para evitar incurrir en cargos.

Eliminación de los grupos de recursos

Elimine los grupos de recursos y todos sus recursos contenidos:

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

Eliminación de recursos individuales

Si desea conservar algunos recursos, puede eliminarlos individualmente:

1. Elimine la suscripción de 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. Elimine el tema de Event Grid:

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

3. Elimine las aplicaciones de función:

   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. Elimine las cuentas de almacenamiento:

   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
   

Pasos siguientes

Más información sobre:

• Administración de instancias
• Control de versiones en Durable Functions