Compartilhar via

Namespaces da Grade de Eventos do Azure – suporte para o esquema CloudEvents

  • Artigo

Os tópicos do namespace da Grade de Eventos aceitam eventos que estão em conformidade com a especificação CloudEvents 1.0 padrão aberto do CNCF (Cloud Native Computing Foundation) usando a associação de protocolo HTTP com o formato JSON. Um CloudEvent é um tipo de mensagem que contém o que está sendo comunicado, conhecido como dados de evento e metadados sobre ele. Os dados de evento em arquiteturas controladas por eventos normalmente carregam as informações anunciando uma alteração de estado do sistema. Os metadados do CloudEvents são compostos por um conjunto de atributos que fornecem informações contextuais sobre a mensagem como de onde ela se originou (o sistema de origem), seu tipo etc. Todas as mensagens válidas que cumprem as especificações do CloudEvents devem incluir os seguintes atributos de contexto necessários:

A especificação CloudEvents também define atributos de contexto de extensão e opcionais que você pode incluir ao usar a Grade de Eventos.

Ao usar a Grade de Eventos, o CloudEvents é o formato de evento preferencial devido aos casos de uso bem documentados (modos para transferir eventos, formatos de eventos etc.), extensibilidade e interoperabilidade aprimorada. O CloudEvents aprimora a interoperabilidade, fornecendo um formato comum de evento para publicar e consumir eventos. Ele permite ferramentas uniformes e formas padrão de roteamento e manipulação de eventos.

Modos de conteúdo do CloudEvents

A especificação CloudEvents define três modos de conteúdo: binário, estruturado e em lote.

Importante

Com qualquer modo de conteúdo, você pode trocar texto (JSON, texto/*, etc.) ou dados de evento codificados em binário. O modo de conteúdo binário não é usado exclusivamente para enviar dados binários.

Os modos de conteúdo não se referem à codificação que você usa, binário ou texto, mas a como os dados do evento e seus metadados são descritos e trocados. O modo de conteúdo estruturado usa uma única estrutura, por exemplo, um objeto JSON, em que os atributos de contexto e os dados de evento são reunidos no conteúdo HTTP. O modo de conteúdo binário separa atributos de contexto, que são mapeados para cabeçalhos HTTP e dados de evento, que é o payload HTTP codificado de acordo com o tipo de mídia definido em Content-Type.

Suporte do CloudEvents

Esta tabela mostra o suporte atual para a especificação CloudEvents:

Modo de conteúdo do CloudEvents Com suporte?
JSON estruturado Sim
JSON estruturado em lote Sim, para eventos de publicação
Binary Sim, para eventos de publicação

O tamanho máximo permitido para um evento é 1 MB. Eventos acima de 64 KB são cobrados em incrementos de 64 KB.

Modo de conteúdo estruturado

Uma mensagem no modo de conteúdo estruturado do CloudEvents tem os atributos de contexto e os dados do evento juntos em um payload HTTP.

Importante

Atualmente, a Grade de Eventos dá suporte ao formato JSON CloudEvents com HTTP.

Aqui está um exemplo de um CloudEvents no modo estruturado usando o formato JSON. Os metadados (todos os atributos que não são "dados") e os dados de mensagem/evento (o objeto "data") são descritos usando JSON. Nosso exemplo inclui todos os atributos de contexto necessários, juntamente com alguns atributos opcionais (subject, time e datacontenttype) e atributos de extensão (comexampleextension1, comexampleothervalue).

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "subject" : "O-28964",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "application/json",
    "data" : {
       "orderId" : "O-28964",
       "URL" : "https://com.yourcompany/orders/O-28964"
    }
}

Você pode usar o formato JSON com conteúdo estruturado para enviar dados de evento que não são um valor JSON. Para isso, execute as seguintes etapas:

  1. Inclua um atributo datacontenttype com o tipo de mídia no qual os dados são codificados.
  2. Se o tipo de mídia for codificado em um formato de texto como text/plain, text/csv ou application/xml, você deverá usar um atributo data com uma cadeia de caracteres JSON contendo o que você está se comunicando como valor.
  3. Se o tipo de mídia representar uma codificação binária, você deverá usar um atributo data_base64 cujo valor é uma cadeia de caracteres JSON contendo o valor binário codificado BASE64.

Por exemplo, este CloudEvent carrega dados de evento codificados em application/protobuf para trocar mensagens Protobuf.

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "datacontenttype" : "application/protobuf",
    "data_base64" : "VGhpcyBpcyBub3QgZW5jb2RlZCBpbiBwcm90b2J1ZmYgYnV0IGZvciBpbGx1c3RyYXRpb24gcHVycG9zZXMsIGltYWdpbmUgdGhhdCBpdCBpcyA6KQ=="
}

Para obter mais informações sobre o uso dos atributos data ou data_base64, consulte Manipulação de dados.

Para obter mais informações sobre este modo de conteúdo, consulte as especificações do modo de conteúdo estruturado por HTTP do CloudEvents.

Modo de conteúdo em lote

Atualmente, a Grade de Eventos dá suporte ao modo de conteúdo em lote JSON ao publicar CloudEvents na Grade de Eventos. Esse modo de conteúdo usa uma matriz JSON preenchida com CloudEvents no modo de conteúdo estruturado. Por exemplo, seu aplicativo pode publicar dois eventos usando uma matriz como a seguir. Da mesma forma, se você estiver usando o SDK do plano de dados da Grade de Eventos, essa payload também será o que está sendo enviado:

[
    {
        "specversion": "1.0",
        "id": "E921-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": "some data"
    },
    {
        "specversion": "1.0",
        "id": "F555-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": {
            "somekey" : "value",
            "someOtherKey" : 9
        }
    }
]

Para obter mais informações, consulte as especificações do Modo de conteúdo em lote do CloudEvents.

Envio em lote

Seu aplicativo deve agrupar vários eventos em uma matriz para obter maior eficiência e maior taxa de transferência com uma solicitação individual de publicação. Os lotes podem ter até 1 MB, e o tamanho máximo de um evento é 1 MB.

Modo de conteúdo binário

Um CloudEvent no modo de conteúdo binário tem seus atributos de contexto descritos como cabeçalhos HTTP. Os nomes dos cabeçalhos HTTP são o nome do atributo de contexto prefixado com ce-. O cabeçalho Content-Type reflete o tipo de mídia no qual os dados do evento são codificados.

Importante

Ao usar o modo de conteúdo binário, o cabeçalho HTTP ce-datacontenttype NÃO DEVE estar presente também.

Importante

Se você estiver planejando incluir seus próprios atributos (ou seja, atributos de extensão) ao usar o modo de conteúdo binário, certifique-se de que seus nomes consistam em letras minúsculas ("a" a "z") ou dígitos ("0" a "9") do caractere ASCII e que eles não excedam 20 caracteres de comprimento. Ou seja, a convenção de nomenclatura para nomear atributos de contexto CloudEvents é mais restritiva do que a de nomes de cabeçalho HTTP válidos. Nem todo nome de cabeçalho HTTP válido é um nome de atributo de extensão válido.

O payload HTTP são os dados de evento codificados de acordo com o tipo de mídia em Content-Type.

Uma solicitação HTTP usada para publicar um CloudEvent no modo binário de conteúdo pode ser semelhante a este exemplo:

POST / HTTP/1.1
HOST mynamespace.eastus-1.eventgrid.azure.net/topics/mytopic
ce-specversion: 1.0
ce-type: com.example.someevent
ce-source: /mycontext
ce-id: A234-1234-1234
ce-time: 2018-04-05T17:31:00Z
ce-comexampleextension1: value
ce-comexampleothervalue: 5
content-type: application/protobuf

Binary data according to protobuf encoding format. No context attributes are included.

Quando usar o modo de conteúdo binário ou estruturado do CloudEvents

Você poderá usar o modo de conteúdo estruturado se quiser uma abordagem simples para encaminhar CloudEvents entre saltos e protocolos. Como um CloudEvent no modo de conteúdo estruturado contém a mensagem junto com seus metadados, é fácil para os clientes consumi-la como um todo e encaminhá-la para outros sistemas.

Você poderá usar o modo de conteúdo binário se souber que aplicativos downstream exigem apenas a mensagem sem informações extras (ou seja, os atributos de contexto). Embora com o modo de conteúdo estruturado você ainda possa obter os dados do evento (mensagem) do CloudEvent, será mais fácil se um aplicativo de consumidor apenas os tiver no payload HTTP. Por exemplo, outros aplicativos podem usar outros protocolos e podem estar interessados apenas em sua mensagem principal, não em seus metadados. Na verdade, os metadados podem ser relevantes apenas para o primeiro salto imediato. Neste caso, ter os dados que você deseja trocar além de seus metadados torna o tratamento e encaminhamento mais fáceis.

Conteúdo relacionado