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

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

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:

https://www.address.com

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:

https://www.address.com

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:

https://www.address.com

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

https://www.address.com

HEADERS

Authorization: Bearer <ACCESS_TOKEN>

Mercado Livre

https://www.address.com?access_token=<ACCESS_TOKEN>

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.

Encontrou sua resposta?