Grade de Eventos do Azure: CloudEvents, filtros, repetições e eventos personalizados de IA

radio_button_uncheckedshort_text1. Cenário de IA orientado a eventos e objetivos

Uma plataforma de moderação recebe imagens e textos no Armazenamento de Blobs do Azure, gera embeddings, executa classificadores e encaminha resultados de risco para revisores. Consultar continuamente cada origem e etapa desperdiça solicitações, retarda reações, aumenta o acoplamento e piora nos picos. O fluxo precisa de um sinal leve quando dados chegam, a inferência termina, um modelo muda ou uma etapa entrega trabalho à próxima.

A Grade de Eventos do Azure (Azure Event Grid) fornece essa camada de roteamento. O capítulo aborda modelagem, tópicos, modos de entrega, filtros, falhas transitórias, dead-letter, observabilidade e publicação por SDK ou API REST.

• Reconhecer eventos, origens, tópicos, assinaturas e manipuladores em um fluxo de IA.
• Escolher tópicos do sistema, personalizados ou de namespace e entrega push ou pull.
• Criar CloudEvents interoperáveis com tipos, assuntos e dados compactos.
• Configurar filtros, repetições, dead-letter, lotes e monitoramento.
• Publicar com segurança usando Microsoft Entra ID, identidade gerenciada, Python ou REST.

Resumo do tópico

A Grade de Eventos substitui a sondagem por notificações explícitas e roteáveis, permitindo que cada etapa de IA reaja de modo independente.

radio_button_uncheckedshort_text2. Entenda o modelo de roteamento

A Grade de Eventos é um serviço gerenciado de publicação e assinatura com baixa latência e operações cobradas conforme o uso. Um evento é um fato compacto sobre uma mudança, não o recurso completo. Uma origem publica no tópico, a assinatura seleciona correspondências e o manipulador executa a reação. Armazenamento de Blobs do Azure, Cofre de Chaves, Registro de Contêiner do Azure, Hubs de Eventos, aplicações personalizadas e parceiros SaaS podem ser origens.

Resumo do tópico

Separe o fato, o produtor, o tópico, cada filtro e cada reação para obter baixo acoplamento.

radio_button_uncheckedshort_text3. Escolha tópicos do sistema, personalizados ou de namespace

Use eventos do sistema para estado da plataforma, personalizados para marcos da aplicação e tópicos de namespace quando o consumidor precisar controlar o pull, usar endpoint privado ou concentrar recursos no namespace. A moderação pode começar com BlobCreated e, depois da inferência, publicar com.contoso.ai.ContentClassified.

Resumo do tópico

Associe o tópico ao publicador e ao consumo: recurso do Azure, marco da aplicação ou namespace com push e pull.

radio_button_uncheckedshort_text4. Aplique padrões e selecione manipuladores

O processamento reativo começa quando os dados chegam. A coordenação de pipeline publica somente em limites significativos, como embeddings concluídos ou índice atualizado. Eventos de ciclo de vida comunicam treinamento, validação, promoção e implantação de modelos. Assim, auditoria, notificações ou qualidade podem assinar sem alterar o produtor.

No push, a Grade de Eventos envia HTTP assim que há correspondência. O pull, disponível para tópicos de namespace, deixa o consumidor receber no próprio ritmo e confirmar, liberar, rejeitar ou renovar bloqueios. Prefira pull quando não for possível expor endpoint, quando houver conectividade privada ou quando a taxa de entrada precisar ser controlada.

Resumo do tópico

Publique transições relevantes, use push para reação imediata e pull de namespace quando o consumidor precisar controlar tempo, taxa ou rede.

radio_button_uncheckedshort_text5. Padronize com CloudEvents 1.0

A Grade de Eventos aceita o esquema original e CloudEvents 1.0. CloudEvents é recomendado para novos projetos porque padroniza o contexto, atravessa produtos e protocolos e permite atributos de extensão. O esquema Event Grid continua disponível por compatibilidade. Entrada no formato Event Grid pode sair como CloudEvents, mas entrada CloudEvents não pode virar saída Event Grid porque o esquema antigo não representa extensões.

Resumo do tópico

Adote CloudEvents 1.0 de ponta a ponta e confirme a compatibilidade antes de criar tópicos e assinaturas.

radio_button_uncheckedshort_text6. Projete CloudEvents úteis para operações de IA

CloudEvent exige specversion, type, source e id. O tipo em DNS reverso nomeia o fato, source identifica o produtor e id distingue a ocorrência. Subject, time, datacontenttype e data fornecem roteamento e contexto. Subject funciona bem como caminho hierárquico, por exemplo /pipelines/moderation/image-classifier.

{
  "specversion": "1.0",
  "type": "com.contoso.ai.InferenceCompleted",
  "source": "/services/content-moderation",
  "id": "evt-7e18",
  "subject": "/pipelines/moderation/image-classifier",
  "time": "2026-08-24T14:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "requestId": "req-78901",
    "modelName": "content-classifier",
    "modelVersion": "3.2.1",
    "processingDurationMs": 1250,
    "resultLocation": "https://results.example/output/req-78901.json",
    "status": "completed",
    "summary": { "flagged": true, "confidence": 0.97 }
  }
}

Mantenha data compacto: IDs de correlação, modelo e versão, duração, status, resumo da decisão e URI protegida do resultado. Tipos úteis incluem InferenceCompleted, EmbeddingsRefreshed, BatchProcessingStarted, AnomalyDetected, ModelRetrained e ContentClassified. Não publique toda mudança interna; publique fatos que outro componente possa usar.

Resumo do tópico

Crie eventos pequenos e autodescritivos para fatos relevantes e referencie resultados grandes.

radio_button_uncheckedshort_text7. Filtre por tipo de evento e assunto

A assinatura pode limitar included event types aos fatos compreendidos pelo destino. Prefixos e sufixos de subject roteiam caminhos, famílias de arquivos, locatários ou etapas sem abrir data. Quando combinadas, as condições de tipo e assunto precisam corresponder.

az eventgrid event-subscription create \
  --name flagged-content \
  --source-resource-id <topic-resource-id> \
  --endpoint <handler-endpoint> \
  --included-event-types com.contoso.ai.ContentClassified \
  --subject-begins-with /pipelines/moderation/ \
  --advanced-filter data.status StringIn flagged review

A nomenclatura é infraestrutura operacional. Defina convenções de tipo e subject antes de multiplicar produtores, preserve maiúsculas e minúsculas e teste casos positivos e negativos. O tipo informa o que ocorreu; o assunto indica onde ou para qual objeto ocorreu.

Resumo do tópico

Use type para semântica e prefixo ou sufixo de subject para caminhos, reduzindo trabalho desnecessário.

radio_button_uncheckedshort_text8. Encaminhe dados com filtros avançados

Filtros avançados examinam contexto ou campos de data. Entre os operadores estão StringIn, StringContains, StringBeginsWith, NumberGreaterThan, BoolEquals e IsNotNull. Uma assinatura pode usar StringIn em data.status para flagged ou review; outra pode selecionar confiança mínima ou versão do modelo.

Há até 25 filtros avançados e 25 valores no total, com 512 caracteres por string. Cláusulas distintas usam AND; valores de uma condição representam alternativas. Chaves com ponto não podem ser escapadas. Filtros roteiam, mas não autorizam: o manipulador ainda valida evento, esquema e permissão.

Resumo do tópico

Filtros avançados evitam processamento inútil, mas exigem contrato estável, respeito aos limites e validação no destino.

radio_button_uncheckedshort_text9. Confirme corretamente a entrega push

No push, a Grade de Eventos envia HTTP POST. Apenas 200, 201, 202, 203 e 204 confirmam sucesso. O endpoint tem 30 segundos para responder; o tempo excedido falha. A carga é uma matriz com um evento por padrão. Como a entrega é pelo menos uma vez, podem surgir duplicatas e o destino deve tornar efeitos idempotentes pelo id do evento ou por chave de negócio.

Use 503 para indisponibilidade temporária, não 400. Um 401 de webhook não é repetido; a repetição tardia especial de 401 e 404 vale para endpoints de recursos do Azure. Se a inferência durar mais de 30 segundos, grave o trabalho aceito, responda 202 e conclua de modo assíncrono.

Resumo do tópico

Responda rapidamente com 2xx adequado, classifique falhas transitórias e garanta idempotência.

radio_button_uncheckedshort_text10. Configure vida útil e limite de tentativas

A repetição usa espera exponencial aleatorizada. A sequência nominal é 10 segundos, 30 segundos, 1 minuto, 5 minutos, 10 minutos, 30 minutos, 1 hora, 3 horas, 6 horas e, depois, a cada 12 horas até a janela de 24 horas. A assinatura define máximo de 1 a 30 tentativas e TTL de 1 a 1.440 minutos; os padrões são 30 e 1.440. O primeiro limite atingido encerra a entrega, e a agenda não é configurável.

TTL curto pode expirar antes de um limite alto de tentativas. Escolha ambos pela validade de negócio, tempo de recuperação e capacidade do destino. Tentativas podem ser puladas se o endpoint aparentar indisponibilidade. Se ele responder em até três minutos, a remoção em melhor esforço pode concorrer com outra tentativa e ainda produzir duplicata.

az eventgrid event-subscription create \
  --name moderation-subscription \
  --source-resource-id <topic-resource-id> \
  --endpoint <handler-endpoint> \
  --max-delivery-attempts 5 \
  --event-ttl 30 \
  --deadletter-endpoint <blob-container-resource-id> \
  --max-events-per-batch 100 \
  --preferred-batch-size-in-kilobytes 512

Resumo do tópico

Ajuste TTL e tentativas juntos; o primeiro que expirar vence e a idempotência continua obrigatória.

radio_button_uncheckedshort_text11. Preserve eventos não entregues com dead-letter

Dead-letter fica desabilitado até a assinatura apontar para um contêiner existente do Armazenamento de Blobs do Azure. Ao esgotar tentativas ou TTL, a Grade de Eventos pode salvar o evento e propriedades como deadLetterReason (MaxDeliveryAttemptsExceeded ou MaxRetryDurationExceeded), deliveryAttempts, lastDeliveryOutcome (NotFound, TimedOut, Busy ou Forbidden), publishTime e lastDeliveryAttemptTime. Sem destino, o evento expirado é descartado.

Trate o contêiner como fila operacional: proteja, retenha, alerte, investigue padrões como NotFound ou TimedOut, corrija a causa e republique por processo idempotente. Uma assinatura no próprio contêiner pode disparar notificação ou reprocessamento.

Resumo do tópico

Dead-letter gera evidência recuperável, mas precisa de responsável, alerta, diagnóstico, retenção e replay controlado.

radio_button_uncheckedshort_text12. Agrupe saídas sem comprometer a confiabilidade

O lote de saída vem desligado. A assinatura aceita de 1 a 5.000 eventos por lote e tamanho preferencial de 1 a 1.024 KB. São metas em melhor esforço: a Grade de Eventos não espera completar o lote, e um evento grande pode superar o tamanho preferido.

A semântica é tudo ou nada. O endpoint processa o lote inteiro e devolve um resultado em até 30 segundos; não há sucesso parcial, e a falha repete o lote. Selecione tamanho compatível com o destino e mantenha idempotência por evento.

Resumo do tópico

Lotes reduzem HTTP, mas exigem processamento integral dentro do prazo e tolerância à reentrega completa.

radio_button_uncheckedshort_text13. Monitore fluxo e resultados

O Azure Monitor expõe sucesso de entrega, tentativas com falha, eventos correspondentes, descartados e enviados para dead-letter. Relacione essas métricas à latência, disponibilidade e logs do destino, à capacidade do modelo e à taxa de publicação. Falha conta tentativas, não somente perdas finais.

Alerte para aumento de dead-letter, falhas persistentes, descartes inesperados, desaparecimento de correspondências e queda de sucesso. Registre id, type, subject, correlação, assinatura, manipulador e resultado sem incluir segredos ou dados sensíveis.

Resumo do tópico

Observe publicação, correspondência, tentativas, sucesso, descarte e dead-letter em conjunto.

radio_button_uncheckedshort_text14. Autentique publicadores com privilégio mínimo

Publicadores podem usar chave, token SAS ou Microsoft Entra ID. Em produção no Azure, prefira identidade gerenciada e conceda Event Grid Data Sender no menor escopo do tópico. Essa função fornece Microsoft.EventGrid/events/send/action sem segredo embutido.

A chave usa aeg-sas-key e serve para laboratório. SAS reduz tempo e recurso, mas continua sendo segredo. Microsoft Entra ID usa tokens, pode aplicar políticas de Acesso Condicional e elimina rotação de chave pela aplicação. A identidade de entrada é distinta da identidade que a Grade de Eventos usa para entregar a serviços downstream.

Resumo do tópico

Em produção, combine identidade gerenciada e Event Grid Data Sender; limite e gire chaves ou SAS quando necessários.

radio_button_uncheckedshort_text15. Publique CloudEvents com o SDK Python

O pacote azure-eventgrid oferece EventGridPublisherClient e azure.core.messaging fornece CloudEvent. O cliente aceita AzureKeyCredential, AzureSasCredential ou credencial de token como DefaultAzureCredential e envia um evento ou lista homogênea. Para tópico de namespace, forneça o contexto exigido pela API atual.

import os
from azure.core.messaging import CloudEvent
from azure.eventgrid import EventGridPublisherClient
from azure.identity import DefaultAzureCredential

client = EventGridPublisherClient(
    os.environ["EVENTGRID_TOPIC_ENDPOINT"],
    DefaultAzureCredential(),
)

event = CloudEvent(
    type="com.contoso.ai.InferenceCompleted",
    source="/services/content-moderation",
    subject="/pipelines/moderation/image-classifier",
    data={
        "requestId": "req-78901",
        "modelName": "content-classifier",
        "status": "completed",
        "resultLocation": "https://results.example/output/req-78901.json",
    },
)

client.send(event)  # A list publishes a batch of one event type.

Reutilize o cliente, valide os dados, propague correlação e publique em pontos naturais: inferência concluída, promoção, anomalia ou transição. Envio bem-sucedido significa que a Grade de Eventos aceitou o evento, não que todos os destinos terminaram.

Resumo do tópico

O SDK cuida da serialização e autenticação; o aplicativo mantém contratos, marcos e a distinção entre aceitação e processamento.

radio_button_uncheckedshort_text16. Publique por REST e reutilize padrões

Tópico personalizado também recebe HTTP POST. Para CloudEvent estruturado, use application/cloudevents+json e autentique com token do Microsoft Entra, aeg-sas-key ou SAS. Resposta 200 confirma aceitação; JSON inválido, credencial errada ou esquema incompatível retorna outro status.

curl -X POST "$EVENTGRID_TOPIC_ENDPOINT" \
  -H "Content-Type: application/cloudevents+json; charset=utf-8" \
  -H "aeg-sas-key: $EVENTGRID_TOPIC_KEY" \
  --data-binary @inference-completed.json

Resumo do tópico

REST é portátil, mas deve seguir os mesmos contratos versionados e regras de segurança do SDK.

radio_button_uncheckedshort_text17. Laboratório guiado: roteie eventos de moderação

O exercício cria namespace e tópico, assinaturas para conteúdo sinalizado, aprovado e todos os eventos, além de uma aplicação Flask que publica moderação. O consumidor pull recebe e confirma, libera ou rejeita. Reserve cerca de 30 minutos com assinatura do Azure, Visual Studio Code, Python 3.12 ou posterior e CLI do Azure atual.

az group create --name ai200-eventgrid-rg --location eastus
az eventgrid namespace create \
  --resource-group ai200-eventgrid-rg \
  --name <globally-unique-namespace> \
  --location eastus
az eventgrid namespace topic create \
  --resource-group ai200-eventgrid-rg \
  --namespace-name <namespace> \
  --name moderation-events \
  --event-retention-in-days 1

python -m venv .venv
python -m pip install --upgrade azure-identity azure-eventgrid flask

1. Baixe o projeto inicial, crie tópico de namespace com CloudEvents e três assinaturas com filtros testados.
2. Publique eventos approved e flagged com type, subject, request ID, modelo, status e referência.
3. Receba por pull, inspecione evento e propriedades, confirme sucesso, libere falha transitória e rejeite entrada inválida.
4. Prove que cada assinatura recebe somente o previsto e correlacione os logs.
5. Provoque uma falha controlada, observe repetição ou dead-letter e depois exclua o grupo de recursos.

Resumo do tópico

O laboratório valida publicação, filtros, liquidação pull e observabilidade com eventos reais.

radio_button_uncheckedshort_text18. Avaliação comentada e checklist de produção

Antes da produção, confirme tipo de tópico, contrato e versão CloudEvents, taxonomia de type e subject, testes de filtro, escolha push/pull, validação do endpoint, comportamento em 30 segundos, idempotência, TTL e tentativas, responsável por dead-letter, limites de lote, métricas e alertas, runbook de replay, identidade e RBAC, rede privada, cotas, custo e teste de carga.

1. Microsoft Learn: visão geral da Grade de Eventos do Azure
2. Microsoft Learn: conceitos de entrega push
3. Microsoft Learn: conceitos de namespace e pull
4. Microsoft Learn: CloudEvents 1.0
5. Microsoft Learn: filtros de eventos
6. Microsoft Learn: entrega, repetição e lotes
7. Microsoft Learn: dead-letter e política de repetição
8. Microsoft Learn: autenticar publicadores com Microsoft Entra ID
9. Microsoft Learn: EventGridPublisherClient para Python

Resumo do tópico

Uma solução de produção combina contrato interoperável, roteamento preciso, entrega segura, recuperação observável e publicação por identidade.