Conceitos de namespace da Grade de Eventos do Azure
Este artigo apresenta os principais conceitos e funcionalidades associados aos tópicos de namespace.
evento
Um evento é a menor quantidade de informação que descreve completamente algo que aconteceu em um sistema. Muitas vezes nos referimos a um evento como um evento discreto porque ele representa um fato distinto e autônomo sobre um sistema que fornece uma visão que pode ser acionável. Cada evento tem informações comuns, como source o evento, time o evento ocorrido e um identificador único. 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 ficheiro que está a ser criado no Armazenamento do Azure inclui detalhes sobre o ficheiro, tal como o valor lastTimeModified. Um evento de Hubs de Eventos tem a URL do arquivo capturado. Um evento sobre um novo pedido em seu microsserviço Pedidos pode ter um orderId atributo e um atributo URL para a representação de estado do pedido. Mais alguns exemplos de tipos de eventos incluem: com.yourcompany.Orders.OrderCreated, org.yourorg.GeneralLedger.AccountChanged, io.solutionname.Auth.MaximumNumberOfUserLoginAttemptsReached.
Aqui está 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 como "eventos" a mensagens que carregam um ponto de dados, como uma leitura de um único dispositivo ou um clique em uma página de aplicativo da web. Esse tipo de evento geralmente é analisado ao longo de uma janela de tempo para obter insights e tomar uma ação. Na documentação do Event Grid, nos referimos a esse tipo de evento como um ponto de dados, streaming de dados ou simplesmente como telemetria. Entre outros tipos de mensagens, esse tipo de evento é usado com o recurso de agente de Transporte de Telemetria de Enfileiramento de Mensagens (MQTT) da Grade de Eventos.
CloudEventos
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:
- Inclua um
datacontenttypeatributo com o tipo de mídia no qual os dados são codificados. - Se o tipo de mídia estiver codificado em um formato de texto como
text/plain,text/csvouapplication/xml, você deverá usar umdataatributo com uma cadeia de caracteres JSON contendo o que você está comunicando como valor. - Se o tipo de mídia representa uma codificação binária, você deve usar um
data_base64atributo 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.
Editores
Um editor é o aplicativo que envia eventos para a Grade de Eventos. Pode ser a mesma aplicação onde os eventos se originaram, a fonte do evento. Você pode publicar eventos de seu próprio aplicativo ao usar tópicos de namespace.
Origens de eventos
Uma fonte de evento é onde o evento acontece. Cada fonte de evento oferece suporte a um ou mais tipos de evento. Por exemplo, seu aplicativo é a fonte de eventos personalizados que seu sistema define. Ao usar tópicos de namespace, as fontes de eventos suportadas são seus próprios aplicativos.
Espaços de nomes
Um namespace de Grade de Eventos é um contêiner de gerenciamento para os seguintes recursos:
| Recurso | Protocolo suportado |
|---|---|
| Tópicos de namespace | HTTP |
| Espaços Temáticos | MQTT |
| Clientes | MQTT |
| Grupos de Clientes | MQTT |
| Certificados de CA | MQTT |
| Ligações de permissão | MQTT |
Com um namespace da Grade de Eventos do Azure, você pode agrupar recursos relacionados e gerenciá-los como uma única unidade em sua assinatura do Azure. Dá-lhe um nome de domínio totalmente qualificado (FQDN) exclusivo.
Um namespace expõe dois pontos de extremidade:
- Um ponto de extremidade HTTP para dar suporte a requisitos gerais de mensagens usando tópicos de namespace.
- Um ponto de extremidade MQTT para mensagens IoT ou soluções que usam MQTT.
Um namespace também fornece pontos de extremidade de rede integrados ao DNS. Ele também fornece uma gama de controle de acesso e recursos de 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 recursos contidos no namespace.
Aqui estão mais alguns pontos sobre namespaces:
- O namespace é um recurso controlado com
tagselocationpropriedades e, uma vez criado, pode ser encontrado emresources.azure.com. - O nome do namespace pode ter de 3 a 50 caracteres. Pode incluir alfanuméricos e hífen(-), e sem espaços.
- O nome precisa ser exclusivo por região.
Unidades de débito
As unidades de taxa de transferência (TUs) definem a capacidade da taxa de eventos 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 dentro de um namespace de Grade de Eventos. Seu aplicativo publica eventos em um ponto de extremidade de namespace HTTP especificando um tópico de namespace onde os eventos publicados estão logicamente contidos. Ao projetar seu aplicativo, você tem que decidir quantos tópicos criar. 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 eventos de ambos os aplicativos. Para segregar preocupações, crie dois tópicos de namespace: um para cada aplicativo. Permita que os consumidores de eventos se inscrevam no tópico de acordo com suas necessidades. Para soluções pequenas, você pode preferir enviar todos os eventos para um único tópico.
Os tópicos de namespace suportam entrega pull e push delivery. Veja quando usar a entrega pull ou push para ajudá-lo a decidir se a entrega pull é a abordagem certa de acordo com suas necessidades.
Subscrições de eventos
Uma assinatura de evento é um recurso de configuração associado a um único tópico. Entre outras coisas, você usa uma assinatura de evento para definir os critérios de seleção de eventos para definir a coleção de eventos disponível para um assinante fora 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 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 para a propriedade de dados . Para obter mais informações sobre as propriedades do recurso, procure operações de plano de controle na API REST da grade de eventos.
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 CLI.
Nota
As assinaturas de eventos em um tópico de namespace apresentam um modelo de recurso simplificado quando comparado ao usado para tópicos personalizados, de domínio, de parceiro e de sistema (Grade de Eventos Básica). Para obter mais informações, consulte Criar, exibir e gerenciar assinaturas de eventos.
Entrega puxada
Com a entrega pull, seu aplicativo se conecta à Grade de Eventos para ler mensagens usando semântica semelhante a uma fila. À medida que 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 podem usar pontos de extremidade privados ao se conectar à Grade de Eventos para ler eventos usando espaço IP privado.
A entrega pull suporta as seguintes operações para ler mensagens e controlar o estado da mensagem: receber, reconhecer, liberar, rejeitar e renovar bloqueio. Para obter mais informações, consulte Visão geral da entrega pull.
Forma de dados ao receber eventos usando entrega pull
Ao entregar eventos usando a entrega 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 objeto json a seguir é uma resposta de exemplo de uma operação de recebimento 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 por push
Com a entrega por push, a Grade de Eventos envia eventos para um destino configurado em uma assinatura de evento push (modo de entrega em). Ele fornece uma lógica de repetição robusta caso o destino não seja capaz de receber eventos.
Importante
A entrega por push dos namespaces da Grade de Eventos atualmente dá suporte aos 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 suportados pelo Event Grid Basic.
Entrega de eventos dos Hubs de Eventos
A Grade de Eventos usa o SDK de Hubs de Eventos para enviar eventos para Hubs de Eventos usando AMQP. Os eventos são enviados como uma matriz de bytes com cada elemento na matriz contendo um CloudEvent.
Entrega push and pull
A Grade de Eventos oferece suporte à entrega de eventos push e pull usando HTTP. Com a entrega por 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 envia eventos. Com a entrega pull, os aplicativos do assinante se conectam à Grade de Eventos para consumir eventos. A entrega pull é suportada para tópicos em um namespace Event Grid.
Importante
Os Hubs de Eventos são suportados como um destino para assinaturas de tópicos de namespace. Nas próximas versões, os Namespaces de Grade de Eventos suportarão todos os destinos atualmente disponíveis no Event Grid Basic, juntamente com destinos adicionais.
Quando usar a entrega por push vs. entrega por pull
Seguem-se orientações gerais para o ajudar a decidir quando utilizar a entrega por pull ou push.
Entrega puxada
- Você precisa de controle total sobre quando receber eventos. Por exemplo, seu aplicativo pode não estar ativo o tempo todo, não ser estável o suficiente ou você processar dados em determinados momentos.
- Você precisa de controle total sobre o consumo de eventos. Por exemplo, um serviço ou camada downstream em seu aplicativo de consumidor tem um problema que impede que você processe eventos. Nesse caso, a API de entrega pull permite que o aplicativo do consumidor libere um evento já lido de volta ao corretor para que possa ser entregue posteriormente.
- Você deseja usar links privados ao receber eventos, o que só é possível com a entrega pull, não com a entrega push.
- Você não tem a capacidade de expor um ponto de extremidade e usar a entrega por push, mas pode se conectar à Grade de Eventos para consumir eventos.
Entrega por push
- Você deseja evitar sondagens constantes para determinar se ocorreu uma alteração no estado do sistema. Em vez disso, use a Grade de Eventos para enviar eventos para você no momento em que as alterações de estado ocorrerem.
- Você tem um aplicativo que não pode fazer chamadas de saída. Por exemplo, sua organização pode estar preocupada com a exfiltração de dados. No entanto, seu aplicativo pode receber eventos por meio de um ponto de extremidade público.
Próximos passos
- Para obter uma introdução ao Event Grid, veja Sobre o Azure Event Grid.
- Para começar a usar tópicos de namespace, consulte publicar eventos usando tópicos de namespace.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários