Compartir vía

Esquema de eventos de Azure Event Grid

  • Artículo

En este artículo se describe el esquema de Event Grid, que es un formato de su propiedad, no extensible, pero totalmente funcional. Event Grid sigue admitiendo este formato de evento y seguirá admitiéndolo. Sin embargo, CloudEvents es el formato de evento recomendado que se va a usar. Si usa aplicaciones que usan el formato de Event Grid, puede resultar útil la información de la sección [CloudEvents] que describe las transformaciones entre el formato Event Grid y CloudEvents admitido por Event Grid.

En este artículo se describen detalladamente las propiedades y el esquema para el formato de Event Grid. Los eventos constan de un conjunto de cuatro propiedades de cadena. Las propiedades son comunes a todos los eventos de cualquier anunciante. El objeto de datos tiene propiedades específicas de cada publicador. Para los temas de sistema, estas propiedades son específicas del proveedor de recursos, como Azure Storage o Azure Event Hubs.

Los orígenes de eventos envían eventos a Azure Event Grid en una matriz que puede tener varios objetos de evento. Al publicar eventos en un tema de Event Grid, la matriz puede tener un tamaño total de hasta 1 MB. Cada evento de la matriz tiene 1 MB, como máximo. Si un evento o la matriz superan los límites de tamaño, recibirá la respuesta 413 Payload Too Large (Carga útil demasiado grande). No obstante, las operaciones se cobran en incrementos de 64 KB. Así, los eventos de más de 64 kB incurren en gastos de operación como si fueran eventos múltiples. Por ejemplo, un evento que tenga 130 KB incurrirá en operaciones como si fueran tres eventos independientes.

Event Grid envía los eventos a los suscriptores en una matriz que tiene un solo evento. Este comportamiento puede cambiar en el futuro.

Puede encontrar el esquema JSON para el evento de Event Grid y cada carga de datos del publicador de Azure en el almacén de esquemas de eventos.

Nota:

La compatibilidad con el esquema de eventos de Event Grid no se retirará, pero no se realizarán mejoras importantes en él en el futuro. Se recomienda usar el esquema CloudEvents, que proporciona una definición estandarizada y independiente del protocolo de la estructura y la descripción de metadatos de los eventos. Para más información, consulte Esquema de CloudEvents v1.0 con Azure Event Grid.

Esquema del evento

En el ejemplo siguiente se muestran las propiedades que todos los publicadores de eventos usan:

[
  {
    "topic": string,
    "subject": string,
    "id": string,
    "eventType": string,
    "eventTime": string,
    "data":{
      object-unique-to-each-publisher
    },
    "dataVersion": string,
    "metadataVersion": string
  }
]

Por ejemplo, el esquema publicado para un evento de Azure Blob Storage es:

[
  {
    "topic": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contosorg/providers/Microsoft.Storage/storageAccounts/contosostorage",
    "subject": "/blobServices/default/containers/testcontainer/blobs/dataflow.jpg",
    "eventType": "Microsoft.Storage.BlobCreated",
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "data": {
      "api": "PutBlob",
      "clientRequestId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "requestId": "cccccccc-2222-3333-4444-dddddddddddd",
      "eTag": "0x8DD15A69488FE5A",
      "contentType": "image/jpeg",
      "contentLength": 52577,
      "blobType": "BlockBlob",
      "accessTier": "Default",
      "url": "https://contosostorage.blob.core.windows.net/testcontainer/dataflow.jpg",
      "sequencer": "0000000000000000000000000003A13C00000000007da85d",
      "storageDiagnostics": {
        "batchId": "9d292d9f-e006-00a5-008f-47b300000000"
      }
    },
    "dataVersion": "",
    "metadataVersion": "1",
    "eventTime": "2024-12-06T03:32:15.7238874Z"
  }
]

Propiedades de evento

Todos los eventos tienen los mismos datos de nivel superior, que son los siguientes:

Propiedad Type Obligatorio Description
topic string No, pero si se incluye, debe coincidir exactamente con el identificador de Azure Resource Manager del tema Event Grid. Si no se incluye, Event Grid se marca en el evento. Ruta de acceso completa a los recursos del origen del evento. En este campo no se puede escribir. Event Grid proporciona este valor.
subject string Sí Ruta al asunto del evento definida por el anunciante.
eventType string Sí Uno de los tipos de eventos registrados para este origen de eventos.
eventTime string Sí La hora de generación del evento en función de la hora UTC del proveedor.
id string Sí Identificador único para el evento
data object Sí Los datos del evento específicos del proveedor de recursos.
dataVersion string No, pero se marcará con un valor vacío. Versión del esquema del objeto de datos. El publicador define la versión del esquema.
metadataVersion string No es necesario, pero si se incluye, debe coincidir exactamente con el esquema metadataVersion de Event Grid (actualmente, solo 1). Si no se incluye, Event Grid se marca en el evento. Versión del esquema de los metadatos del evento. Event Grid define el esquema de las propiedades de nivel superior. Event Grid proporciona este valor.

Para obtener información sobre las propiedades del objeto de datos, consulte los artículos de esta sección: Temas del sistema.

Para temas personalizados, el publicador de eventos determina el objeto de datos. Los datos de nivel superior deben tener los mismos campos que los eventos estándar definidos por recursos.

Al publicar eventos en temas personalizados, cree asuntos para los eventos que faciliten que los suscriptores sepan si les interesa el evento. Los suscriptores usan el asunto para filtrar y redirigir eventos. Considere la posibilidad de proporcionar la ruta de acceso de donde se produjo el evento, para que los suscriptores pueden filtrar por los segmentos de esa ruta de acceso. La ruta de acceso permite que los suscriptores filtren eventos de una manera más amplia o más restringida. Por ejemplo, si se proporciona una ruta de acceso de tres segmentos como /A/B/C en el asunto, los suscriptores pueden filtrar por el primer segmento /A para obtener un amplio conjunto de eventos. Esos suscriptores obtienen eventos con asuntos como /A/B/C o /A/D/E. Otros suscriptores pueden filtrar por /A/B para obtener un conjunto de eventos más reducido.

A veces el asunto necesita información más detallada sobre qué ocurrió. Por ejemplo, el publicador de cuentas de almacenamiento proporciona el asunto /blobServices/default/containers/<container-name>/blobs/<file> cuando se agrega un archivo a un contenedor. Un suscriptor puede filtrar por la ruta de acceso /blobServices/default/containers/<container-name>/ para obtener todos los eventos de ese contenedor, pero no otros contenedores en la cuenta de almacenamiento. Un suscriptor también puede filtrar o redirigir por el sufijo .txt para que funcione solo con archivos de texto.

CloudEvents

CloudEvents es el formato de evento recomendado que se va a usar. Azure Event Grid sigue invirtiendo en características relacionadas con al menos el formato JSON de CloudEvents. Dado que algunos orígenes de eventos como los servicios de Azure usan el formato de Event Grid, se proporciona la tabla siguiente para ayudarle a comprender la transformación admitida al usar los formatos de CloudEvents y Event Grid como esquema de entrada en temas y como esquema de salida en suscripciones de eventos. No se puede usar un esquema de salida de Event Grid al usar CloudEvents como esquema de entrada porque CloudEvents admite atributos de extensión que no son compatibles con el esquema de Event Grid.

Esquema de entrada Esquema de salida
Formato de CloudEvents Formato de CloudEvents
Formato de Event Grid Formato de CloudEvents
Formato de Event Grid Formato de Event Grid

Pasos siguientes