Event schemas and properties (Event Grid)

EventGrid vs CloudEvents schema

Event Grid soporta dos event schemas

  • CloudEvents v1.0 schema: recomendado para nuevas implementaciones. Event structure standard y protocol-agnostic. Este standard implica que los eventos producidos por tus AI services pueden interoperar con cualquier sistema que soporte CloudEvents, no solo Event Grid. Simplifica la integración multi-plataforma.
  • Event Grid schema (propietario): se mantiene por backward compatibility. NO se pueden intercambiar mensajes cloudevents-eventgrid

CloudEvents schema structure

IMPORTANTE

{
    "specversion": "1.0",
    "type": "com.contoso.ai.InferenceCompleted",
    "source": "/services/content-moderation",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "time": "2025-09-15T14:30:00Z",
    "subject": "/pipelines/moderation/batch-42",
    "datacontenttype": "application/json",
    "data": {
        "modelName": "content-classifier-v3",
        "requestId": "req-78901",
        "resultLocation": "https://storage.blob.core.windows.net/results/batch-42.json",
        "processingDurationMs": 1250,
        "status": "success",
        "itemsProcessed": 150
    }
}

Los atributos requeridos son:

  • specversion identifica la spec version del CloudEvents. Se pone siempre a "1.0"
  • type categoriza el evento. permite filtrar luego por event type. Se usa reverse-DNS naming convention para evitar colisiones
  • source identifica el sistema origen. Combinado con type permite identificar el contexto donde el evento ocurre
  • id es unico de este evento. Los consumers lo usan para detectar y deduplicar deliveries repetidas

Atributos opcionales:

  • subject provee de un path para filtrar. Se usa con valores jerarquicos que reflejen el contexto del evento permitiendo filtrar por prefijos y sufijos
  • time cuando ocurre el evento
  • datacontenttype formato del payload
  • data payload como tal

IMPORTANTE

Design custom event types

Los event types tienen que tener pensamiento detrás y estar bien diseñados. Cada event type tiene que representar un cambio de estado con un significado, que al menos un consumer deba conocer.

Ejemplos:

  • com.contoso.ai.InferenceCompleted
  • com.contoso.ai.EmbeddingsRefreshed
  • com.contoso.ai.AnomalyDetected
  • com.contoso.ai.ContentClassified

El event payload debe ser pequeño y estar enfocado. Incluir suficiente contexto para que el consumer pueda comenzar a procesar como por ej: resource URI, model name, processing duration y result summary.
Si necesitamos incluir muchos datos no meterlos en el payload, pasar una URL y que el consumer haga el fetch de la BBDD o storage.

Configure event type filtering

Las event subscriptions pueden filtrar eventos por type para que cada consumer reciba solo los que realmente necesita.

Puedes configurar event type filtering cuando creas una event subscription con el param --included-event-types

az eventgrid event-subscription create \
	--name inference-handler-sub \
	--source-resource-id /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.EventGrid/topics/ai-events \
	--endpoint https://inference-handler.azurewebsites.net/api/events \
	--included-event-types com.contoso.ai.InferenceCompleted

Puedes incluir múltiples event types en una única subscripción

Subject filtering (granular routing)

El field subject permite un filtrado basado en un path, usando prefijos y sufijos. Ej: /pipelines/embeddings/batch-42

De este modo los subscribers pueden filtrar eventos basándose en la jerarquía donde el evento se originó.

Subject filtering usa dos params en la event subscription

  • subjectBeginsWith: se usa para filtrar pipes o categorías específicas
  • subjectWendsWith: se usa para filtrar por tipo, versión o estado
az eventgrid event-subscription create \
	--name embeddings-sub \ 
	--source-resource-id /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.EventGrid/topics/ai-events \
	--endpoint https://embeddings-handler.azurewebsites.net/api/events \
	--subject-begins-with /pipelines/embeddings

Advanced filtering

Event Grid soporta filtros avanzados para buscar matches dentro del event body o extension attributes. Estos filtros permiten tomar decisiones de routing basándose en el contenido del event data como confidence scores, model names o processing statuses.

Tienen operadores como:

  • StringContains
  • NumberGreaterThan
  • StringBeginsWith
  • BoolEquals
  • IsNotNull

Se pueden definir hasta 25 filtros POR SUBSCRIPCIÓN

crea una subscription que recibe solo eventos donde data.status es igual a "flagged"

az eventgrid event-subscription create \ 
	--name flagged-content-sub \
	--source-resource-id /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.EventGrid/topics/ai-events \
	--endpoint https://review-service.azurewebsites.net/api/events \
	--advanced-filter data.status StringIn flagged

Para AI events, los filtros avanzados permiten hacer target de escenarios especificos y tomar decisiones sobre:

  • Confidence-based routing: Podemos enrutar los eventos a diferentes consumers según el confidence score
  • Model-specific subscriptions: Enrutar según el modelo
  • Status-based workflows: Crear workflows con diferentes consumers o pasos según el estado

Configure input and output schema

Al crear un custom topic el param input-schema controla los schemas que el topic acepta.

IMPORTANTE

Con este valor a cloudeventsschemaV1_0 aceptamos eventos con formato CloudEvents

az eventgrid topic create \
	--name ai-events \
	--resource-group ai-platform-rg \
	--location eastus \
	--input-schema cloudeventschemav1_0

Al crear la event subscription el param event-delivery-schema controla el formato de entrega al handler. Event Grid puede intercambiar entre Event Grid schema y CloudEvents schema durante la entrega, pero no se soporta CloudEvents-to-EventGrid conversion.

/IMPORTANTE