HTTP Trigger

Descubra mais sobre o HTTP Trigger e saiba como utilizá-lo na Digibee Integration Platform.

IQuando um pipeline é configurado e publicado com o HTTP Trigger, um endpoint HTTP é criado automaticamente. Você pode visualizar esse endpoint após a implantação - basta clicar no cartão do pipeline na tela de Run.

Com esse trigger, você tem a flexibilidade de definir diferentes tipos de conteúdo tanto para a requisição como para a resposta do endpoint.

Parâmetros

Dê uma olhada nas opções de configuração do componente. Parâmetros suportados por expressões Double Braces estão marcados com (DB).

Parâmetro Descrição Valor padrão Tipo de dado

Parâmetro	Descrição	Valor padrão	Tipo de dado
Methods	Serve para configurar os verbos HTTP a serem suportados pelo endpoint após a implantação.	POST, PUT, GET, PATCH, DELETE e OPTIONS	String
Request Content Types	Determina os tipos de conteúdo que o endpoint pode receber.	text/xml, application/xml and application/x-www-form-urlencoded	String
Response Content Types `(DB)`	Tipos de conteúdo a serem retornados pelo endpoint quando o processamento no pipeline terminar. Esse parâmetro não pode ser deixado vazio (a resposta depende de tratamento com o mock + Double Braces). Caracteres especiais não devem ser utilizados nas chaves, por conta de possíveis falhas em proxys e gateways.	text/xml, application/xml	String
Response Headers `(DB)`	Headers a serem retornados pelo endpoint quando o processamento no pipeline terminar. Esse parâmetro não pode ser deixado vazio e aceita Double Braces. Caracteres especiais não devem ser utilizados nas chaves, por conta de possíveis falhas em proxys e gateways.	N/A	Pares Chave-Valor
Add Cross-Origin Resource Sharing (CORS) - CORS Headers	Adicione os CORS headers a serem retornados pelo endpoint quando o processamento no pipeline terminar. Este parâmetro define o CORS especificamente ao pipeline e suas restrições.	N/A	Pares Chave-Valor
Maximum Timeout	Tempo máximo para o pipeline processar informação antes de retornar uma resposta. Limite: 900000. Em milissegundos. Se o processamento demorar mais que a definição do parâmetro, a request é finalizada e retorna um status code 500, mas sem body algum.	30000	Inteiro
Maximum Request Size	Tamanho máximo do payload (em MB). O limite máximo do payload configurável é de 5MB.	5	Inteiro
External API	Se a opção estiver ativada, a API é publicada em um gateway externo.	True	Booleano
Internal API	Se a opção estiver ativada, a API é publicada em um gateway interno. O pipeline pode ter tanto a opção de External API quanto a Internal API habilitadas simultaneamente.	False	Booleano
mTLS enabled API	Se a opção estiver ativada, a API é publicada em um gateway dedicado a APIs com mTLS ativo por padrão. Nesse caso, o host de acesso será diferente dos demais. O pipeline pode ter tanto a opção de External API quanto a Internal API habilitadas simultaneamente, mas é recomendado deixá-las inativas.	False	Booleano
API Key	Se a opção estiver ativada, o endpoint pode ser consumido apenas se for enviada uma chave de API previamente configurada na Digibee Integration Platform.	False	Booleano
Token JWT	Se a opção estiver ativada, o endpoint pode ser consumido apenas se for enviado um token JWT previamente gerado por outro endpoint com essa capacidade. Leia o artigo da implementação JWT para obter mais detalhes.	False	Booleano
Basic Auth (Fase Beta)	Se a opção estiver ativada, o endpoint só pode ser consumido se uma configuração de Basic Auth estiver presente na requisição. Essa configuração pode ser previamente registrada pela página de Consumers na Digibee Integration Platform.	False	Booleano
Additional API Routes	Se a opção estiver ativada, o trigger permite que você configure novas rotas. Veja mais sobre esse parâmetro na seção abaixo.	False	Booleano
Remove Digibee Prefix from Route	Esta opção estará disponível somente quando os parâmetros External API e Internal API estiverem desabilitados, e os parâmetros mTLS enabled API e Additional API Routes estiverem habilitados. Defina esta opção para remover o prefixo de rota padrão Digibee "/pipeline/{realm}/v{n}" da rota do pipeline. Saiba mais sobre o parâmetro na seção abaixo.	False	Booleano
Routes	Exibido somente quando o parâmetro Additional API Routes estiver habilitado. É aqui que você consegue definir as rotas adicionais do endpoint.	N/A	String
Rate Limit	Se a opção estiver ativada, uma configuração de rate limiting será aplicada no API Gateway. Esta opção estará disponível somente se API Key ou Basic Auth estiverem ativados. Veja mais sobre esse parâmetro na seção abaixo.	False	Booleano
Limit by	Define a entidade na qual os limites serão aplicados.	API	String
Aggregate by	Define a entidade agregadora dos limites. Opções: Consumer ou Credential (API Key, Basic Auth)	Consumer	String
Options	Define o limite de requisições que podem ser feitas dentro de um período de tempo.	N/A	Lista de opções
Interval	Define o intervalo de tempo para o limite de requisições. Opções: second, minute, hour, day e month	second	String
Limit	Define o número máximo de requisições que os usuários podem fazer no intervalo de tempo especificado.	N/A	Inteiro
Allow Redelivery Of Messages	Se a opção estiver ativada, permite o reenvio da mensagem em caso de falha do Pipeline Engine. Leia o artigo sobre o Pipeline Engine para obter mais detalhes.	False	Booleano

Methods

Serve para configurar os verbos HTTP a serem suportados pelo endpoint após a implantação.

POST, PUT, GET, PATCH, DELETE e OPTIONS

String

Request Content Types

Determina os tipos de conteúdo que o endpoint pode receber.

text/xml, application/xml and application/x-www-form-urlencoded

String

Response Content Types (DB)

Tipos de conteúdo a serem retornados pelo endpoint quando o processamento no pipeline terminar. Esse parâmetro não pode ser deixado vazio (a resposta depende de tratamento com o mock + Double Braces). Caracteres especiais não devem ser utilizados nas chaves, por conta de possíveis falhas em proxys e gateways.

text/xml, application/xml

String

Response Headers (DB)

Headers a serem retornados pelo endpoint quando o processamento no pipeline terminar. Esse parâmetro não pode ser deixado vazio e aceita Double Braces. Caracteres especiais não devem ser utilizados nas chaves, por conta de possíveis falhas em proxys e gateways.

N/A

Pares Chave-Valor

Add Cross-Origin Resource Sharing (CORS) - CORS Headers

Adicione os CORS headers a serem retornados pelo endpoint quando o processamento no pipeline terminar.

Este parâmetro define o CORS especificamente ao pipeline e suas restrições.

N/A

Pares Chave-Valor

Maximum Timeout

Tempo máximo para o pipeline processar informação antes de retornar uma resposta. Limite: 900000. Em milissegundos. Se o processamento demorar mais que a definição do parâmetro, a request é finalizada e retorna um status code 500, mas sem body algum.

30000

Inteiro

Maximum Request Size

Tamanho máximo do payload (em MB). O limite máximo do payload configurável é de 5MB.

Inteiro

External API

Se a opção estiver ativada, a API é publicada em um gateway externo.

True

Booleano

Internal API

Se a opção estiver ativada, a API é publicada em um gateway interno. O pipeline pode ter tanto a opção de External API quanto a Internal API habilitadas simultaneamente.

False

Booleano

mTLS enabled API

Se a opção estiver ativada, a API é publicada em um gateway dedicado a APIs com mTLS ativo por padrão. Nesse caso, o host de acesso será diferente dos demais. O pipeline pode ter tanto a opção de External API quanto a Internal API habilitadas simultaneamente, mas é recomendado deixá-las inativas.

False

Booleano

API Key

Se a opção estiver ativada, o endpoint pode ser consumido apenas se for enviada uma chave de API previamente configurada na Digibee Integration Platform.

False

Booleano

Token JWT

Se a opção estiver ativada, o endpoint pode ser consumido apenas se for enviado um token JWT previamente gerado por outro endpoint com essa capacidade. Leia o artigo da implementação JWT para obter mais detalhes.

False

Booleano

Basic Auth (Fase Beta)

Se a opção estiver ativada, o endpoint só pode ser consumido se uma configuração de Basic Auth estiver presente na requisição. Essa configuração pode ser previamente registrada pela página de Consumers na Digibee Integration Platform.

False

Booleano

Additional API Routes

Se a opção estiver ativada, o trigger permite que você configure novas rotas. Veja mais sobre esse parâmetro na seção abaixo.

False

Booleano

Remove Digibee Prefix from Route

Esta opção estará disponível somente quando os parâmetros External API e Internal API estiverem desabilitados, e os parâmetros mTLS enabled API e Additional API Routes estiverem habilitados. Defina esta opção para remover o prefixo de rota padrão Digibee "/pipeline/{realm}/v{n}" da rota do pipeline. Saiba mais sobre o parâmetro na seção abaixo.

False

Booleano

Routes

Exibido somente quando o parâmetro Additional API Routes estiver habilitado. É aqui que você consegue definir as rotas adicionais do endpoint.

N/A

String

Rate Limit

Se a opção estiver ativada, uma configuração de rate limiting será aplicada no API Gateway. Esta opção estará disponível somente se API Key ou Basic Auth estiverem ativados. Veja mais sobre esse parâmetro na seção abaixo.

False

Booleano

Limit by

Define a entidade na qual os limites serão aplicados.

API

String

Aggregate by

Define a entidade agregadora dos limites. Opções: Consumer ou Credential (API Key, Basic Auth)

Consumer

String

Options

Define o limite de requisições que podem ser feitas dentro de um período de tempo.

N/A

Lista de opções

Interval

Define o intervalo de tempo para o limite de requisições. Opções: second, minute, hour, day e month

second

String

Limit

Define o número máximo de requisições que os usuários podem fazer no intervalo de tempo especificado.

N/A

Inteiro

Allow Redelivery Of Messages

Se a opção estiver ativada, permite o reenvio da mensagem em caso de falha do Pipeline Engine. Leia o artigo sobre o Pipeline Engine para obter mais detalhes.

False

Booleano

Existe um parâmetro de configuração global que obriga todos os pipelines a serem publicados com ao menos a opção API Key ou Basic Auth habilitada.

Informações adicionais sobre parâmetros

O Cross-Origin Resource Sharing (CORS) é um mecanismo que permite informar ao navegador quais origens tem a permissão para fazer requisições. Para configurar de forma global ao invés de individualmente em cada pipeline consulte o artigo CORS Global.

Utilizamos vírgula para informar múltiplos valores em um header, mas não adicionamos espaço antes ou após a vírgula. Caracteres especiais não devem ser utilizados nas chaves, por conta de possíveis falhas em proxys e gateways.

Maximum Request Size:

Caso o payload enviado pelo consumidor do endpoint ultrapasse o limite, será retornada uma mensagem indicando que o tamanho máximo foi ultrapassado e um status-code 413 com a seguinte mensagem:

{  
    "message": "Request size limit exceeded"
}

mTLS enabled API

Este parâmetro não suporta API Key, JWT ou Basic Auth. Para utilizá-lo no seu realm, é necessário fazer uma solicitação via chat e assim enviaremos as informações necessárias para instalação deste serviço.

Additional API Routes

Conforme explicado anteriormente, essa opção serve para configurar rotas novas no endpoint.

Ao implantar um pipeline, uma URL é criada automaticamente. No entanto, você pode customizar a rota de acordo com o que for mais conveniente. Isso inclui também o recebimento de parâmetros através da rota.

Depois que os pipelines são implantados, as URLs adquirem a seguinte estrutura:

TEST:

https://test.godigibee.io/pipeline/{realm}/v{n}/{pipeline-name}

ou PROD:

https://api.godigibee.io/pipeline/{realm}/v{n}/{pipeline-name}

{realm}: corresponde ao realm.
v{n}: versão principal (major) do pipeline.
{pipeline-name}: nome dado ao pipeline.

Rota estática customizada

Vamos supor que você criou o pipeline product-list. Levando em consideração o comentário acima, a sua URL teria a seguinte aparência:

https://test.godigibee.io/pipeline/realm/v1/product-list

Agora, veja como configurar uma rota estática para esse caso.

Com essas configurações aplicadas e o pipeline implantado, você obtém uma nova URL:

https://test.godigibee.io/pipeline/realm/v1/products

Rota customizada com parâmetro no caminho

Usando como exemplo o mesmo pipeline configurado anteriormente, veja como configurar a rota:

Com essas configurações aplicadas e o pipeline implantado, você obtém uma nova URL:

https://test.godigibee.io/pipeline/realm/v1/products/:id

Nesse caso, o consumidor do endpoint pode enviar uma requisição contendo o id de um produto e retornar apenas as informações dele. Exemplo da URL na requisição:

https://test.godigibee.io/pipeline/realm/v1/products/10156

Para utilizar esse valor enviado pela rota dentro do pipeline, recorra à sintaxe Double Braces:

{{ message.queryAndPath.id }}

Remove Digibee Prefix from Route

Como explicado anteriormente, esta opção é recomendada para remover o prefixo de rota padrão Digibee da rota do pipeline.

Digamos que você tenha criado um pipeline e definido o trigger da seguinte forma:

Com as configurações aplicadas e o pipeline implantado, você terá uma nova URL:

https://test.godigibee.io/products

Ao remover o prefixo padrão e definir a rota do pipeline pelo parâmetro Additional API Routes, tenha cuidado para não definir uma rota de pipeline existente que esteja em uso por outros pipelines. Caso você tenha mais do que uma versão principal do pipeline, também é importante ter em mente que o versionamento da rota do pipeline deve ser feito pelo usuário devido à ausência de um parâmetro para versionamento da rota. Por exemplo: /pipeline/realm/v1/.

Rate Limit

Ao criarmos APIs, geralmente queremos limitar o número de requisições da API que usuários podem fazer em um dado intervalo de tempo.

Esta ação pode ser executada ativando a opção Rate Limit e aplicando as seguintes configurações:

Se a API possui rotas adicionais, o limite é compartilhado entre todas as rotas. Para aplicar as configurações de rate limit, a API precisa ser configurada com uma API Key ou Basic Auth para que o parâmetro Aggregate by possa ser usado por grupos de credenciais se a opção Consumer estiver selecionada, ou por credenciais individuais se a opção Credential (API Key, Basic Auth) estiver selecionada.

Se vários parâmetros Interval estiverem configurados com valores repetidos, apenas um desses valores é considerado. Também é necessário que um valor maior que zero seja informado para o parâmetro Limit.

Se as opções de rate limiting não forem definidas corretamente, elas serão ignoradas e um warning log será emitido. Você pode visualizar esse log na página de Pipeline Logs.

HTTP Trigger em Ação

Veja a seguir como o trigger se comporta em determinada situação e a sua respectiva configuração.

API de consulta de informações com retorno em XML

Observe como configurar um pipeline com o HTTP Trigger para retornar uma informação de dentro do pipeline em formato XML e como o retorno deve ser tratado especificamente para esse trigger.

Primeiramente, crie um novo pipeline e configure o trigger. A configuração pode ser feita da seguinte forma:

Com as configurações acima, você determina que:

o endpoint funciona apenas com o verbo GET;
a requisição aceita somente content-type relacionados ao XML;
o response retorna somente content-type relacionados ao XML.

Além disso, você determina que a API é do tipo externa e não precisa de token para a comunicação.

Esse exemplo serve apenas para fins educacionais. Em alguns casos você não deve deixar o endpoint aberto por questões de segurança.

Agora observe como configurar um MOCK no pipeline para que ele seja o provedor de dados que o endpoint retorna ao final. Coloque o componente indicado, conecte-o ao trigger e configure-o com o seguinte JSON:

{
    "data": {
        "products": [
            {
                "name": "Samsung 4k Q60T 55",
                "price": 3278.99
            },
            {
                "name": "Samsung galaxy S20 128GB",
                "price": 3698.99
            }
        ]
    }
}

O próximo passo é adicionar um componente que transforme o JSON previamente criado em um padrão XML. Para isso, utilize o JSON To XML Transformer, adicione-o no canvas e conecte-o logo após o JSON Generator colocado previamente. Mantenha a configuração da seguinte forma:

Feito isso, o último passo é formatar e determinar como será realizado o retorno dessas informações para o consumidor. Coloque um MOCK novamente, sendo que dessa vez a sua função é apenas formatar a resposta. Conecte-o à saída do JSON To XML Transformer.

Para a configurar esse MOCK, utilize o seguinte JSON:

{    
    "code": 200,    
    "body": {{ message.data }},    
    "Content-Type": "text/xml"
}

code: HTTP Status Code a ser retornado pelo endpoint após a finalização da requisição
body: corpo da mensagem de resposta (Double Braces estão sendo utilizados para repassar a informação convertida no passo anterior). Esse item precisa ser necessariamente uma string. Se o dado que você deseja enviar é um JSON, utilize a função TOSTRING.
Content-type: tipo de conteúdo do corpo da resposta. Todos os tipos são suportados, porém precisam ser declarados no campo Response Content Types.

Ao finalizar todas essas configurações, você deve ter um pipeline parecido com o que a imagem abaixo demonstra:

Após a implantação, pegue a URL gerada e envie uma requisição do tipo GET. O endpoint deve retornar o status-code 200, conforme definido anteriormente, e o corpo da resposta deve ter a seguinte aparência:

<?xml version='1.0' encoding='UTF-8' standalone='no' ?>
<doc>
  <products>
    <name>Samsung 4k Q60T 55</name>
    <price>3278.99</price>
  </products>
  <products>
    <name>Samsung galaxy S20 128GB</name>
    <price>3698.99</price>
  </products>
</doc>

Sempre que você realizar uma requisição ao endpoint criado, a estrutura da mensagem que o trigger entrega ao pipeline é sempre a mesma e segue este padrão:

{
  "body": "<xml>\n\t<id>1</id>\n</xml>\t",
  "form": {},
  "headers": {
    "Host": "pipeline-trigger-http:8100",
    "Connection": "keep-alive",
    "X-Forwarded-For": "***",
    "X-Forwarded-Proto": "http",
    "X-Forwarded-Host": "***",
    "my-custom-header": "a"
  },
  "queryAndPath": {
    "id": "1"
  },
  "method": "POST",
  "contentType": "application/xml",
  "path": "/pipeline/digibee/v1/trigger-http/1"
}

body: conteúdo a ser enviado no payload do request para ser transformado em string neste campo.
form: se o form-data for utilizado no request, os dados enviados são entregues neste campo.
headers: os headers enviados no request são entregues neste campo, mas alguns são preenchidos automaticamente de acordo com a ferramenta utilizada para realizar o request.
queryAndPath: os parâmetros de query e path passados na URL são entregues neste campo.
method: método HTTP utilizado no request a ser entregue neste campo.
contentType: quando informado no request, o valor do Content-type é repassado para o pipeline dentro deste campo.
path: o path utilizado na URL no request é repassado nesse campo.