Event-Driven Callbacks

Durante a operação normal do API Manager, é comum que existam situações nas quais queremos notificar sistemas externos. Por exemplo, quando alguns objetos importantes são criados, alterados ou deletados. Para isso, o API Manager permite cadastrar event-driven callbacks, que são chamadas externas disparadas a partir de gatilhos pré-configurados (eventos).

A tela de visualização de Event-Driven Callbacks é acessada via menu lateral, dentro de Notification. Na tela, é possível criar, alterar, deletar e visualizar as chamadas por eventos já cadastradas, bem como verificar o histórico de ativação de cada chamada separadamente.

É possível configurar várias chamadas a partir de um mesmo tipo de objeto. Por exemplo, você pode desejar executar duas ações diferentes (como enviar email e gerar log) em resposta a um mesmo evento (e.g., criação de uma app). Para reduzir o acoplamento, poderiam ser criados dois event-driven callbacks, um para http://host/send-email e outro para http://host/generate-log.

Olhe alguns exemplos de como a funcionalidade pode ser usada:

Toda vez que…​ …​ faça isto:

um usuário se cadastrar no Portal de Desenvolvedores

envie um email para um administrador.

uma app for criada

crie objetos de sandbox para essa app.

uma app for criada

crie tokens provisórios para acelerar a experimentação dos desenvolvedores.

uma policy for modificada

valide que nenhuma regra permita mais de 100 acessos por segundo.

Funcionamento

Existem dois tipos de eventos: o tipo After (depois) e o tipo Before (antes). Eventos do tipo After são executados depois que um objeto é criado, atualizado ou excluído no Manager. Por exemplo, se um usuário criar uma app e houver um evento cadastrado como After App, a chamada será disparada logo após a criação da app no backend.

Já eventos do tipo Before são disparados antes de uma ação no Manager. Sendo assim, a criação/atualização/exclusão de um objeto poderá ser cancelada caso a chamada à URL cadastrada no event-driven callback falhe por qualquer motivo.

Um administrador cria um event-driven callback informando: a) qual o tipo de objeto que deseja observar; e b) uma URL. Quando objetos do tipo selecionado forem criados, alterados ou deletados, o API Manager fará uma requisição POST para a URL informada. Nesse caso, dizemos que o event-driven callback foi "ativado". O corpo da requisição POST conterá uma representação JSON do objeto em questão e mais alguns dados, como a ação (created, updated ou deleted) e o usuário responsável por ela.

callbacks diagram pt

O event-driven callback cadastrado pode ser disparado ANTES ou DEPOIS, dependendo do seu tipo (Before ou After). Depois de disparado, um listener é notificado de um evento e, se o callback for do tipo Before, o próprio callback pode bloquear a ação de criação/atualização/exclusão de um objeto qualquer, pois uma validação pode ser realizada antes que a ação ocorra de fato.

No caso de event-driven callbacks do tipo After, a ação (criação/atualização/exclusão) não será bloqueada, mas gerará uma mensagem de erro ou aviso alertando sobre o evento ocorrido.

Se um callback do tipo After e um do tipo Before forem cadastrados para o mesmo tipo de objeto, os dois serão executados, mas os eventos do tipo Before têm prioridade sobre eventos do tipo After.

Criando event-driven callbacks

Para criar um novo callback, clique no botão Create Event-Driven Callback, representado pelo símbolo + no canto inferior direito da tela. Uma janela modal será aberta para preenchimento dos dados.

Digite o nome (Name), escolha o tipo de evento que será observado no campo Event Type (veja tipos disponíveis abaixo) e informe a URL de um sistema criado para fins de notificação.

O campo Expected HTTP Status será habilitado apenas para eventos do tipo Before e deverá ser preenchido com o status HTTP esperado no retorno da chamada à URL cadastrada. Isso porque eventos desse tipo comparam o status cadastrado com o status retornado pela chamada para saber se podem prosseguir com a operação ou não.

O campo Request Headers não é obrigatório. Como já mencionamos, os callbacks são disparados a partir do monitoramento de ações de criação, atualização e exclusão de objetos. Se quisermos utilizar apenas uma ou duas das ações como gatilho, devemos inserir a propriedade action no campo Request Headers.

Depois de todos os campos estarem preenchidos corretamente, clique em Save.

Tipos de eventos

Os callbacks podem ser configurados como do tipo Before ou After para as ações (criação, edição e exclusão) destes objetos: access token, API, app, desenvolvedor, plano e configuração de sistema.

As páginas seguintes trazem exemplos dos corpos de requisição que serão enviados em cada caso:

Editando um event-driven callback

Para editar um callback já cadastrado, clique no ícone icon edit, encontrado na coluna Actions da listagem de callbacks. Uma janela modal contendo as informações do callout será aberta, e você poderá alterar os dados. Quando terminar, clique em Save.

Excluindo um event-driven callback

Para excluir um callback, clique no ícone icon delete, encontrado no campo Actions da listagem de callbacks .

Uma mensagem de confirmação será exibida. Clique em Ok para efetuar a remoção.

Erros e histórico de ativação

Caso ocorra algum erro durante a requisição POST para a URL informada (incluindo casos em que o host é desconhecido ou recusa conexões), o processamento do API Manager não será afetado e não serão feitas novas tentativas de POST.

Porém, o Manager mantém um histórico de todas as notificações que tentou enviar. Para ver o histórico de ativação de um event-driven callback, clique no link formado por data e horário na coluna Last triggered on na listagem de callbacks. Uma tela mostrará os detalhes do callback selecionado.

Chamando a API do Manager em seus event-driven callbacks

Muitas vezes, é desejável criar um callback para modificar ou complementar informações recebidas. Por exemplo, pode-se estabelecer que, quando uma app for criada, seja assumido o valor Java sempre que um valor do campo extra fields não seja especificado.

Porém, como o listener recebe o objeto depois que ele já foi criado, será necessário chamar a API do Manager para fazer a alteração.

Observe, porém, que alterações no Manager podem, por sua vez, disparar outros listeners. Deve-se tomar cuidado para não criar um loop infinito de eventos.

Note também que a API do Manager é, por si só, protegida com credenciais de acesso (para maiores detalhes, veja o tópico Users). Você deve criar credenciais do tipo "Integration" para que seu sistema interaja com o Manager de forma bem-sucedida.

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