REST Trigger

Conheça o trigger e saiba como utilizá-lo.

Erick Rubiales avatar
Escrito por Erick Rubiales
Atualizado há mais de uma semana

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

Com esse trigger, você pode criar APIs que atendem o padrão REST e definir rapidamente quais os métodos que seu endpoint responderá.

Dê uma olhada nos parâmetros de configuração do trigger:

  • Methods: serve para configurar os verbos HTTP a serem suportados pelo endpoint após a implantação. Caso nenhum valor seja informado, será assumido o valor default: POST, PUT, GET, PATCH, DELETE e OPTIONS.

  • Response Headers: 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.

  • Maximum Timeout: tempo limite para que o pipeline processe informações antes de retornar uma resposta (padrão = 30000, limite = 300000). Em milissegundos. Caso o processamento demore mais do que a determinação do parâmetro, a requisição é finalizada e retorna status-code 500, porém sem corpo nenhum.

  • Maximum Request Size: tamanho máximo do payload (em MB). O limite máximo do payload configurável é de 5MB. 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"
}

  • Response Headers: 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 possiveis falhas em proxys e gateways.

  • Add Cross-Origin Resource Sharing (CORS) - CORS Headers: adicione os CORS headers a serem retornados pelo endpoint quando o processamento no pipeline terminar. O Cross-Origin Resource Sharing (CORS) é um mecanismo que permite informar ao navegador quais origens tem a permissão para fazer requisições. Este parâmetro define o CORS especificamente ao pipeline e suas restrições. Para configurar de forma global ao invés de individualmente em cada pipeline consulte o artigo CORS Global . Importante: Utilizamos a 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.

  • External API: se a opção estiver ativada, a API é publicada em um gateway externo.

  • Internal API: se a opção estiver ativada, a API é publicada em um gateway interno. Nesse caso, o IP interno é acessível apenas através da VPN dedicada ou do Pipeline Executor. O pipeline pode ter tanto a opção de External API quanto a Internal API habilitadas simultaneamente.

  • 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. Este parâmetro não suporta API Key e JWT. Para utilizá-lo no seu realm, é necessário fazer uma solicitação via chat e assim enviremos as informações necessárias para instalação deste serviço.

  • API Key: se a opção estiver ativada, o endpoint pode ser consumido apenas se for enviada uma chave de API previamente configurada na Plataforma. Existe um parâmetro de configuração global que obriga todos os pipelines a serem publicados apenas com a opção API Key habilitada. A única forma de desativar esse parâmetro é por solicitação via chat. A desativação pode ser realizada de 2 formas: para um único pipeline, sendo que você precisa enviar o nome dele, ou globalmente, que o desativará para todos os pipelines do seu Realm.

  • 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.

  • Additional API Routes: se a opção estiver ativada, o trigger permite que você configure novas rotas. Veja mais sobre esse parâmetro abaixo.

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

  • 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.

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:

ou

  • {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 }}

Adding Response Headers

Conforme explicado anteriormente, essa opção serve para configurar headers na resposta do endpoint.

IMPORTANTE: Não utilizar caracteres especiais.

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

{{ message.parameter }}

REST 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 JSON

Observe como configurar um pipeline com o REST Trigger para retornar uma informação de dentro do pipeline em formato JSON 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.

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


IMPORTANTE: 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
}
]
}
}

Feito isso, o endpoint já retornará automaticamente o JSON que definimos acima como resposta do endpoint.

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, e o corpo da resposta deve ter a mesma aparência do JSON que previamente definimos dentro do conector MOCK.

  • API de envio de informações com retorno em JSON

Observe como configurar um pipeline com o REST Trigger para retornar uma informação de dentro do pipeline em formato JSON 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 POST.

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

IMPORTANTE: 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 modifique os dados recebidos e que o endpoint retornará 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
},
{{ message.body.product }}
]
}
}

Com isso configurado, um payload com um novo produto será recebido e esse será adicionado ao array. Após isso, o pipeline retornará para o consumidor o array com o novo produto adicionado.

Após a implantação, pegue a url gerada e envie uma requisição do tipo POST com o seguinte body:

{
"product": {
"name": "Samsung galaxy note 10 256GB",
"price": 2879.99
}
}

O endpoint deve retornar o status-code 200, e o corpo da resposta deve ter a seguinte aparência:

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

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": "{}",
"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/json",
"path": "/pipeline/digibee/v1/trigger-rest/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 desse campo

  • path: o path utilizado na URL no request é repassado nesse campo.

  • absoluteURI: a URI absoluta da requisição é passada nesse campo


Respondeu à sua pergunta?