Compartir vía

Espacios de nombres de Azure Event Grid: compatibilidad con el esquema CloudEvents

  • Artículo

Los temas del espacio de nombres de Event Grid aceptan eventos que cumplen con la especificación de estándar abierto de Cloud Native Computing Foundation (CNCF) CloudEvents 1.0 mediante la especificación enlace de protocolo HTTP con formato JSON. CloudEvent es un tipo de mensaje que contiene tanto lo que se comunica, a lo que se denomina datos de eventos, como sus metadatos. Los datos de eventos en arquitecturas controladas por eventos normalmente llevan la información que anuncia un cambio de estado del sistema. Los metadatos de CloudEvents se componen de un conjunto de atributos que proporcionan información contextual sobre el mensaje como dónde se originó (el sistema de origen), su tipo, etc. Todos los mensajes válidos que se adhieren a las especificaciones de CloudEvents deben incluir los siguientes atributos de contexto necesarios:

La especificación CloudEvents también define atributos de contexto de extensión y opcionales que puede incluir al usar Event Grid.

Al usar Event Grid, CloudEvents es el formato de evento preferido debido a sus casos de uso bien documentados (modos para transferir eventos, formatos de eventos, etc.), extensibilidad y mejor interoperabilidad. CloudEvents mejora la interoperabilidad al proporcionar un formato de eventos común para la publicación y el consumo de eventos. Permite usar herramientas uniformes y formas estándar de enrutamiento y administración de eventos.

Modos de contenido de CloudEvents

La especificación CloudEvents define tres modos de contenido: binarios, estructurados y por lotes.

Importante

Con todos los modos de contenido se puede intercambiar texto (JSON, text/*, etc.) o datos de eventos con codificación binaria. El modo de contenido binario no se usa exclusivamente para enviar datos binarios.

Los modos de contenido no tienen que ver la codificación que se usa, binario o texto, sino con cómo se describen e intercambian los datos del evento y sus metadatos. El modo de contenido estructurado usa una sola estructura, por ejemplo, un objeto JSON, donde los atributos de contexto y los datos de eventos se unen en la carga HTTP. El modo de contenido binario separa los atributos de contexto, que se asignan a encabezados HTTP, y los datos de eventos, que son la carga HTTP codificada según el tipo de medio establecido en Content-Type.

Compatibilidad con CloudEvents

En esta tabla se muestra la compatibilidad actual con la especificación CloudEvents:

Modo de contenido de CloudEvents ¿Compatible?
JSON estructurado Sí
JSON estructurado por lotes Sí, para publicar eventos
Binario Sí, para publicar eventos

El tamaño máximo permitido para un evento es de 1 MB. Los eventos de más de 64 KB se cobran en incrementos de 64 KB.

Modo de contenido estructurado

Un mensaje en el modo de contenido estructurado de CloudEvents tiene los atributos de contexto y los datos del evento juntos en una carga HTTP.

Importante

Actualmente, Event Grid admite el formato JSON de CloudEvents con HTTP.

Este es un ejemplo de CloudEvents en modo estructurado mediante el formato JSON. Ambos metadatos (todos los atributos que no son "datos") y los datos de mensaje o evento (el objeto de "datos") se describen mediante JSON. En nuestro ejemplo se incluyen todos los atributos de contexto necesarios junto con algunos atributos opcionales (subject, time y datacontenttype) y atributos de extensión (comexampleextension1, comexampleothervalue).

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "subject" : "O-28964",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "application/json",
    "data" : {
       "orderId" : "O-28964",
       "URL" : "https://com.yourcompany/orders/O-28964"
    }
}

Puede usar el formato JSON con contenido estructurado para enviar datos de eventos que no son un valor JSON. Para ello, siga los pasos siguientes:

  1. Incluya un atributo datacontenttype con el tipo de medio en el que se codifican los datos.
  2. Si el tipo de medio se codifica en un formato de texto como text/plain, text/csv o application/xml, debe usar un atributo data con una cadena JSON que contenga lo que se comunica como valor.
  3. Si el tipo de medio representa una codificación binaria, debe usar un atributo data_base64 cuyo valor es una cadena JSON que contiene el valor binario codificado en BASE64.

Por ejemplo, este CloudEvent incluye datos de eventos codificados en application/protobuf para intercambiar mensajes Protobuf.

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "datacontenttype" : "application/protobuf",
    "data_base64" : "VGhpcyBpcyBub3QgZW5jb2RlZCBpbiBwcm90b2J1ZmYgYnV0IGZvciBpbGx1c3RyYXRpb24gcHVycG9zZXMsIGltYWdpbmUgdGhhdCBpdCBpcyA6KQ=="
}

Para obtener más información sobre el uso de los atributos data o data_base64, vea Control de datos.

Para obtener más información sobre este modo de contenido, consulte las especificaciones del modo de contenido estructurado HTTP de CloudEvents.

Modo de contenido por lotes

Event Grid admite actualmente el modo de contenido por lotes JSON al publicar CloudEvents en Event Grid. Este modo de contenido usa una matriz JSON rellenada con CloudEvents en modo de contenido estructurado. Por ejemplo, la aplicación puede publicar dos eventos mediante una matriz como la siguiente. Del mismo modo, si usa el SDK del plano de datos de Event Grid, esta carga también es lo que se envía:

[
    {
        "specversion": "1.0",
        "id": "E921-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": "some data"
    },
    {
        "specversion": "1.0",
        "id": "F555-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": {
            "somekey" : "value",
            "someOtherKey" : 9
        }
    }
]

Para obtener más información, consulte las especificaciones del modo de contenido por lotes de CloudEvents.

Procesamiento por lotes

La aplicación debe procesar por lotes varios eventos juntos en una matriz para lograr una mayor eficacia y un mayor rendimiento con una única solicitud de publicación. Los lotes pueden tener hasta 1 MB y el tamaño máximo de un evento es también de 1 MB.

Modo de contenido binario

CloudEvent en modo de contenido binario tiene sus atributos de contexto descritos como encabezados HTTP. Los nombres de los encabezados HTTP son el nombre del atributo de contexto prefijo con ce-. El encabezado Content-Type refleja el tipo de medio en el que se codifican los datos del evento.

Importante

Cuando se usa el modo de contenido binario, el encabezado HTTP ce-datacontenttype NO DEBE estar presente también.

Importante

Si planea incluir sus propios atributos (es decir, atributos de extensión) cuando use el modo de contenido binario, asegúrese de que sus nombres contienen letras minúsculas ( de la "a" a la "z") o dígitos (del "0" al "9") del carácter ASCII y que no superan los 20 caracteres de longitud. Es decir, la convención de nomenclatura de para nombrar los atributos de contexto de CloudEvents es más restrictiva que la de los nombres de encabezado HTTP válidos. No todos los nombres de encabezado HTTP válidos son un nombre de atributo de extensión válido.

La carga HTTP son los datos del evento codificados según el tipo de medio de Content-Type.

Una solicitud HTTP que se usa para publicar un CloudEvent en modo binario de contenido puede tener un aspecto similar al de este ejemplo:

POST / HTTP/1.1
HOST mynamespace.eastus-1.eventgrid.azure.net/topics/mytopic
ce-specversion: 1.0
ce-type: com.example.someevent
ce-source: /mycontext
ce-id: A234-1234-1234
ce-time: 2018-04-05T17:31:00Z
ce-comexampleextension1: value
ce-comexampleothervalue: 5
content-type: application/protobuf

Binary data according to protobuf encoding format. No context attributes are included.

Cuándo usar el modo de contenido binario o estructurado de CloudEvents

Puede usar el modo de contenido estructurado si desea un enfoque sencillo para reenviar CloudEvents entre saltos y protocolos. Dado que CloudEvent en modo de contenido estructurado contiene el mensaje, junto con sus metadatos, es fácil que los clientes lo consuman en su totalidad y lo reenvíen a otros sistemas.

Puede usar el modo de contenido binario si sabe que las aplicaciones de bajada solo requieren el mensaje sin información adicional (es decir, los atributos de contexto). Aunque con el modo de contenido estructurado todavía puede obtener los datos del evento (mensaje) de CloudEvent, es más fácil si una aplicación de consumidor solo la tiene en la carga HTTP. Por ejemplo, otras aplicaciones pueden usar otros protocolos y podrían estar interesadas solo en el mensaje principal, no en sus metadatos. De hecho, los metadatos podrían ser relevantes solo para el primer salto inmediato. En este caso, tener los datos que se desean intercambiar aparte de sus metadatos facilita tanto el manejo como el reenvío.

Contenido relacionado