Guia Rápido

Este guia rápido ajuda a entender o funcionamento do Sensedia Events Hub. Ele dá uma visão geral de como:

• Configurar as rotas para enviar e receber eventos.

• Aplicar políticas de segurança e tentativas automáticas de distribuição dos eventos aos subscritores.

TIP

Os links incluídos nessa página levam a seções mais detalhadas da nossa documentação.

Glossário

Em toda a documentação, você verá alguns termos próprios do contexto de mensageria. Para facilitar o entendimento, explicamos:

• Publicadores: também conhecidos como publishers, são as aplicações remetentes. Eles são responsáveis por criar os eventos e enviá-los ao Events Hub.

• Subscritores: também chamados de subscribers, são os destinatários, aplicações ou parceiros do cliente que recebem os eventos e podem tomar ações com base neles.

• Business moments: são momentos de oportunidade para o negócio que, utilizando o Events Hub, podem ser aproveitados para gerar receita.

Funcionamento geral

O Events Hub permite gerenciar uma arquitetura de distribuição de eventos por meio de uma interface low-code, que não requer conhecimentos avançados de programação. Nela, é possível cadastrar e gerenciar publicadores e subscritores de eventos de forma totalmente independente.

Para que o Events Hub saiba quais subscritores devem receber quais eventos, existem rotas de publicação e subscrição, formando um canal para receber e distribuir eventos. Essas rotas são definidas através de tópicos, handlers e contextos, cada um com um caminho específico que é adicionado à URL de publicação. Quando os publicadores enviam requisições ao Events Hub, garantimos que elas serão distribuídas somente aos subscritores cadastrados para receber o evento.

Além de gerenciar a publicação e subscrição de eventos, o Events Hub garante a entrega aos subscritores por meio de:

• Acompanhamento do status do envio.

• Tentativas automáticas de entrega.

• Reenvio manual através da interface em caso de falha.

Para garantir a segurança durante todo o processo de gerenciamento dos eventos, você pode adicionar interceptores no fluxo de recebimento. Isso permite controlar o acesso de publicadores, que podem ser validados por um servidor externo.

Para os subscritores, incluímos uma assinatura digital junto com todos os eventos distribuídos para validar a origem das requisições. Além disso, você pode configurar um token de segurança estático ou dinâmico para o tráfego seguro das informações.

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. Eles organizam as rotas de recebimento e distribuição dos eventos, assegurando que as mensagens cheguem aos subscritores corretos.

Tópicos

O tópico é o último marcador da URL de publicação e é através dele que o Events Hub encontra os subscritores que devem receber cada evento. Os publicadores enviam requisições usando a URL de publicação do tópico e o Events Hub encaminha os eventos para todos os subscritores ativos no tópico.

Handlers

Os handlers são grupos de tópicos que servem para agrupá-los de forma lógica. Eles também são responsáveis por aplicar políticas de segurança e entrega de eventos, que serão compartilhadas com todos os tópicos dentro dele.

Contextos

Os contextos permitem reutilizar tópicos em diferentes cenários. O servidor externo de autorização é definido por contexto, o que significa que 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.

TIP

A URL de publicação de eventos é composta por duas partes: a base (exclusiva de cada cliente) e os marcadores de posição context, handler e topic, organizados na seguinte estrutura: url-base/context/handler/topic.

Exemplo: mesmo tópico em cenários diferentes

Você tem um handler chamado "Alerts", no path /alerts, onde estão agrupados tópicos de alerta de monitoramento das APIs. Um desses tópicos é /latency, que distribui eventos de alerta de latência.

Nesse cenário, você pode optar por:

1. Não cadastrar nenhum contexto. Quando isso acontece, o Events Hub define o contexto "Default" como padrão, e nenhum marcador é adicionado à URL de publicação. Com isso, requisições para o tópico latency serão enviadas para url-base/alerts/latency e todos os subscritores ativos nele receberão os eventos.

2. Cadastrar um contexto para, por exemplo, definir ambientes. Em um cenário de teste, em que você não quer que os subscritores do tópico recebam alertas, pode cadastrar o contexto testing e habilitá-lo para o tópico latency.

Para cadastrar subscritores no contexto, você deve vinculá-los ao tópico latency e habilitá-los somente para o contexto testing. Assim, os eventos enviados para <url-base>/testing/alerts/latency serão distribuídos apenas para os subscritores desse contexto.

O contexto de teste também permite utilizar um mock de autorização para que sua equipe não precise validar as credenciais do endpoint de autorização do contexto padrão.

Configurar tópicos, handlers e contextos

TIP

Para cadastrar handlers com contexto, recomendamos registrar o contexto previamente na tela Contexts.

Handlers são criados e gerenciados na tela Handlers. Na tela de cadastro e edição de um handler, você pode:

• Criar e editar tópicos e políticas.
• Atribuir contextos aos tópicos, clicando sobre o ícone da seta na tela de cadastro. Eles devem ser previamente cadastrados pela tela Contexts. Os endpoints de autorização de publicadores são definidos para cada contexto na tela Authorizations.

Cadastro de contextos, handlers e tópicos

Publicadores e subscritores

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

Os publicadores são a fonte dos eventos. Eles são cadastrados na tela Publishers. Você pode criá-los ou importar uma app da Sensedia API Platform.

No processo de cadastro, você conecta o publicador aos tópicos para os quais ele enviará eventos. Além disso, você escolhe quais contextos serão compartilhados com ele.

Tela de cadastro e gerenciamento de publicadores

Os subscritores são aqueles que recebem os eventos. Eles são cadastrados na tela Subscribers. Ao cadastrar um subscritor, você o inscreve nos tópicos dos quais receberá eventos e também escolhe quais contextos serão compartilhados com ele.

IMPORTANT

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

Cadastro de subscritores: definição de URL do subscritor

Políticas de segurança para os publicadores

Na tela Policies, você pode definir as medidas de segurança para publicadores e a entrega de eventos aos subscritores. Isso inclui:

• A quantidade de tentativas automáticas de entrega que serão feitas.

• Tempo limite de requisição.

• Códigos de status HTTP que acionam novas tentativas quando retornados.

A segurança para publicadores é garantida por interceptores que validam sua identidade, como OAuth, JWT, Client ID e Access Token. Além disso, você pode filtrar o acesso dos publicadores por IP.

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

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

As políticas se aplicam aos handlers durante sua criação ou edição na tela Handlers. Portanto, todos os tópicos de um handler usam a mesma política.

A autorização de publicadores é definida a nível de contexto por um servidor externo de autorização, configurado na tela Authorizations.

Segurança na conexão com subscritores

O Events Hub implementa camadas de segurança que permitem que os subscritores verifiquem a procedência das mensagens recebidas. Isso acontece por meio de assinaturas digitais trafegadas em todas as requisições. Essa assinatura é um token JWT gerado a partir de uma chave de conhecimento mútuo entre subscritores e o Events Hub durante o cadastro de subscritores.

Para reforçar a segurança, você pode também configurar um token estático ou dinâmico para ser incluído nas requisições.

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

Detalhes de eventos e reenvio manual

Você pode acompanhar em detalhes os eventos recebidos através da tela Event Status. Para cada evento, são mostradas as tentativas e o histórico de distribuição aos subscritores.

Listagem de eventos recebidos dos publicadores

NOTE

Tentativas automáticas de entrega usam um algoritmo de recuo exponencial para aumentar as chances de sucesso. Contudo, se todos os envios a um subscritor falharem, você pode tentar uma entrega manual na tela Delivery Retry.