Subscribers

Os subscritores (subscribers) são as aplicações ou parceiros que recebem os eventos distribuídos pelo Events Hub.

A subscrição em eventos é feita por meio da vinculação entre subscritores e tópicos (que são agrupados dentro de handlers). Para cada tópico, é possível definir quais contextos estarão disponíveis para o subscritor. Então, toda vez que um evento for enviado para um determinado tópico e em dado contexto, o Events Hub distribuirá o evento para todos os subscritores do tópico com o contexto habilitado. Para saber mais sobre tópicos, acesse a página sobre handlers, e veja mais sobre contextos aqui.

O Events Hub cuida de toda a segurança para que cada subscritor possa garantir que a mensagem foi enviada por uma fonte totalmente confiável. Para ter detalhes sobre o funcionamento da segurança entre o Events Hub e os subscritores, confira a página sobre segurança.

A tela Subscribers lista todos os subscritores cadastrados e permite criar novos:

Lista de subscritores

A lista de subscritores informa o nome, descrição, status (que pode ser aprovado, pendente, rejeitado ou cancelado) e data de criação. A lista pode ser ordenada por nome ou data de criação e de forma crescente ou decrescente, a partir dos ícones de ordenação ao lado dos campos NAME e CREATION DATE.

Acima da listagem, é possível pesquisar por nome do subscritor no campo de busca Name ou abrir filtros avançados pelo ícone icon search , que permitem pesquisar por desenvolvedor, handler, data inicial e final de criação, ou status:

Clicando sobre o nome de um subscritor, o usuário é dirigido para a tela de overview, que permite editar as informações do subscritor e habilitar ou desabilitar tópicos para recebimento de eventos:

Criando subscritores

Para registrar um subscriber, clique no botão flutuante +, no canto inferior direito da tela. O processo de registro é composto de quatro telas: OVERVIEW, SECURITY, TOPICS e REVIEW.

Overview

A primeira etapa de registro contém os seguintes campos a serem preenchidos:

Name: nome do subscriber, que deve ser único.
Status: estado, entre aprovado (approved), pendente (pending), rejeitado (rejected) ou cancelado (canceled).
Description: campo não obrigatório para incluir uma descrição.
Developer: campo para inserir o email do desenvolvedor responsável pelo subscriber.

Security

A segunda etapa de registro corresponde à configuração da segurança na conexão entre subscritores e o Events Hub (veja mais detalhes sobre isso aqui).

Implementamos duas camadas de segurança:

Na distribuição de eventos aos subscritores, passamos uma assinatura digital que permite com que o subscritor valide a origem da requisição. Para que essa assinatura seja gerada, é necessário que uma chave de conhecimento mútuo entre Events Hub e o subscritor seja enviada no processo de registro do subscritor.
É possível configurar um token para que também seja trafegado nas requisições aos subscritores. Esse token pode ser estático ou dinâmico e também é cadastrado nesta etapa.

Ao chegar nesta etapa, a tela conterá uma URL e um timer marcando o tempo restante para que seja enviada uma chave de conhecimento mútuo entre Events Hub e o subscritor:

A chave deve ser enviada no corpo de uma requisição POST no padrão descrito aqui. A URL de destino aceita somente uma requisição e pode ser copiada clicando-se no ícone icon copy .

Se o tempo de validade da URL expirar, será exibido o ícone icon refresh , que gera uma nova URL.

No exemplo abaixo, estamos enviando uma chave pelo Postman:

Após um envio bem sucedido, a tela exibirá uma mensagem de que o envio da chave foi validado:

Se o processo de registro do subscriber for cancelado sem o envio da chave de conhecimento mútuo, o subscriber estará cadastrado no Events Hub mas não será possível vinculá-lo a nenhum tópico. Essa vinculação só será possível após o envio de uma chave pelo processo de edição do subscriber.

Após o envio da chave, é possível incluir um token estático ou dinâmico a ser trafegado nas requisições aos subscritores. Para isso, clique no botão CONFIGURE TOKEN. Ver mais sobre os tokens (incluindo a diferença entre o estático e o dinâmico) aqui.

A inclusão de token não é obrigatória, sendo possível prosseguir diretamente para a etapa TOPICS.

Para cadastrar um token estático, é necessário informar:

Type: tipo do token (escolher Static).
Location: onde o token deverá ser passado na requisição (opções: header ou query param).
Name: nome com o qual o valor do token será passado.
Token SHA-256: valor do token. Se desejar, é possível gerar um token randômico pelo ícone .
- Após salvar o token, ele será exibido apenas uma vez em uma janela modal, que conterá botões para copiá-lo ou salvá-lo em formato TXT:

Para cadastrar um token dinâmico, é necessário informar:

Type: tipo do token (escolher Dynamic).
Location: onde o token deverá ser passado na requisição (opções: header ou query param).
Name: nome com o qual o valor do token será passado.
URL OAuth: URL de geração do valor do token.
- Após clicar para salvar o token, será enviada uma requisição para a URL para gerar o token e validar a configuração. Cheque detalhes da requisição enviada e a resposta esperada aqui.

Se algum token for configurado, a tela mostrará seus detalhes, além da informação de validação do envio da chave:

Você pode configurar apenas um token por subscriber.

Topics

A etapa TOPICS compreende a subscrição a tópicos específicos para que eventos sejam recebidos do Events Hub. Os tópicos cadastrados são exibidos por meio dos handlers (que são agrupadores de tópicos):

Você pode procurar por handlers usando o campo de busca Keywords acima da lista de handlers, que procura por termos usados no nome ou descrição do handler.

Ao encontrar o handler desejado, clique no ícone icon view topics , que abre uma janela com os tópicos agregados ao handler:

Ao escolher os tópicos, é necessário habilitar os contextos de subscrição. Isso possibilita controlar a distribuição de eventos aos subscritores com base em cenários de uso diferentes. Veja este exemplo de uso para entender melhor:

Imagine, por exemplo, que você queira que o subscritor "Subscriber A" receba eventos do tópico "Example". Ao mesmo tempo, quer que sua equipe de desenvolvimento faça testes para o mesmo tópico "Example" e que a própria equipe de desenvolvimento receba eventos como subscritora.

Você pode criar um contexto para testes (chamado, por exemplo, "Testing") e habilitar o tópico "Example" tanto para o contexto padrão ("Default") quando para o contexto "Testing".

Ao cadastrar o "Subscriber A", você pode adicionar o tópico "Example" mas habilitar apenas o contexto padrão para subscrição. Pode, então, cadastrar um outro subscriber para o seu time de desenvolvimento e, para esse subscriber, habilitar "Testing" como contexto de subscrição para o tópico "Example".

Os tópicos com contextos habilitados estarão com o ícone icon expand colorido. Clicando sobre ele, você verá que os contextos (que estão habilitados a nível do tópico) estarão desabilitados para o subscritor que está sendo configurado. Habilite os contextos que desejar pelo botão da coluna PUBLISH:

Se você quiser incluir um tópico mas o ícone icon expand

estiver cinza, será necessário primeiro habilitar um contexto para o tópico, o que é feito no processo de edição de handlers.

Cada tópico selecionado será listado na seção SUBSCRIBED TOPICS acima da listagem de handlers (e pode ser removido pelo ícone icon delete ):

Cada novo tópico incluído terá o ícone icon warning na coluna STATUS, que mostra que é necessário configurar a URL de destino de eventos. Para fazer isso, clique no ícone icon expand da coluna CONFIGURATION.

Inclua a URL que deverá receber os eventos no campo Subscriber URL e o código de estado de sucesso que deverá ser retornado. Após clicar no ícone icon ok , o Events Hub fará uma requisição para validação da URL esperando esse código de retorno. Se o retorno for diferente do esperado, uma janela modal avisará o usuário e ele poderá confirmar o uso da URL mesmo sem ter sido validada.

Se desejar, é possível habilitar criptografia do corpo para cada tópico marcando a opção Encrypt Body. Nesse caso, o Events Hub usa a chave do subscritor enviada na requisição POST descrita acima para criptografar o corpo enviado pelo publicador e repassar o corpo criptografado ao subscritor.

O subscritor pode descriptografar o corpo utilizando como base o trecho de código abaixo (para Java 8+):^*

// Descriptografar body

public static String decrypt(String contentBase64, byte[] subscriberKey, String salt) {
    try {
        byte[] contentEncoded = Base64.decodeBase64(contentBase64);
        char[] keyToCharArray = new String(subscriberKey, StandardCharsets.UTF_8).toCharArray();
        SecretKeyFactory factory = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256");
        KeySpec spec = new PBEKeySpec(keyToCharArray, salt.getBytes(), 65536, 256);
        SecretKey tmp = factory.generateSecret(spec);
        SecretKeySpec secretKey = new SecretKeySpec(tmp.getEncoded(), "AES");
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        GCMParameterSpec ivSpec = new GCMParameterSpec(128, salt.getBytes());
        cipher.init(Cipher.DECRYPT_MODE, secretKey, ivSpec);
        byte[] contentDecripted = cipher.doFinal(contentEncoded);
        return new String(contentDecripted, StandardCharsets.UTF_8);
    } catch (Exception ex) {
        throw new IllegalStateException("Erro descriptografando conteúdo: " + ex);
    }
}

^* A chave subscriberKey do código acima é a chave mútua enviada pelo POST descrito acima. Para o salt, utilizar o sub que é trafegado com a assinatura JWT (ver mais sobre a assinatura aqui).

Também é possível que publicadores e subscritores tenham um entendimento quanto à criptografia de corpo, com o publicador enviando um corpo já criptografado ao Events Hub. Nesse caso, a opção de criptografar o corpo não deve ser marcada.

Após a configuração da URL do subscritor, os tópicos serão exibidos na seção SUBSCRIBED TOPICS, como neste exemplo:

subscribers create topics subscribed view

Na coluna STATUS, um ícone verde significa que a URL foi validada, enquanto um ícone cinza significa que a URL foi cadastrada mas requisição de validação falhou.

Review

A etapa final de registro de um subscriber exibe os dados cadastrados:

Editando e excluindo subscritores

Tanto a edição quanto a exclusão de subscritores são feitas na tela de overview, que é acessada ao clicar sobre o nome na lista da tela Subscribers:

Para editar os dados básicos do subscritor (nome, descrição, estado e desenvolvedor), clique no botão EDIT SUBSCRIBER. Os campos para edição são iguais ao da etapa OVERVIEW de registro.

A edição dos tópicos habilitados é feita na aba TOPICS, clicando em EDIT TOPICS. O processo é o mesmo descrito na etapa TOPICS de registro.

Para incluir, excluir ou editar o token de segurança que deverá ser trafegado com as requisições, clique na aba SECURITY:

Para excluir um subscritor, clique no botão button delete .

Thanks for your feedback!

EDIT

How useful was this article to you?