Conceitos de namespace da Grade de Eventos do Azure

  • Artigo

Este artigo apresenta os principais conceitos e funcionalidades associados aos tópicos do namespace.

Eventos

Um evento é a menor quantidade de informações que descreve por completo algo que aconteceu em um sistema. Muitas vezes, nós nos referimos a um evento, como um evento discreto, porque ele representa um fato distinto e independente sobre um sistema que fornece um insight que pode ser acionável. Todos os eventos apresentam informações comuns como a source do evento, a time em que o evento ocorreu e um identificador exclusivo. Cada evento também tem um type, que geralmente é um identificador exclusivo que descreve o tipo de anúncio para o qual o evento é usado.

Por exemplo, um evento sobre um novo arquivo que está sendo criado no Armazenamento do Azure traz detalhes sobre o arquivo, como o valor lastTimeModified. Um evento de Hubs de Eventos tem a URL do arquivo capturado. Um evento sobre uma nova ordem no seu microsserviço Pedidos pode ter um atributo orderId e um atributo de URL à representação de estado da ordem. Mais alguns exemplos de tipos de evento incluem: com.yourcompany.Orders.OrderCreated, org.yourorg.GeneralLedger.AccountChanged, io.solutionname.Auth.MaximumNumberOfUserLoginAttemptsReached.

Veja um exemplo de evento:

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

Outro tipo de evento

A comunidade de usuários também se refere a “eventos” como mensagens que carregam um ponto de dados, como uma leitura de dispositivo individual ou um clique em uma página de aplicativo Web. Esse tipo de evento costuma ser analisado em uma janela de tempo para obtenção de insights e execução de uma ação. Na documentação da Grade de Eventos, nós nos referimos a esse tipo de evento como ponto de dados, dados de streaming ou apenas telemetria. Entre outros tipos de mensagens, este tipo de eventos é usado com o recurso de agente de Message Queue Telemetry Transport (MQTT) da Grade de Eventos.

CloudEvents

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.

Publicadores

Um editor é o aplicativo que envia eventos para a Grade de Eventos. Pode ser o mesmo aplicativo em que os eventos se originaram, a origem do evento. Você poderá publicar eventos por meio do seu aplicativo ao usar tópicos de namespace.

Origens de eventos

A origem de um evento é onde o evento acontece. Cada origem do evento dá suporte a um ou mais tipos de evento. Por exemplo, seu aplicativo é a origem do evento para eventos personalizados definidos pelo sistema. Ao usar tópicos de namespace, as origens de eventos com suporte serão seus aplicativos.

Namespaces

Um namespace da Grade de Eventos é um contêiner de gerenciamento para os seguintes recursos:

Recurso Protocolo com suporte
Tópicos de namespace HTTP
Espaços de tópicos MQTT
Clientes MQTT
Grupos de Clientes MQTT
Certificados de Autoridade de Certificação MQTT
Associações de permissão MQTT

Com um namespace da Grade de Eventos do Azure, você pode agrupar recursos relacionados e gerenciá-los como uma só unidade na sua assinatura do Azure. Ele fornece um FQDN (nome de domínio totalmente qualificado).

Um namespace expõe dois pontos de extremidade:

  • Um ponto de extremidade HTTP para dar suporte aos requisitos gerais de mensagens usando tópicos de namespace.
  • Um ponto de extremidade MQTT para mensagens IoT ou soluções que usam o MQTT.

Um namespace também fornece pontos de extremidade de rede integrados ao DNS. Também fornece uma variedade de recursos de controle de acesso e gerenciamento de integração de rede, como filtragem de entrada de IP público e links privados. Também é o contêiner de identidades gerenciadas usado para os recursos contidos no namespace.

Veja a seguir mais algumas observações sobre namespaces:

  • O namespace é um recurso acompanhado com as propriedades tags e location e, uma vez criado, ele pode ser encontrado em resources.azure.com.
  • O nome do namespace pode ter entre 3 e 50 caracteres. Ele pode incluir caracteres alfanuméricos e hífen (-) e não pode conter espaços.
  • O nome precisa ser exclusivo por região.
  • Regiões atuais com suporte: EUA Central, Leste da Ásia, Leste dos EUA, Leste dos EUA 2, Norte da Europa, Centro-Sul dos EUA, Sudeste da Ásia, Norte dos EAU, Oeste da Europa, Oeste dos EUA 2, Oeste dos EUA 3.

Unidades de transferência

As TUs (unidades de produtividade) definem a capacidade de taxa de evento de entrada e saída em namespaces. Para obter mais informações, consulte Cotas e limites da Grade de Eventos do Azure.

Tópicos

Um tópico contém eventos que foram publicados na Grade de Eventos. Normalmente, você usa um recurso de tópico para uma coleção de eventos relacionados. Muitas vezes nos referimos a tópicos dentro de um namespace como tópicos de namespace.

Tópicos de namespace

Os tópicos de namespace são tópicos criados em um namespace da Grade de Eventos. Seu aplicativo publica eventos em um ponto de extremidade de namespace HTTP especificando um tópico de namespace em que os eventos publicados estão logicamente contidos. Quando você projeta seu aplicativo, tem precisa decidir quantos tópicos devem ser criados. Para soluções relativamente grandes, crie um tópico de namespace para cada categoria de eventos relacionados. Por exemplo, considere um aplicativo que gerencia contas de usuário e outro aplicativo sobre pedidos de clientes. É improvável que todos os assinantes de eventos queiram receber eventos dos dois aplicativos. Para separar as preocupações, crie dois tópicos de namespace: um para cada aplicativo. Permita que os consumidores do evento assinem o tópico de acordo com os respectivos requisitos. Para soluções pequenas, você pode preferir enviar todos os eventos para um único tópico.

Os tópicos de namespace dão suporte à entrega de pull e entrega de push. Confira quando usar a entrega push ou pull para ajudar a decidir se a entrega pull é a abordagem certa, considerando seus requisitos.

Assinaturas de evento

Uma assinatura de evento é um recurso de configuração associado a um só tópico. Entre outras coisas, você usa uma assinatura de evento para definir critérios de seleção de eventos a fim de definir a coleção de eventos disponível para um assinante do conjunto total de eventos disponíveis em um tópico. Você pode filtrar eventos de acordo com os requisitos do assinante. Por exemplo, você pode filtrar eventos por seu tipo de evento. Você também pode definir critérios de filtro em propriedades de dados de evento se estiver usando um objeto JSON como o valor da propriedade de dados. Para obter mais informações sobre as propriedades do recurso, procure as operações do painel de controle na API REST da Grade de Eventos.

Diagrama que mostra um tópico e as assinaturas de eventos associadas.

Para obter um exemplo de criação de assinaturas para tópicos de namespace, consulte Publicar e consumir mensagens usando tópicos de namespace usando a CLI.

Observação

As assinaturas de evento em um tópico de namespace apresentam um modelo de recurso simplificado quando comparado ao usado para tópicos personalizados, de domínio, de parceiros e do sistema (Grade de Eventos Básica). Para obter mais informações, confira Criar, exibir e gerenciar assinaturas de eventos.

Entrega pull

Com a entrega de pull, seu aplicativo se conecta à Grade de Eventos para ler mensagens usando semântica semelhante à fila. Conforme os aplicativos se conectam à Grade de Eventos para consumir eventos, eles controlam a taxa de consumo de eventos e seu tempo. Os aplicativos de consumidor também poderão usar pontos de extremidade privados ao se conectarem à Grade de Eventos para ler eventos usando espaço IP privado.

A entrega de pull dá suporte às seguintes operações para ler mensagens e controlar o estado da mensagem: receber, confirmar, liberar, rejeitar e renovar bloqueio. Para obter mais informações, consulte Visão geral de entrega de pull.

Forma de dados no recebimento de eventos usando a entrega de pull

Ao fornecer eventos usando a entrega de pull, a Grade de Eventos inclui uma matriz de objetos que, por sua vez, inclui os objetos event e brokerProperties. O valor da propriedade event é o CloudEvent entregue no modo de conteúdo estruturado. O objeto brokerProperties contém o token de bloqueio associado ao CloudEvent entregue. O seguinte objeto JSON é uma resposta de exemplo de uma operação receive que retorna dois eventos:

{
    "value": [
        {
            "brokerProperties": {
                "lockToken": "CiYKJDUwNjE4QTFFLUNDODQtNDZBQy1BN0Y4LUE5QkE3NjEwNzQxMxISChDXYS23Z+5Hq754VqQjxywE",
                "deliveryCount": 2
            },
            "event": {
                "specversion": "1.0",
                "id": "A234-1234-1235",
                "source": "/mycontext",
                "time": "2018-04-05T17:31:00Z",
                "type": "com.example.someeventtype",
                "data": "some data"
            }
        },
        {
            "brokerProperties": {
                "lockToken": "CiYKJDUwNjE4QTFFLUNDODQtNDZBQy1BN0Y4LUE5QkE3NjEwNzQxMxISChDLeaL+nRJLNq3/5NXd/T0b",
                "deliveryCount": 1
            },
            "event": {
                "specversion": "1.0",
                "id": "B688-1234-1235",
                "source": "/mycontext",
                "type": "com.example.someeventtype",
                "time": "2018-04-05T17:31:00Z",
                "data": {
                    "somekey" : "value",
                    "someOtherKey" : 9
                }
            }
        }
    ]
}

Entrega push

Com a entrega de push, a Grade de Eventos envia eventos para um destino configurado em uma assinatura de evento push (modo de entrega). Ele fornece uma lógica de repetição robusta caso o destino não seja capaz de receber eventos.

Importante

A entrega de push dos namespaces da Grade de Eventos atualmente dá suporte a Hubs de Eventos do Azure como destino. No futuro, os namespaces da Grade de Eventos darão suporte a mais destinos, incluindo todos os destinos compatíveis com o Event Grid Basic.

Entrega de eventos dos Hubs de Eventos

A Grade de Eventos usa o SDK dos Hubs de Eventos para enviar eventos aos Hubs de Eventos usando AMQP. Os eventos são enviados como uma matriz de bytes com cada elemento na matriz que contém um CloudEvent.

Entrega push e pull

Usando o HTTP, a Grade de Eventos dá suporte às entregas push e pull de eventos. Com a entrega de push, você define um destino em uma assinatura de evento, um webhook ou um serviço do Azure para o qual a Grade de Eventos enviará os eventos. Com a entrega pull, os aplicativos assinantes se conectam à Grade de Eventos para consumir os eventos. A entrega de pull tem suporte para tópicos em um namespace da Grade de Eventos.

Importante

Os Hubs de Eventos têm suporte como destino para assinaturas para tópicos de namespace. Nas próximas versões, os Namespaces da Grade de Eventos darão suporte a todos os destinos atualmente disponíveis no Event Grid Básico, juntamente com destinos adicionais.

Diagrama de alto nível que mostra uma entrega push e uma entrega pull com os tipos de recursos envolvidos.

Quando usar a entrega push ou a entrega pull

As diretrizes gerais a seguir vão para ajudar você a decidir quando usar a entrega push ou pull.

Entrega pull

  • Você precisa obter controle completo sobre quando os eventos serão recebidos. Por exemplo, seu aplicativo talvez não fique online o tempo todo, não seja estável o suficiente ou você processa os dados em determinados horários.
  • Você precisa obter controle completo sobre o consumo de eventos. Por exemplo, um serviço downstream ou uma camada no seu aplicativo consumidor tem um problema que impede que você processe os eventos. Nesse caso, a API de entrega pull permite que o aplicativo consumidor libere um evento já lido novamente para o agente, de modo que ele possa ser entregue posteriormente.
  • Você deseja usar links privados ao receber eventos, o que é possível apenas com a entrega de pull, não com a entrega de push.
  • Você não tem a capacidade de expor um ponto de extremidade e usar a entrega push, mas pode se conectar à Grade de Eventos para consumir eventos.

Entrega push

  • Você deseja evitar a sondagem constante para determinar se ocorreu uma alteração de estado do sistema. Você prefere usar a Grade de Eventos para enviar eventos para você no momento em que as alterações de estado ocorrem.
  • Você tem um aplicativo que não pode fazer chamadas de saída. Por exemplo, sua organização talvez esteja preocupada com a exfiltração dos dados. No entanto, seu aplicativo pode receber eventos por meio de um ponto de extremidade público.

Próximas etapas