Cómo trabajar con desencadenadores y enlaces de Event Grid en Azure Functions

Artículo
06/01/2023

Azure Functions proporciona integración incorporada con Azure Event Grid mediante desencadenadores y enlaces. En este artículo, se muestra cómo configurar y evaluar localmente el desencadenador y los enlaces de Event Grid. Para más información acerca de las definiciones y los ejemplos del enlace de salida y el desencadenador de Event Grid, consulte uno de los siguientes artículos de referencia:

Suscripciones a eventos

Para empezar a recibir solicitudes HTTP de Event Grid, necesita una suscripción a los eventos generados por Event Grid. Las suscripciones de eventos especifican la dirección URL del punto de conexión que invoca la función. Al crear una suscripción de eventos desde la pestaña Integración de la función en Azure Portal, la dirección URL se proporciona automáticamente. Al crear una suscripción de eventos mediante programación o al crear la suscripción de eventos desde Event Grid, deberá proporcionar el punto de conexión. La dirección URL del punto de conexión contiene una clave del sistema, que debe obtener de las API de REST del administrador de Functions.

Dirección URL del punto de conexión de webhook

El punto de conexión de dirección URL de la función desencadenada de Event Grid depende de la versión del runtime de Functions. En el siguiente ejemplo se muestra el patrón de la dirección URL específico de la versión:

v2.x+
v1.x

https://{functionappname}.azurewebsites.net/runtime/webhooks/eventgrid?functionName={functionname}&code={systemkey}

https://{functionappname}.azurewebsites.net/admin/extensions/EventGridExtensionConfig?functionName={functionname}&code={systemkey}

Nota:

Hay una versión del desencadenador de Blob Storage que también usa suscripciones de eventos. La dirección URL del punto de conexión de este tipo de desencadenador de Blob Storage tiene una ruta de acceso de /runtime/webhooks/blobs, mientras que la ruta de acceso de un desencadenador de Event Grid sería /runtime/webhooks/EventGrid. Para obtener una comparación de las opciones de procesamiento de blobs, consulte Desencadenador en un contenedor de blobs.

Clave del sistema

El punto de conexión de dirección URL que construya incluye el valor de la clave del sistema. La clave de sistema es una clave de autorización que debe incluirse en la dirección URL del punto de conexión para desencadenador de Event Grid. En la siguiente sección se explica cómo obtener la clave del sistema.

Puede obtener la clave del sistema mediante la siguiente API (HTTP GET):

v2.x y posteriores
v1.x

http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgrid_extension?code={masterkey}

http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgridextensionconfig_extension?code={masterkey}

Esta API REST es una API de administrador, por lo que requiere la clave maestra de la aplicación de funciones. No confunda la clave del sistema (para invocar una función de desencadenador de Event Grid) con la clave maestra (para realizar tareas administrativas en la aplicación de función). Cuando se suscriba a un tema de Event Grid, asegúrese de usar la clave del sistema.

Este es un ejemplo de la respuesta que proporciona la clave del sistema:

{
  "name": "eventgridextensionconfig_extension",
  "value": "{the system key for the function}",
  "links": [
    {
      "rel": "self",
      "href": "{the URL for the function, without the system key}"
    }
  ]
}

Puede obtener la clave maestra de la aplicación de función en la pestaña Configuración de Function App del portal.

Importante

La clave maestra proporciona acceso de administrador a la aplicación de función. Esta clave no debe compartirse con terceros ni distribuirse en aplicaciones cliente nativas.

Para más información, consulte Claves de autorización en el artículo de referencia del desencadenador HTTP.

Creación de una suscripción a evento

Puede crear una suscripción de eventos desde Azure Portal o mediante la CLI de Azure.

Portal
CLI de Azure

En el caso de las funciones que se desarrollen en Azure Portal con el desencadenador de Event Grid, seleccione Integración y, después, elija Desencadenador de Event Grid y seleccione Crear suscripción de Event Grid.

Screenshot of connecting to a new event subscription to trigger in the portal.

Al seleccionar este vínculo, el portal abre la página Crear suscripciones de eventos con el punto de conexión del desencadenador actual ya definido.

Screenshot of creating an event subscription with the function endpoint already defined.

Para obtener más información sobre cómo crear suscripciones mediante el Azure Portal, consulte Creación de eventos personalizados: Azure Portal en la documentación de Event Grid.

Para crear una suscripción mediante el uso de la CLI de Azure, utilice el comando az eventgrid event-subscription create. En los ejemplos se usa la versión v2.x+ de la dirección URL y se escriben para ejecutarse en Azure Cloud Shell. Deberá modificar los ejemplos para que se ejecuten desde un símbolo del sistema de Windows.

En este ejemplo se crea una suscripción a una cuenta de almacenamiento de blobs, con un marcador de posición para la clave del sistema:

az eventgrid resource event-subscription create -g myResourceGroup \
    --provider-namespace Microsoft.Storage --resource-type storageAccounts \
    --resource-name myblobstorage12345 --name myFuncSub \
    --included-event-types Microsoft.Storage.BlobCreated \
    --subject-begins-with /blobServices/default/containers/images/blobs/ \
    --endpoint https://mystoragetriggeredfunction.azurewebsites.net/runtime/webhooks/eventgrid?functionName=imageresizefunc&code=<key>

Para más información sobre cómo crear una suscripción, consulte la guía de inicio rápido sobre el almacenamiento de blobs o cualquiera de las demás guías de inicio rápido de Event Grid.

Pruebas locales con la aplicación web de visor

Para probar localmente un desencadenador de Event Grid, debe enviar las solicitudes HTTP de Event Grid desde su origen en la nube a la máquina local. Una manera de hacerlo es mediante la captura de solicitudes en línea y de reenviarlas manualmente a la máquina local:

Cree una aplicación web de visor que capture los mensajes de eventos.
Cree una suscripción a Event Grid que envíe eventos a la aplicación de visor.
Genere una solicitud y copie el cuerpo de la solicitud desde la aplicación de visor.
Envíe manualmente la solicitud a la dirección URL de localhost de la función del desencadenador de Event Grid.

Cuando haya finalizado las pruebas, puede utilizar la misma suscripción para producción actualizando el punto de conexión. Use el comando az eventgrid event-subscription update de la CLI de Azure.

También puede usar la utilidad ngrok para reenviar solicitudes remotas a las funciones que se ejecutan localmente. Para obtener más información, consulte este tutorial.

Creación de una aplicación web de visor

Para simplificar la captura de mensajes de evento, puede implementar una aplicación web de ejemplo que muestre los mensajes de los eventos. La solución implementada incluye un plan de App Service, una aplicación web de App Service y el código fuente desde GitHub.

Seleccione Deploy to Azure (Implementar en Azure) para implementar la solución en su suscripción. En Azure Portal, proporcione valores para los parámetros.

La implementación puede tardar unos minutos en completarse. Después de que la implementación se haya realizado correctamente, puede ver la aplicación web para asegurarse de que se está ejecutando. En un explorador web, vaya a: https://<your-site-name>.azurewebsites.net

Verá el sitio, pero aún no se ha publicado en él ningún evento.

View new site

Creación de una suscripción de Event Grid

Cree una suscripción de Event Grid del tipo que desee probar y asígnele la dirección URL de su aplicación web como punto de conexión para la notificación de eventos. El punto de conexión de la aplicación web debe incluir el sufijo /api/updates/. Por lo tanto, dirección URL completa es https://<your-site-name>.azurewebsites.net/api/updates

Para obtener información sobre cómo crear suscripciones mediante Azure Portal, consulte Creación de eventos personalizados: Azure Portal en la documentación de Event Grid.

Generación de una solicitud

Desencadene un evento que generará tráfico HTTP a su punto de conexión de aplicación web. Por ejemplo, si crea una suscripción de almacenamiento de blobs, cargue o elimine un blob. Cuando aparezca una solicitud en la aplicación web, copie el cuerpo de la solicitud.

La solicitud de validación de la suscripción se recibirá primero; ignore cualquier solicitud de validación y copie la solicitud del evento.

Copy request body from web app

Envío manual de la solicitud

Ejecute la función de Event Grid localmente. Es necesario establecer manualmente los encabezados Content-Type y aeg-event-type, mientras que todos los demás valores se pueden dejar como valores predeterminados.

Use una herramienta como Postman o curl para crear una solicitud HTTP POST:

Establezca un encabezado Content-Type: application/json.
Establezca un encabezado aeg-event-type: Notification.
Pegue los datos de RequestBin en el cuerpo de la solicitud.

Envíe la dirección URL de la función del desencadenador de Event Grid.

v2.x y posteriores
v1.x

http://localhost:7071/runtime/webhooks/eventgrid?functionName={FUNCTION_NAME}

http://localhost:7071/admin/extensions/EventGridExtensionConfig?functionName={FUNCTION_NAME}

El parámetro functionName debe ser el nombre especificado en el atributo FunctionName.

Las capturas de pantalla siguientes muestran los encabezados y el cuerpo de la solicitud en Postman:

Headers in Postman

Request body in Postman

La función de desencadenador de Event Grid ejecuta y muestra registros similares a los del ejemplo siguiente:

Sample Event Grid trigger function logs

Pasos siguientes

Para más información sobre Event Grid con Functions, consulte los siguientes artículos: