Contexts

A tela Contexts lista os contextos cadastrados no seu Events Hub:

contexts

Em resumo, os contextos são uma divisão lógica que funciona como marcador da URL de publicação de eventos. Mas há especificidades a respeito deles. A seção sobre funcionamento abaixo explica em detalhes o papel dos contextos na publicação e distribuição de eventos. No restante desta página, você pode ler sobre como criar e editar contextos.

Funcionamento

Para entender o papel dos contextos, é necessário compreender como o Events Hub coordena a publicação e a subscrição a eventos.

Os publicadores de eventos (publishers) enviam requisições ao Events Hub, que depois as distribui para todos os subscritores (subscribers) cadastrados. Para que o caminho correto de distribuição de eventos seja seguido (ou seja, para que cada evento de um publicador seja encaminhado a todos os devidos subscritores e somente a eles), o Events Hub dispõem de tópicos. Cada tópico pode ter inúmeros subscritores. Quando um publicador envia um evento para um determinado tópico, o Events Hub distribui o evento para todos os subscritores vinculados ao tópico.

O canal de publicação de eventos é a URL utilizada pelos publicadores para enviar requisições ao Events Hub. Essa URL é formada por uma série de marcadores de posição: URL base + context + handler + topic.

A URL base é definida pelo Events Hub, que concatena o endereço da interface de cada cliente + event-receiver + uma hash. Já context, handler e topic são criados pelo usuário. O tópico, como já falamos, define a subscrição. É através dele que o Events Hub organiza quem deve receber cada evento. Handlers funcionam como agregadores de tópicos, servindo como uma camada lógica de agrupamento e ajudando na criação e manutenção de tópicos. As políticas de segurança e tentativas automáticas de envio são aplicadas a nível de handlers, então todos os tópicos de um handler utilizam a mesma política.

Por fim, contextos adicionam mais um marcador à URL. Para que um tópico seja disponibilizado a um publicador, ele tem que ser habilitado em pelo menos um contexto. Como isso modifica as URLs de publicação?

Exemplo 1

Imagine um tópico chamado "latency" agrupado em um handler chamado "Alerts" (path: /alerts). Ao criar o tópico, imagine que você o habilita em dois contextos: "Dev" (/dev) e "Testing" (/testing):

  • no contexto "Dev", a URL de publicação de eventos para o Events Hub será: <url-base>/dev/alerts/latency;

  • no contexto "Testing", a URL de publicação de eventos para o Events Hub será: <url-base>/testing/alerts/latency.

Além de criar mais um separador lógico que ajuda a categorizar os canais de publicação, os contextos ajudam porque tornam possível a utilização de um mesmo tópico em cenários diferentes, sem que você necessite duplicar o tópico para definir um controle de publicadores e subscritores. E, além dessa facilidade, o usuário define os endpoints de autorização de publicadores a nível de contexto, o que permite com que o mesmo tópico tenha mais de um servidor de autorização. Veja o exemplo abaixo para compreender isso melhor.

Exemplo 2

Imagine que o tópico "latency" descrito no exemplo 1 esteja sendo utilizado no seu contexto padrão ("Default"), já exposto a publicadores e subscritores parceiros. Você deseja enviar alguns eventos de teste para esse tópico, e para isso cria um publicador para a sua equipe de desenvolvimento.

Mas você tem dois problemas iniciais:

  1. você não quer que os subscritores parceiros já vinculados ao tópico recebam os seus eventos de teste;

  2. você quer que o publicador da sua equipe de desenvolvimento utilize um mock de autorização ao invés do endpoint utilizado pelo contexto padrão.

Nesse caso, a habilitação de contextos diferentes resolve ambos os problemas. Os publicadores e subscritores que já estão alimentando e consumindo o tópico continuam vinculados ao contexto padrão. Agora, você pode utilizar o contexto "Testing" para os eventos de teste que deseja enviar.

Para isso, você precisa habilitar esse contexto para o tópico "latency". Além disso, precisa também habilitar o tópico para o publicador do seu time de desenvolvimento: ao registrar o publicador, vincule-o ao tópico "latency" na etapa TOPICS de criação/edição e, na mesma etapa, habilite "Testing" como contexto de publicação. O mesmo processo deve ser feito com os subscritores que deverão receber os eventos de teste: ao criá-los, subscreva-os ao tópico "latency" na etapa TOPICS de criação/edição e, na mesma etapa, habilite "Testing" como contexto de subscrição.

Agora, quando o publicador enviar eventos para o tópico "latency" no contexto "Testing" (utilizando a URL de publicação formada por: <url-base>/testing/alerts/latency), apenas os subscritores vinculados ao tópico e com o contexto "Testing" habilitado receberão o evento.

Para resolver o problema de autorização, basta ir à tela Authorizations do Events Hub e inserir o endpoint de autorização que deverá ser utilizado para autorizar os publicadores quando enviarem requisições ao contexto "Testing". Se você configurar um mock de autorização para o "Testing", os publicadores que enviarem eventos para ele serão autorizados pelo mock, enquanto o contexto padrão utilizará o endpoint definido para ele.

É importante ter em mente que os contextos são divisões lógicas que têm o objetivo de facilitar a criação e manutenção de tópicos, viabilizando sua reutilização em diferentes cenários. Os contextos não são ambientes fisicamente separados uns dos outros.

Isso quer dizer que, se você usa o contexto "Default" para eventos produtivos e o contexto "Testing" para eventos de teste, consegue controlar os publicadores, subscritores e endpoints de autorização para cada contexto, mas todos os eventos recebidos e distribuídos no Events Hub compartilharão a mesma infraestrutura.

Testes que onerem a infraestrutura, ainda que feitos no contexto "Testing", poderão afetar o recebimento e distribuição de eventos nos outros contextos.

Contexto Default e outros contextos

Quando você começar a utilizar o Events Hub, verá que só existirá um contexto configurado: o contexto padrão ("Default").

Como descrito acima, os contextos adicionam mais um marcador de posição na URL de publicação de eventos, mas o contexto padrão tem uma característica própria: ele não adiciona nenhum marcador. Veja as diferenças nas URLs de publicação entre o contexto padrão e outros contextos:

Exemplo 3

Pensando no caso do exemplo 1 acima, as URLs de publicação para o tópico "latency" serão:

  • Contexto "Default": <url-base>/alerts/latency

  • Contexto "Dev": <url-base>/dev/alerts/latency

  • Contexto "Testing": <url-base>/testing/alerts/latency

Autorização

Os endpoints que validam os publicadores são definidos para cada contexto. Isso é feito na tela Authorizations, que contém duas seções: uma para URLs de OAuth e outra para JWT.

Após definidas as URLs de autorização, sempre que um publicador enviar requisições para um determinado tópico, será autorizado com base na validação da URL definida para o contexto.

Exemplo 4

Pensando nas URLs de publicação do exemplo 3 acima, teremos:

Contexto URL de publicação de eventos URL de autorização de publicadores

"Default"

<url-base>/alerts/latency

  • OAuth: URL de autorização do contexto "Default" (Authorizations  OAUTH  Default)

  • JWT: URL de autorização do contexto "Default" (Authorizations  JWT  Default)

"Dev"

<url-base>/dev/alerts/latency

  • OAuth: URL de autorização do contexto "Dev" (Authorizations  OAUTH  Dev)

  • JWT: URL de autorização do contexto "Dev" (Authorizations  JWT  Dev)

"Testing"

<url-base>/testing/alerts/latency

  • OAuth: URL de autorização do contexto "Testing" (Authorizations  OAUTH  Testing)

  • JWT: URL de autorização do contexto "Testing" (Authorizations  JWT  Testing)

Vinculação de contextos e tópicos

Para utilizar um tópico para enviar eventos ao Events Hub, ele deve ter ao menos um contexto habilitado.

Os tópicos são sempre gerenciados através dos handlers, que são agrupadores de tópicos. No processo de criação e edição de handlers, a etapa TOPICS permite criar tópicos e habilitar contextos para eles. Nessa etapa, todos os contextos cadastrados no Events Hub são exibidos e o usuário deve habilitar todos os contextos que devem ser disponibilizados para o tópico.

Veja mais sobre o processo de criação de handlers e tópicos aqui.

Vinculação de contextos e publicadores

Quando um publicador é cadastrado no Events Hub, ele é vinculado a todos os tópicos para os quais poderá publicar e, para cada um desses tópicos, os contextos que estarão disponíveis para o publicador devem ser habilitados. Após a vinculação do publicador a um tópico e a habilitação de ao menos um contexto do tópico para o publicador, ele poderá enviar eventos para o tópico.

Para fazer essa vinculação, na etapa TOPICS de registro de um publicador, o usuário deve selecionar todos os tópicos para os quais o publicador poderá enviar eventos. Para cada um dos tópicos, serão exibidos os contextos disponibilizados para o tópico e o usuário deverá então selecionar em quais o publicador poderá publicar.

Veja mais sobre o processo de registro de publicadores aqui.

Vinculação de contextos e subscritores

Quando um subscritor é cadastrado no Events Hub, ele é subscrito em tópicos com habilitação de contextos, representando que ele receberá todos os eventos enviados por publicadores para aqueles tópicos e nos contextos habilitados para subscrição.

Para fazer essa vinculação, na etapa TOPICS de registro de um subscritor, o usuário deve selecionar todos os tópicos em que ele estará subscrito. Para cada um dos tópicos, serão exibidos os contextos disponibilizados para o tópico e o usuário deverá então selecionar quais os contextos de subscrição.

Veja mais sobre o processo de registro de subscritores aqui.

Criando contextos

O Events Hub vem com o contexto padrão ("Default") já criado (e ele não pode ser editado). Além disso, é possível criar outros quatro contextos, totalizando um limite de cinco.

Para criar um novo contexto, clique no botão +, que levará para esta tela de registro:

contexts create

Você deve completar os seguintes campos:

  • Name: nome único identificador do contexto.

  • Path: caminho do contexto, que servirá como marcador da URL de publicação (conforme descrito acima).

  • Description: descrição opcional para o contexto.

Uma vez registrado, o contexto será exibido na etapa TOPICS de criação/edição de handlers e poderá ser habilitado para qualquer tópico.

O botão + está desabilitado, impedindo a criação de um novo contexto. O que fazer?

Além do contexto padrão ("Default"), é possível criar mais quatro contextos, totalizando um máximo de cinco. Se já houver cinco contextos cadastrados, o botão + será desabilitado. Nesse caso, um novo contexto poderá ser criado apenas se um dos existentes for excluído.

Overview de contextos

Ao clicar sobre o nome de um contexto na tela Contexts, o usuário acessa a página de overview do contexto, como a deste exemplo:

contexts overview

A tela lista todos os tópicos que estão habilitados para publicação no contexto selecionado, exibindo o nome do tópico, do handler, e a descrição do tópico (se houver). É possível pesquisar por tópicos utilizando o campo de busca Keywords, que procura por termos utilizados nos nomes dos tópicos e handlers ou na descrição dos tópicos.

Clicando sobre o nome do handler, o usuário é dirigido à tela de overview do handler, em que é possível editar detalhes do próprio handler ou de seus tópicos.

Editando e excluindo contextos

A tela de overview de cada contexto (acessada ao clicar sobre o nome do contexto na tela Contexts), contém o botão EDIT CONTEXT para editar detalhes do contexto e icon delete para excluí-lo.

O contexto padrão ("Default") não pode ser editado ou removido.

Quanto aos outros contextos, se estiverem vinculados a algum tópico, só será possível editar a descrição. Se o contexto não estiver vinculado a nenhum tópico, será possível também editar o nome e o campo Path.

Sé é possível excluir contextos se eles não estiverem associados a nenhum tópico. Se houver tópicos associados, será necessário desabilitar o contexto em cada tópico para então excluí-lo.

Thanks for your feedback!
EDIT
How useful was this article to you?