REST V2

Descubra mais sobre o componente REST V2 e saiba como utilizá-lo na Digibee Integration Platform.

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.

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
URL `(DB)`	Endereço que receberá a chamada HTTP.	https://viacep.com.br/ws/{{ DEFAULT(message.$.cep, "04547-130") }}/json/	String
Headers `(DB)`	Configura todos os tipos de headers necessários para chamada, por exemplo: Content-Type: application/json ou multipart/form-data. Esse parâmetro suporta Double Braces para os campos key e value.	Content-Type : application/json	Pares de chave-valor
Query Params `(DB)`	Configura os query parameters necessários para a chamada.	N/A	Pares de chave-valor
Verb	Especifica o verbo que indica o método HTTP.	GET	String
Account	Conta a ser utilizada pelo componente. Contas suportadas: ApiKey, AWS v4, Basic, Certificate Chain, Custom Auth Header, Google Key, Oauth2 e Oauth Bearer Token.	N/A	String
Custom Account #1	Conta adicional a ser utilizada pelo componente por meio de Double Braces _{{ account.custom-1.value }}.	N/A	String
Custom Account #2	Conta adicional a ser utilizada pelo componente por meio de Double Braces {{ account.custom-2.value }}.	N/A	String
Connect Timeout	Tempo de expiração da conexão (em milissegundos).	30000	Inteiro
Read Timeout	Tempo máximo para leitura (em milissegundos).	30000	Inteiro
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.	False	Booleano
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.	False	Booleano
Advanced Settings	Configurações avançadas.	False	Booleano
Raw Mode	Se ativada, a opção recebe ou passa um payload que não é JSON.	False	Booleano
Raw Mode As Base64	Quando ativada, a opção mostra o retorno como base64.	False	Booleano
Save As Local File	Quando ativada, a opção salva o retorno como um arquivo no diretório local do pipeline.	False	Booleano
Response File Name `(DB)`	Nome do arquivo ou caminho completo do arquivo (por exemplo, tmp/processed/file.txt).	N/A	String
Allow Insecure Endpoints	Quando ativada, a opção permite que chamadas a endpoints HTTPS não seguros sejam realizadas.	False	Booleano
Enable Retries	Quando ativada, a opção permite que sejam feitas novas tentativas.	False	Booleano
Number Of Retries	Número máximo de tentativas antes de desistir da chamada.	0	Inteiro
Time To Wait Between Retries	Tempo máximo entre tentativas (em milissegundos).	0	Inteiro
Compress Body With GZIP	Quando ativada, a opção permite que o body seja comprimido com GZIP.	False	Booleano
Force HTTP 1.1	Quando ativada, a opção força a solicitação a ser executada utilizando HTTP 1.1.	False	Booleano
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.	False	Booleano
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).	UTF-8	String
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.	False	Booleano
Invalidate SSL Sessions on Every Call	Quando ativada, a opção invalida sessões SSL em todas as chamadas.	False	Booleano
Use Dynamic Account	Quando a opção estiver ativada, o componente irá usar a conta dinamicamente. Quando estiver desativada, a conta será usada estaticamente.	False	Booleano
Account Name	Nome da conta a ser definida. O nome da conta deve ser gerado dinamicamente através do componente Store Account.	N/A	String
Scoped	Quando a opção estiver ativada, a conta armazenada é isolada para outro sub-processo. Nesse caso, os sub-processos verão sua própria versão dos dados da conta armazenada. Essa opção não é suportada para contas usadas em headers ou body. Para saber mais sobre a funcionalidade Scoped, leia a documentação de Suporte a credenciais dinâmicas.	False	Booleano

URL (DB)

Endereço que receberá a chamada HTTP.

https://viacep.com.br/ws/{{ DEFAULT(message.$.cep, "04547-130") }}/json/

String

Headers (DB)

Configura todos os tipos de headers necessários para chamada, por exemplo: Content-Type: application/json ou multipart/form-data. Esse parâmetro suporta Double Braces para os campos key e value.

Content-Type : application/json

Pares de chave-valor

Query Params (DB)

Configura os query parameters necessários para a chamada.

N/A

Pares de chave-valor

Verb

Especifica o verbo que indica o método HTTP.

GET

String

Account

Conta a ser utilizada pelo componente. Contas suportadas: ApiKey, AWS v4, Basic, Certificate Chain, Custom Auth Header, Google Key, Oauth2 e Oauth Bearer Token.

N/A

String

Custom Account #1

Conta adicional a ser utilizada pelo componente por meio de Double Braces _{{ account.custom-1.value }}.

N/A

String

Custom Account #2

Conta adicional a ser utilizada pelo componente por meio de Double Braces {{ account.custom-2.value }}.

N/A

String

Connect Timeout

Tempo de expiração da conexão (em milissegundos).

30000

Inteiro

Read Timeout

Tempo máximo para leitura (em milissegundos).

30000

Inteiro

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.

False

Booleano

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.

False

Booleano

Advanced Settings

Configurações avançadas.

False

Booleano

Raw Mode

Se ativada, a opção recebe ou passa um payload que não é JSON.

False

Booleano

Raw Mode As Base64

Quando ativada, a opção mostra o retorno como base64.

False

Booleano

Save As Local File

Quando ativada, a opção salva o retorno como um arquivo no diretório local do pipeline.

False

Booleano

Response File Name (DB)

Nome do arquivo ou caminho completo do arquivo (por exemplo, tmp/processed/file.txt).

N/A

String

Allow Insecure Endpoints

Quando ativada, a opção permite que chamadas a endpoints HTTPS não seguros sejam realizadas.

False

Booleano

Enable Retries

Quando ativada, a opção permite que sejam feitas novas tentativas.

False

Booleano

Number Of Retries

Número máximo de tentativas antes de desistir da chamada.

Inteiro

Time To Wait Between Retries

Tempo máximo entre tentativas (em milissegundos).

Inteiro

Compress Body With GZIP

Quando ativada, a opção permite que o body seja comprimido com GZIP.

False

Booleano

Force HTTP 1.1

Quando ativada, a opção força a solicitação a ser executada utilizando HTTP 1.1.

False

Booleano

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.

False

Booleano

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

UTF-8

String

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.

False

Booleano

Invalidate SSL Sessions on Every Call

Quando ativada, a opção invalida sessões SSL em todas as chamadas.

False

Booleano

Use Dynamic Account

Quando a opção estiver ativada, o componente irá usar a conta dinamicamente. Quando estiver desativada, a conta será usada estaticamente.

False

Booleano

Account Name

Nome da conta a ser definida. O nome da conta deve ser gerado dinamicamente através do componente Store Account.

N/A

String

Scoped

Quando a opção estiver ativada, a conta armazenada é isolada para outro sub-processo. Nesse caso, os sub-processos verão sua própria versão dos dados da conta armazenada. Essa opção não é suportada para contas usadas em headers ou body. Para saber mais sobre a funcionalidade Scoped, leia a documentação de Suporte a credenciais dinâmicas.

False

Booleano

Atualmente, os parâmetros Use Dynamic Account, Account Name e Scoped podem ser usados apenas no Pipeline Engine v2 e estão disponíveis em fase Beta Restrito. Para saber mais, leia o artigo Progama Beta.

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

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

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:

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 (Contas), leia nossa documentação.

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.

Para usar 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, acesse 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.

PreviousEmail V1: Exemplos de uso (Descontinuado)NextREST V1 (Descontinuado)

Last updated 4 months ago