Compartilhar via

Esquema de eventos da Grade de Eventos do Azure

  • Artigo

Este artigo descreve o esquema da Grade de Eventos, que é um formato de evento proprietário e não extensível, mas totalmente funcional. A Grade de Eventos ainda dá suporte a esse formato de evento e continuará a dar suporte a ele. No entanto, CloudEvents é o formato de evento recomendado a ser usado. Se você estiver usando aplicativos que usam o formato da Grade de Eventos, poderá achar úteis as informações na seção [CloudEvents] que descreve as transformações entre a Grade de Eventos e o formato CloudEvents compatíveis com a Grade de Eventos.

Este artigo descreve detalhadamente as propriedades e o esquema para o formato da Grade de Eventos. Os eventos são compostos por um conjunto de quatro propriedades de cadeia de caracteres necessárias. As propriedades são comuns a todos os eventos de qualquer fornecedor. O objeto de dados tem propriedades que são específicas de cada fornecedor. Para tópicos do sistema, essas propriedades são específicas ao provedor de recursos, como Armazenamento do Azure ou Hub de Eventos do Azure.

As fontes de eventos enviam eventos para o Grade de Eventos do Azure em uma matriz, a qual pode ter vários objetos de eventos. 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 O conteúdo 413 é muito grande. No entanto, as operações são cobradas em incrementos de 64 KB. Assim, os eventos com mais de 64 Kb incorrerão em encargos de operações como se fossem vários eventos. Por exemplo, um evento com 130 KB incorreria em operações como se fosse três eventos separados.

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

Você pode encontrar o esquema JSON para o evento de Grade de Eventos e a carga de dados de cada publicador Azure no armazenamento do Esquema de Evento.

Observação

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 da descrição de metadados dos eventos. Para obter mais informações, consulte Esquema CloudEvents v1.0 com a Grade de Eventos do Azure.

Esquema do evento

O exemplo a seguir mostra as propriedades que são 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 terão os mesmos dados de nível superior a seguir:

Propriedade Type Obrigatória Descrição
topic string Não, mas quando incluído, deve corresponder exatamente à ID do Azure Resource Manager no tópico da Grade de Eventos. Se não estiver incluído, a Grade de Eventos o carimbará no evento. Caminho de recurso completo para a origem do evento. Este campo não é gravável. A Grade de Eventos fornece esse valor.
subject string Sim Caminho definido pelo publicador para o assunto do evento.
eventType string Sim Um dos tipos de evento registrados para a origem do 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 do evento específicos ao 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 quando incluído, deve corresponder exatamente ao esquema da Grade de Eventos metadataVersion (atualmente, somente 1). Se não estiver incluído, a Grade de Eventos o carimbará no evento. A versão do esquema dos metadados do evento. Grade de Eventos define o esquema de propriedades de nível superior. A Grade de Eventos fornece esse 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 publicador do evento determina o objeto de dados. Os dados de nível superior devem ter os mesmos campos do que os eventos definidos pelo recurso padrão.

Ao publicar eventos em tópicos personalizados, crie assuntos para os eventos que tornem mais fácil aos assinantes reconhecer se estão interessados no evento. Os assinantes usam o assunto para filtrar e rotear eventos. Forneça o caminho do acontecimento do evento para que os assinante possam filtrar por segmentos desse caminho. O caminho permite que os assinantes filtrem eventos de maneira 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 conjunto amplo de eventos. Esses assinantes recebem eventos com assuntos como /A/B/C ou /A/D/E. Outros assinantes podem filtrar por /A/B para obter um conjunto de eventos mais restrito.

Às vezes, o assunto precisa apresentar mais detalhes sobre o acontecimento. Por exemplo, o publicador da Conta 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 para 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.

CloudEvents

CloudEvents é o formato de evento recomendado a ser usado. A Grade de Eventos do Azure continua investindo em recursos relacionados ao formato JSON do CloudEvents. Considerando que algumas fontes de eventos, como os serviços do Azure, usam o formato da Grade de Eventos, a tabela a seguir é fornecida para ajudá-lo a entender a transformação com suporte 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 da Grade de Eventos não pode ser usado ao usar o CloudEvents como um esquema de entrada porque o CloudEvents dá suporte a atributos de extensão que não têm suporte no esquema da Grade de Eventos.

Esquema de entrada Esquema de saída
Formato de CloudEvents Formato de CloudEvents
Formato da Grade de Eventos Formato de CloudEvents
Formato da Grade de Eventos Formato da Grade de Eventos

Próximas etapas