Guia rápido do Events Hub

Este é um guia rápido do Sensedia Events Hub. Ele dá uma visão geral de como configurar as rotas de publicação e subscrição de eventos e como aplicar as políticas de segurança e tentativas automáticas de distribuição dos eventos aos subscritores. Os links contidos aqui levam a seções mais detalhadas da nossa documentação.

Funcionamento geral

O Events Hub permite gerenciar uma arquitetura de distribuição de eventos a partir de uma interface low-code, em que publicadores e subscritores de eventos são cadastrados e gerenciados de forma completamente independente.

eh diagram pt

Para que o Events Hub saiba quais subscritores devem receber quais eventos, existem rotas de publicação e subscrição — formando um canal de recebimento e distribuição de eventos. Essas rotas são definidas na configuração de contextos, handlers e tópicos, cada um com um path específico que é concatenado à URL de publicação. Quando os publicadores enviam requisições ao Events Hub, garantimos que ela será distribuída somente aos subscritores cadastrados para receber o evento.

Além do gerenciamento de publicação e subscrição, o Events Hub garante a entrega dos eventos aos subscritores por meio de: acompanhamento do estado do envio; tentativas automáticas de entrega; e, se houver falha, possibilidade de reenvio manual pela própria interface.

Para completar, cuidamos da segurança durante todas as etapas de gerenciamento de eventos. Interceptores de segurança podem ser adicionados ao fluxo de recebimento de eventos para controlar o acesso de publicadores, que podem ser validados por um servidor externo. Em relação aos subscritores, trafegamos uma assinatura digital junto com todos os eventos distribuídos, permitindo a validação da origem das requisições. Um token de segurança estático ou dinâmico também pode ser configurado para que seja trafegado.

Tópicos, handlers e contextos

Tópicos, handlers e contextos são os elementos que formam o canal de publicação e subscrição de eventos. É por meio deles que o Events Hub organiza as rotas de recebimento e distribuição dos eventos, assegurando que as mensagens cheguem aos devidos subscritores.

Como o tópico é o último marcador da URL de publicação, é através dele que o Events Hub encontra os subscritores que deverão receber cada evento. Os publicadores enviam requisições ao Events Hub para a URL de publicação do tópico e o Events Hub encaminhará os eventos para todos os subscritores ativos para o tópico.

Handlers e contextos existem para facilitar o gerenciamento e uso dos tópicos:

  • Handlers são agregadores de tópicos, servindo para agrupar tópicos de forma lógica. Além disso, as políticas de segurança e entrega de eventos são aplicadas ao handler, com todos os tópicos de um handler compartilhando a mesma política.

  • Os contextos permitem o reuso dos tópicos em cenários diferentes. O servidor externo de autorização é definido por contexto — com isso, quando dois contextos diferentes são disponibilizados para um tópico, é possível utilizar dois endpoints distintos de autorização para o mesmo tópico. Isso permite criar um cenário de testes, como no exemplo de uso abaixo.

Exemplo de uso: contextos diferentes para o mesmo tópico

A URL de publicação de eventos é formada por uma URL base (que muda para cada cliente) e marcadores de posição referentes a contexto, handler e tópico: <url-base</<context>/<handler>/<topic>.

Imagine que você tenha um handler chamado "Alerts" de path /alerts que agrupa alguns tópicos de alertas a partir de monitoramento de APIs. Um desses tópicos tem path /latency e é usado para a distribuição de eventos ligados a alertas de latência.

O contexto padrão do Events Hub chama-se "Default" e não adiciona um marcador à URL de publicação. Requisições para o tópico "latency" no contexto padrão serão enviadas para <url-base>/alerts/latency. Todos os subscritores inscritos no tópico e com o contexto padrão habilitado receberão os eventos do tópico distribuídos pelo Events Hub.

Imagine, então, que você queira utilizar o mesmo tópico "latency" mas em um cenário de teste. Nesse caso, você não deseja que os subscritores já inscritos no tópico recebam as requisições de teste. E mais uma coisa: você quer que, ao enviar os testes, o publicador da sua equipe de desenvolvimento não precise validar suas credenciais no endpoint de autorização do contexto padrão, mas quer usar um mock de autorização para os testes.

Para viabilizar os testes, você pode criar um contexto específico (por exemplo, "Testing") e habilitá-lo para o tópico "latency". Ao cadastrar um subscritor para receber os eventos de teste, vincule-o ao tópico "latency" e habilite somente o contexto "Testing" para subscrição. Nesse caso, se um evento for enviado para <url-base>/alerts/latency (no contexto padrão), os subscritores "usuais" receberão o evento. Mas se o evento for enviado para <url-base>/testing/alerts/latency, ele será distribuído para o subscritor de teste. E se você configurar um mock de autorização para o contexto "Testing", o publicador que enviar requisições para <url-base>/testing/alerts/latency será validado pelo mock, enquanto os publicadores que enviarem requisições para <url-base>/alerts/latency serão validados pela URL de autorização cadastrada para o contexto padrão.

Como configurar tópicos, handlers e contextos?

Handlers são criados e gerenciados na tela Handlers.

handlers cards
Tela de cadastro e gerenciamento de handlers

Durante o cadastro ou edição de handlers, você pode criar novos tópicos ou editar os existentes.

handlers create topics2
Cadastro de handlers: etapa de criação de tópicos

Os contextos são criados na tela Contexts e habilitados para cada tópico no processo de criação ou edição de handlers. Ao vincular publicadores e subscritores a um tópico, o usuário define quais dos contextos habilitados para o tópico serão disponibilizados para o publicador e para o subscritor. Os endpoints de autorização de publicadores são definidos para cada contexto na tela Authorizations.

contexts
Tela de cadastro e gerenciamento de contextos.
authorizations
Tela de configuração de endpoints de autorização

Publicadores e subscritores

O Events Hub permite que os dois extremos da integração de eventos — os produtores e os consumidores — sejam cadastrados de forma intuitiva e completamente independente.

Os publicadores são cadastrados na tela Publishers. Eles podem ser cadastrados do zero, mas também é possível importar uma app da Sensedia API Platform. No processo de cadastro, cada publicador é vinculado aos tópicos aos quais poderá enviar requisições e, dentre os contextos habilitados para o tópico, é preciso escolher quais serão disponibilizados para o publicador.

publishers
Tela de cadastro e gerenciamento de publicadores

Os subscritores são cadastrados na tela Subscribers. No processo de cadastro, cada subscritor é inscrito nos devidos tópicos dos quais receberá eventos e, dentre os contextos habilitados para o tópico, é preciso escolher quais serão disponibilizados para o subscritor.

subscribers
Tela de cadastro e gerenciamento de subscritores

No processo de cadastro de subscritores, é necessário configurar para cada tópico inscrito uma URL que receberá os eventos. Com isso, um mesmo subscritor pode receber eventos em URLs diferentes.

subscribers create topics subscribed
Cadastro de subscritores: definição de URL do subscritor

Políticas de segurança na conexão com publicadores e entrega de eventos

Na tela Policies você pode definir a segurança que será aplicada aos publicadores e a configuração de entrega de eventos aos subscritores, que compreende a quantidade de tentativas automáticas que deverão ser feitas.

policies
Tela de configuração e gerenciamento de políticas

A política de segurança é definida por interceptores para validar a identidade dos publicadores (opções: validação de OAuth, JWT, Client ID, Access Token). Também é possível utilizar um interceptor para filtrar o acesso de publicadores por IP.

policies flow
Configuração de política: seção de segurança

As configurações de entrega de eventos aos subscritores incluem a quantidade de tentativas automáticas que serão realizadas caso o primeiro envio falhe, o tempo limite de requisição e os códigos de estado HTTP de retorno que devem disparar uma nova tentativa automática.

policies retry settings
Configuração de política: seção de tentativas automáticas de entregas

As políticas cadastradas na tela Policies são aplicadas aos handlers no processo de criação/edição de handlers. Isso significa que todos os tópicos de um handler utilizam a mesma política. O servidor externo de autorização de publicadores é definido a nível de contexto na tela Authorizations.

Segurança na conexão com subscritores

O Events Hub implementa camadas de segurança que permitem com que os subscritores verifiquem a procedência das mensagens recebidas.

Em primeiro lugar, trafegamos uma assinatura digital em todas as requisições aos subscritores. Essa assinatura é um token JWT gerado a partir de uma chave de conhecimento mútuo entre subscritores e o Events Hub, enviada no processo de cadastro de subscritores.

Como um outro requerimento de segurança para os subscritores, é possível configurar um token estático ou dinâmico que também deverá ser trafegado nas requisições.

subscribers create security
Cadastro de subscritores: etapa para envio de chave de conhecimento mútuo e configuração de token

Detalhes de eventos e reenvio manual

A tela Event Status exibe a lista de eventos recebidos dos publicadores.

event status
Listagem de eventos recebidos dos publicadores

Para cada item da lista, é possível ver detalhes a respeito das tentativas de distribuição do evento aos subscritores.

event status delivery details
Listagem de eventos: detalhes de entregas

Também é possível acessar uma tela com o histórico das tentativas de entrega.

event status history3
Histórico de tentativas de entrega

As tentativas automáticas de entrega seguem um algoritmo de recuo exponencial para aumentar as chances de sucesso. Contudo, se todos os envios a um subscritor fracassarem, é possível tentar uma entrega manual na tela Delivery Retry.

delivery retry
Listagem de eventos com falha na entrega
delivery retry multiple subs
Seleção de subscritores para tentativa manual de entrega
Thanks for your feedback!
EDIT
How useful was this article to you?