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