Partilhar via

Azure Event Grid Namespaces - suporte para o esquema CloudEvents

  • Artigo

Os tópicos do namespace Event Grid aceitam eventos que estão em conformidade com a especificação padrão aberta CloudEvents 1.0 da Cloud Native Computing Foundation (CNCF) usando a associação de protocolo HTTP com 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 onde ela se originou (o sistema de origem), seu tipo, etc. Todas as mensagens válidas que aderem às especificações do CloudEvents devem incluir os seguintes atributos de contexto necessários:

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

Ao usar a grade de eventos, o CloudEvents é o formato de evento preferido por causa de seus casos de uso bem documentados (modos de transferência de eventos, formatos de eventos, etc.), extensibilidade e interoperabilidade aprimorada. O CloudEvents melhora a interoperabilidade fornecendo um formato de evento comum para publicação e consumo de 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 eventos 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 são sobre a codificação que você usa, binário ou texto, mas sobre como os dados de evento e seus metadados são descritos e trocados. O modo de conteúdo estruturado usa uma única estrutura, por exemplo, um objeto JSON, onde os atributos de contexto e os dados de evento estão juntos na carga HTTP. O modo de conteúdo binário separa atributos de contexto, que são mapeados para cabeçalhos HTTP, e dados de eventos, que são a carga HTTP codificada de acordo com o tipo de mídia definido em Content-Type.

Suporte a CloudEvents

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

Modo de conteúdo do CloudEvents Suportado?
JSON estruturado Sim
JSON estruturado em lote Sim, para publicação de eventos
Binário Sim, para publicação de eventos

O tamanho máximo permitido para um evento é de 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 uma carga HTTP.

Importante

Atualmente, o Event Grid suporta o formato JSON CloudEvents com HTTP.

Aqui está um exemplo de um CloudEvents no modo estruturado usando o formato JSON. Ambos 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, timee 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 eventos que não sejam um valor JSON. Para isso, siga as seguintes etapas:

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

Por exemplo, este CloudEvent carrega dados de eventos codificados para application/protobuf trocar mensagens do 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 data atributos or data_base64 , consulte Tratamento de dados .

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

Modo de conteúdo em lote

Atualmente, a Grade de Eventos suporta o modo de conteúdo em lote JSON ao publicar CloudEvents na Grade de Eventos. Este 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 seguinte. Da mesma forma, se você estiver usando o SDK do plano de dados da Grade de Eventos, essa carga também é 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 Especificações do modo de conteúdo em lote do CloudEvents.

Criação de batches

Seu aplicativo deve agrupar vários eventos em um array para obter maior eficiência e maior taxa de transferência com uma única solicitação de publicação. Os lotes podem ter até 1 MB e o tamanho máximo de um evento é de 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 Content-Type cabeçalho 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 ce-datacontenttype cabeçalho HTTP NÃO DEVE também estar presente.

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 do 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.

A carga HTTP é 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 se parecer com 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ê pode 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 juntamente com seus metadados, é fácil para os clientes consumi-la como um todo e encaminhá-la para outros sistemas.

Você pode usar o modo de conteúdo binário se souber que os aplicativos downstream exigem apenas a mensagem sem nenhuma informação extra (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, é mais fácil se um aplicativo consumidor apenas os tiver na carga 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. Nesse caso, ter os dados que você deseja trocar além de seus metadados facilita o manuseio e o encaminhamento.

Conteúdos relacionados