Partilhar via

Esquema de eventos da Grade de Eventos do Azure

  • Artigo

Este artigo descreve o esquema de grade de eventos, que é um formato de evento proprietário, não extensível, mas totalmente funcional. A Grelha de Eventos continua a suportar este formato de evento e continuará a suportá-lo. No entanto, CloudEvents é o formato de evento recomendado para usar. Se estiver a utilizar aplicações que utilizam o formato Grelha de Eventos, poderá achar úteis as informações na secção [CloudEvents] que descreve as transformações entre a Grelha de Eventos e o formato CloudEvents suportado pela Grelha de Eventos.

Este artigo descreve em detalhes as propriedades e o esquema para o formato de grade de eventos. Os eventos consistem em um conjunto de quatro propriedades de cadeia de caracteres necessárias. As propriedades são comuns a todos os eventos de qualquer editor. O objeto de dados tem propriedades específicas para cada editor. Para tópicos do sistema, essas propriedades são específicas do provedor de recursos, como o Armazenamento do Azure ou os Hubs de Eventos do Azure.

As fontes de eventos enviam eventos para a Grade de Eventos do Azure em uma matriz, que pode ter vários objetos de evento. Ao postar eventos em um tópico da Grade de Eventos, a matriz pode ter um tamanho total de até 1 MB. Cada evento na matriz é limitado a 1 MB. Se um evento ou a matriz for maior do que os limites de tamanho, você receberá a resposta 413 Payload Too Large. No entanto, as operações são cobradas em incrementos de 64 KB. Assim, eventos com mais de 64 KB incorrem em encargos de operações como se fossem eventos múltiplos. Por exemplo, um evento de 130 KB incorreria em operações como se fossem três eventos separados.

A Grade de Eventos envia os eventos para os assinantes em uma matriz que tem um único evento. Esse comportamento pode mudar no futuro.

Você pode encontrar o esquema JSON para o evento Grade de Eventos e a carga útil de dados de cada editor do Azure no repositório de Esquema de Eventos.

Nota

O suporte para o esquema de eventos da Grade de Eventos não será desativado, mas não faremos grandes melhorias nele no futuro. Recomendamos que você use o esquema CloudEvents, que fornece uma definição padronizada e independente de protocolo da estrutura e descrição de metadados de eventos. Para obter mais informações, consulte Esquema do CloudEvents v1.0 com a Grade de Eventos do Azure.

Esquema de eventos

O exemplo a seguir mostra as propriedades usadas por todos os editores de eventos:

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

Por exemplo, o esquema publicado para um evento de armazenamento de Blob do Azure é:

[
  {
    "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"
  }
]

Propriedades do evento

Todos os eventos têm os mesmos dados de nível superior:

Propriedade Type Obrigatório Description
topic string Não, mas se incluído, deve corresponder exatamente ao tópico Grade de Eventos ID do Azure Resource Manager. Se não estiver incluído, a Grade de Eventos será marcada no evento. Caminho completo do recurso para a origem do evento. Este campo não pode ser gravado. O Event Grid fornece este valor.
subject string Sim Caminho definido pelo publicador para o assunto do evento.
eventType string Sim Um dos tipos de eventos registados para esta origem de evento.
eventTime string Sim A hora em que o evento é gerado com base na hora UTC do provedor.
id string Sim Identificador exclusivo do evento.
data objeto Sim Dados de evento específicos do provedor de recursos.
dataVersion string Não, mas será carimbado com um valor vazio. A versão do esquema do objeto de dados. O publicador define a versão do esquema.
metadataVersion string Não obrigatório, mas se incluído, deve corresponder exatamente ao esquema metadataVersion de grade de eventos (atualmente, apenas 1). Se não estiver incluído, a Grade de Eventos será marcada no evento. A versão do esquema dos metadados do evento. O Event Grid define o esquema das propriedades de nível superior. O Event Grid fornece este valor.

Para saber mais sobre as propriedades no objeto de dados, consulte os artigos nesta seção: Tópicos do sistema.

Para tópicos personalizados, o editor de eventos determina o objeto de dados. Os dados de nível superior devem ter os mesmos campos que os eventos padrão definidos por recursos.

Ao publicar eventos em tópicos personalizados, crie assuntos para os seus eventos que facilitem aos subscritores saber se estão interessados no evento. Os subscritores utilizam o assunto para filtrar e encaminhar eventos. Considere fornecer o caminho para onde o evento aconteceu, para que os assinantes possam filtrar por segmentos desse caminho. O caminho permite que os assinantes filtrem eventos de forma restrita ou ampla. Por exemplo, se você fornecer um caminho de três segmentos, como /A/B/C no assunto, os assinantes poderão filtrar pelo primeiro segmento /A para obter um amplo conjunto de eventos. Esses assinantes recebem eventos com assuntos como /A/B/C ou /A/D/E. Outros subscritores podem filtrar para /A/B obter um conjunto mais restrito de eventos.

Às vezes, o assunto precisa de mais detalhes sobre o que aconteceu. Por exemplo, o editor de Contas de Armazenamento fornece o assunto /blobServices/default/containers/<container-name>/blobs/<file> quando um arquivo é adicionado a um contêiner. Um assinante pode filtrar pelo caminho /blobServices/default/containers/<container-name>/ para obter todos os eventos para esse contêiner, mas não outros contêineres na conta de armazenamento. Um assinante também pode filtrar ou rotear pelo sufixo .txt para trabalhar apenas com arquivos de texto.

CloudEventos

CloudEvents é o formato de evento recomendado para usar. A Grade de Eventos do Azure continua investindo em recursos relacionados a, pelo menos , o formato JSON do CloudEvents. Dado o fato de que algumas fontes de eventos, como os serviços do Azure, usam o formato de Grade de Eventos, a tabela a seguir é fornecida para ajudá-lo a entender a transformação suportada ao usar os formatos CloudEvents e Grade de Eventos como um esquema de entrada em tópicos e como um esquema de saída em assinaturas de eventos. Um esquema de saída de Grade de Eventos não pode ser usado ao usar o CloudEvents como um esquema de entrada porque o CloudEvents oferece suporte a atributos de extensão que não são suportados pelo esquema de Grade de Eventos.

Esquema de entrada Esquema de saída
Formato CloudEvents Formato CloudEvents
Formato da grelha de eventos Formato CloudEvents
Formato da grelha de eventos Formato da grelha de eventos

Próximos passos

  • Para obter uma introdução à Grade de Eventos do Azure, consulte O que é a Grade de Eventos?
  • Para obter mais informações sobre como criar uma assinatura da Grade de Eventos do Azure, consulte Esquema de assinatura da Grade de Eventos.