IMPORTANTE: esta documentação foi descontinuada. Leia a documentação REST V2 atualizada no nosso novo portal de documentação.
O REST V2 realiza chamadas a endpoints de HTTP, tornando muito simples ações como GET, POST, PUT e DELETE.
A grande diferença para a V1 é a adoção de expressões em Double Braces para compor URL, headers, query parameters e corpo da mensagem, permitindo acesso direto aos dados do pipeline.
Dê uma olhada nos parâmetros de configuração do componente:
URL: endereço que receberá a chamada HTTP.
Headers: configura todos os tipos de headers necessários para chamada (ex.: Content-Type: application/json ou multipart/form-data).
Query Params: configura os query parameters necessários para a chamada.
Verb: especifica o verbo que indica o método HTTP.
Account: conta a ser utilizada pelo componente.
Custom Account #1: conta adicional a ser utilizada pelo componente por meio de Double Braces {{ account.custom-1.value }}. Clique aqui para ler o nosso artigo sobre o tema.
Custom Account #2: conta adicional a ser utilizada pelo componente por meio de Double Braces {{ account.custom-2.value }}. Clique aqui para ler o nosso artigo sobre o tema.
Connect Timeout: tempo de expiração da conexão (em milissegundos).
Read Timeout: tempo máximo para leitura (em milissegundos).
Stop On Client Error: se ativada, a opção interrompe a execução do pipeline quando ocorre um erro HTTP da família 4xx na chamada ao endpoint.
Stop On Server Error: se ativada, a opção interrompe a execução do pipeline quando ocorre um erro HTTP da família 5xx na chamada ao endpoint.
Advanced Settings: configurações avançadas.
Raw Mode: se ativada, a opção recebe ou passa um payload que não é JSON.
Raw Mode As Base64: quando ativada, a opção mostra o retorno como base64.
Save As Local File: quando ativada, a opção salva o retorno como um arquivo no diretório local do pipeline.
Response File Name: nome do arquivo ou caminho completo do arquivo (ex.: tmp/processed/file.txt). Double Braces são suportados.
Allow Insecure Endpoints: quando ativada, a opção permite que chamadas a endpoints HTTPS não seguros sejam realizadas.
Enable Retries: quanto ativada, a opção permite que sejam feitas novas tentativas.
Number Of Retries: número máximo de tentativas antes de desistir da chamada.
Time To Wait Between Retries: tempo máximo entre tentativas (em milissegundos).
Compress Body With GZIP: quanto ativada, a opção permite que o body seja comprimido com GZIP.
Force HTTP 1.1: quando ativada, a opção força a solicitação a ser executada utilizando HTTP 1.1.
Override Response Charset: quando ativada, a opção irá sobrescrever o charset retornado do endpoint para o charset especificado na propriedade “Response Charset”; do contrário, o retorno do charset no header “Content-Type” será respeitado. Se nenhum charset no header “Content-Type” for retornado, será utilizado o padrão UTF-8.
Response Charset: utilizado somente quando a opção “Override Response Charset” estiver ativada, forçará o uso do charset especificado na propriedade (Padrão: UTF-8).
Disable Connection Pooling: quando ativada, a opção não mantém as conexões em um pool. O seu uso é recomendado para endpoints que apresentam problemas de compatibilidade quando conexões são reutilizadas.
Invalidate SSL Sessions on Every Call: quando ativada, a opção invalida sessões SSL em todas as chamadas. O seu uso é recomendado para endpoints que apresentam problemas de compatibilidade quando sessões SSL são reutilizadas (ex.: retomada de sessão SSL). Leve em consideração que ativar a opção fará com que o componente tenha um thread único - isso significa que todas as execuções serão sequenciais para o mesmo REST adicionado ao pipeline canvas.
IMPORTANTE: note que alguns dos parâmetros acima suportam Double Braces. Para entender como essa linguagem funciona, leia o nosso artigo clicando aqui.
Fluxo de Mensagens
Entrada
Você pode usar a seguinte configuração no corpo da mensagem e pode fazer uso dela através de Double Braces:
{
"id": {{ DEFAULT(message.customer.id, UUID()) }},
"name": {{ message.customer.name }},
"type": "1"
}
IMPORTANTE: não se aplica ao verbo GET.
Saída
em caso de sucesso
{
status: 2xx,
statusMessage: "STATUS_MESSAGE",
body: {
},
headers: {
}
}
em caso de sucesso (com a utilização da flag "Raw Mode As Base64")
{
status: 2xx,
statusMessage: "STATUS_MESSAGE",
body: "conteúdo em formato de bas64",
headers: {
}
}
em caso de sucesso (com a utilização da flag “Save As Local File”)
{
status: 2xx,
statusMessage: "STATUS_MESSAGE",
body: {
file: "nome do arquivo definido na propriedade Response File Name"
},
headers: {
}
}
em caso de erro
{
error: "error message",
code: XXX,
body: {
},
headers: {
},
errorMessage: "Esta propriedade será exibida sempre que o corpo do retorno da requisição não estiver no formato JSON. Irá conter mensagem de erro de conversão e o corpo original do retorno da requisição."
}
REST V2 em Ação
Enviando um arquivo binário
Para enviar um arquivo binário pelo REST V2, basta informar:
o endpoint de destino
o content type (MIME Type do arquivo) no header (ex.: application/pdf)
o caminho onde o arquivo se encontra (apontar no campo File Name)
Como fazer requisições utilizando o content-type: MultiPart/form-data
A primeira coisa que você precisa fazer é especificar esse header no componente (Content-Type: Multipart/form-data).
Em seguida, depois de selecionar qualquer verbo HTTP (com exceção do GET), um campo vai se abrir para que você especifique o corpo do payload a ser enviado. Este deve ser o padrão para:
especificar campos
{
"fields": {
"nome_do_campo1": "valor_do_campo_1",
"nome_do_campo2": "valor_do_campo_2",
…….
}
}
especificar arquivos
{
"files": {
"nome_do_campo_do_arquivo1": "caminho_que_se_encontra_o_arquivo1",
"nome_do_campo_do_arquivo2": "caminho_que_se_encontra_o_arquivo2",
…..
}
}
Caso precise de ambas as especificações, você pode combiná-las com expressões em Double Braces:
{
"files": {
"file": {{ message.fileName }},
"file2": {{ message.fileName2 }}
},
"fields": {
"nome": {{ message.name }},
"'endereço": {{ message.endereco }}
}
}
Como fazer requisições utilizando o content-type: application/x-www-form-urlencoded
A primeira coisa que você precisa fazer é especificar esse header no componente (Content-Type: application/x-www-form-urlencoded).
Em seguida, depois de selecionar qualquer verbo HTTP (com exceção do GET), um campo vai se abrir para que você especifique o corpo do payload a ser enviado.
Exemplo:
{ "nome_do_campo1": {{ message.campo1}}, "nome_do_campo2": {{ message.campo2}} }
Utilização de accounts
Veja quais são as accounts suportadas pelo REST V2:
APIKEY
Com o URL-PARAM-NAME e o API-KEY definidos na conta tipo Basic, a Plataforma faz a substituição na chamada da seguinte maneira:
https://www.address.com?<URL-PARAM-NAME>=<API-KEY>
BASIC
Com o USERNAME e o PASSWORD definidos na conta tipo Basic, a Plataforma faz a substituição na chamada da seguinte maneira:
HEADERS
Authorization: Basic BASE64(<USERNAME>:<PASSWORD>)
CUSTOM_AUTH_HEADER
Com o HEADER-NAME e o HEADER-VALUE definidos na conta tipo CUSTOM_AUTH_HEADER, a Plataforma faz a substituição na chamada da seguinte maneira:
HEADERS
<HEADER-NAME>: <HEADER-VALUE>
OAUTH_BEARER_TOKEN
Caso você já tenha um token OAUTH, você pode salvá-lo nesse tipo de conta e a Plataforma faz a substituição na chamada da seguinte maneira:
HEADERS
Authorization: Bearer <TOKEN>
OAUTH_2
É específico de cada tipo de provedor suportado. Com essa conta, o access token é passado da forma que cada provider espera.
Microsoft e Google
HEADERS
Authorization: Bearer <ACCESS_TOKEN>
Mercado Livre
Para ter uma visão geral sobre a utilização de accounts, clique aqui e acesse o nosso outro artigo.
GOOGLE_KEY
Você pode recorrer à essa conta caso seja necessário utilizar uma chave para autenticação no serviço Google.
Para ter uma visão geral sobre a utilização de accounts, clique aqui e acesse o nosso outro artigo.
AWS_4
Para você acessar algum serviço da AWS via REST, será necessário utilizar esse tipo de conta. Com ela, o componente é responsável por gerar os headers de autenticação e assinar a mensagem. Para tornar isso possível, fazemos uso da assinatura AWS 4.
IMPORTANTE: para o DynamoDB, é necessário especificar o header:
X-Amz-Target = DynamoDB_20120810.GetItem
caso você queira buscar um item no banco de dados
X-Amz-Target = DynamoDB_20120810.PutItem
caso você queira fazer inserção de dados
Clique aqui para acessar a documentação da AWS e saber qual header especificar no uso do DynamoDB.
Para os demais serviços da AWS é necessário verificar se o header X-Amz-Content-Sha256 é obrigatório. Nesse caso, você precisa informar no header do componente o valor “required”:
X-Amz-Content-Sha256 = required
E se for preciso utilizar mais de um tipo de account na mesma chamada, tire as suas dúvidas sobre o recurso de Double Braces custom account clicando aqui.