Publicar en temas de espacio de nombres y consumir eventos en Azure Event Grid

Artículo
02/20/2024

En este artículo se proporciona una introducción rápida a la entrega de extracción mediante el comando de shell de bash curl para publicar, recibir y confirmar eventos. Los recursos de Event Grid se crean mediante comandos de la CLI. Este artículo es adecuado para una prueba rápida de la funcionalidad de entrega de extracción. Para obtener código de ejemplo con los SDK del plano de datos, consulta las muestras de .NET o Java. Para Java, proporcionamos el código de ejemplo en dos artículos: inicios rápidos depublicar eventos y recibir eventos. Para obtener más información sobre el modelo de entrega de extracción, consulta los artículos Conceptos y Introducción a la entrega de extracción.

Si no tiene una suscripción a Azure, cree una cuenta gratuita de Azure antes de empezar.

Requisitos previos

Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.
Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.
- Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.
- En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.
- Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

En este artículo se necesita la versión 2.0.70 de la CLI de Azure, o cualquier versión posterior. Si usa Azure Cloud Shell, ya está instalada la versión más reciente.

Crear un grupo de recursos

Cree un grupo de recursos de Azure con el comando az group create. Este grupo de recursos se usa para contener todos los recursos creados en este artículo.

Los pasos generales para usar Cloud Shell para ejecutar comandos son:

Seleccione Abrir Cloud Shell para ver una ventana de Azure Cloud Shell en el panel derecho.
Copie el comando y péguelo en la ventana de Azure Cloud Shell.
Presione ENTRAR para ejecutar el comando.

Declare una variable para contener el nombre de un grupo de recursos de Azure. Especifique un nombre para el grupo de recursos reemplazando <your-resource-group-name> por un valor que desee.
```
resource_group="<your-resource-group-name>"
```
Cree un grupo de recursos. Cambie la ubicación como considere oportuno.
```
az group create --name $resource_group --location eastus
```

Habilitar el proveedor de recursos de Event Grid

Si aún no ha usado anteriormente Event Grid en su suscripción de Azure, puede 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
```
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 espacio de nombres

Un espacio de nombres de Event Grid proporciona un punto de conexión definido por el usuario en el que se publican los eventos. En el ejemplo siguiente se crea en un grupo de recursos el espacio de nombres mediante Bash en Azure Cloud Shell. El nombre del espacio de nombres debe ser único porque forma parte de una entrada del Sistema de nombres de dominio (DNS). Un nombre de espacio de nombres debe cumplir las reglas siguientes:

Debe tener entre 3 y 50 caracteres.
Debe ser único en la región.
Los únicos caracteres permitidos son a-z, A-Z, 0-9 y -
No debe empezar con prefijos de palabra clave reservados como Microsoft, System o EventGrid.

Declare una variable para contener el nombre del espacio de nombres de Event Grid. Especifique un nombre para el espacio de nombres reemplazando <your-namespace-name> con un valor que desee.
```
namespace="<your-namespace-name>"
```
Cree un espacio de nombres. Es posible que quiera cambiar la ubicación en la que se implementa.
```
az eventgrid namespace create -g $resource_group -n $namespace -l eastus
```

Creación de un tema de espacio de nombres

Cree un tema que se use para contener todos los eventos publicados en el punto final del espacio de nombres.

Declare una variable para contener el nombre de su tema de espacio de nombres. Especifique un nombre para el tema del espacio de nombres reemplazando <your-topic-name> con un valor que desee.
```
topic="<your-topic-name>"
```

Cree el tema del espacio de nombres:

az eventgrid namespace topic create -g $resource_group -n $topic --namespace-name $namespace

Creación de una suscripción a evento

Cree una suscripción de eventos que establezca su modo de entrega en cola, que admite la entrega de extracción. Para más información sobre todas las opciones de configuración, consulte la API de REST del plano de control de Event Grid más reciente.

Declare una variable para contener el nombre de una suscripción de eventos al tema del espacio de nombres. Especifique un nombre para la suscripción de eventos reemplazando <your-event-subscription-name> por un valor que desee.
```
event_subscription="<your-event-subscription-name>"
```

Cree una suscripción de eventos al tema del espacio de nombres:

az eventgrid namespace topic event-subscription create -g $resource_group --topic-name $topic -n $event_subscription --namespace-name $namespace --delivery-configuration "{deliveryMode:Queue,queue:{receiveLockDurationInSeconds:300,maxDeliveryCount:4,eventTimeToLive:P1D}}"

Envío de eventos al tema

Ahora, envíe un evento de ejemplo al tema de espacio de nombres siguiendo los pasos de esta sección.

Enumeración de las claves de acceso del espacio de nombres

Obtenga las claves de acceso asociadas con el espacio de nombres que creó. Usará una de ellas para autenticarse al publicar eventos. Para enumerar sus claves, primero necesita el id. de recurso de espacio de nombres completo. Para obtenerlo, ejecute el siguiente comando:
```
namespace_resource_id=$(az eventgrid namespace show -g $resource_group -n $namespace --query "id" --output tsv)
```

Obtenga la primera clave del espacio de nombres:

key=$(az eventgrid namespace list-key -g $resource_group --namespace-name $namespace --query "key1" --output tsv)

Publicación de un evento

Recupere el nombre de host del espacio de nombres. Se usa para crear el punto de conexión HTTP del espacio de nombres al que se envían los eventos. Las siguientes operaciones estaban disponibles por primera vez con la versión de API 2023-06-01-preview.
```
publish_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic:publish?api-version=2023-06-01-preview
```
Cree un evento de ejemplo compatible con CloudEvents:
```
event=' { "specversion": "1.0", "id": "'"$RANDOM"'", "type": "com.yourcompany.order.ordercreatedV2", "source" : "/mycontext", "subject": "orders/O-234595", "time": "'`date +%Y-%m-%dT%H:%M:%SZ`'", "datacontenttype" : "application/json", "data":{ "orderId": "O-234595", "url": "https://yourcompany.com/orders/o-234595"}} '
```
El elemento data es la carga del evento. En este campo, puede usar cualquier archivo JSON bien formado. Consulte las especificaciones de CloudEvents para obtener más información sobre las propiedades (también conocidas como atributos de contexto) que pueden ir en un evento.

Use CURL para enviar el evento al tema. CURL es una utilidad que envía solicitudes HTTP.

curl -X POST -H "Content-Type: application/cloudevents+json" -H "Authorization:SharedAccessKey $key" -d "$event" $publish_operation_uri

Recepción del evento

Recibe eventos de Event Grid mediante un punto de conexión que hace referencia a una suscripción de eventos.

Componga ese punto final ejecutando el siguiente comando:

receive_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:receive?api-version=2023-06-01-preview

Envíe una solicitud para consumir el evento:

curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" $receive_operation_uri

Confirmación de un evento

Después de recibir un evento, pasará ese evento a la aplicación para su procesamiento. Una vez que haya procesado correctamente el evento, ya no necesitará que ese evento esté en la suscripción de eventos. Para indicar a Event Grid que elimine el evento, lo tiene que confirmar mediante su token de bloqueo que obtuvo en la respuesta de la operación de recepción.

En el paso anterior, debería haber recibido una respuesta que incluye un objeto brokerProperties con una propiedad lockToken. Copie el valor del token de bloqueo y establézcalo en una variable de entorno:
```
lockToken="<paste-the-lock-token-here>"
```
Ahora, compile la carga de la operación de confirmación, que especifica el token de bloqueo para el evento que quiere confirmar.
```
acknowledge_request_payload=' { "lockTokens": ["'$lockToken'"]} '
```

Continúe con la compilación de la cadena con el URI de la operación de confirmación:

acknowledge_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:acknowledge?api-version=2023-06-01-preview

Por último, envíe una solicitud para confirmar el evento recibido:
```
curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" -d "$acknowledge_request_payload" $acknowledge_operation_uri
```
Si la operación de confirmación se ejecuta antes de que expire el token de bloqueo (300 segundos tal y como se estableció al crear la suscripción de eventos), debería ver una respuesta similar al siguiente ejemplo:
```
{"succeededLockTokens":["CiYKJDQ4NjY5MDEyLTk1OTAtNDdENS1BODdCLUYyMDczNTYxNjcyMxISChDZae43pMpE8J8ovYMSQBZS"],"failedLockTokens":[]}
```

Pasos siguientes

Para más información sobre el modelo de entrega de extracción, consulte Introducción a la entrega de extracción.