REST V2

Descubra mais sobre o conector 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 conector. 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. Este parâmetro suporta Double Braces, mas a referência a informações de conta não é permitida.	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. No entanto, a referência a informações da conta é permitida apenas para os campos de value.	Content-Type : application/json	Pares de chave-valor
Query Params `(DB)`	Configura os query parameters necessários para a chamada. Este parâmetro suporta Double Braces apenas para campos de value.	N/A	Pares de chave-valor
Verb	Especifica o verbo que indica o método HTTP.	GET	String
Account	Conta a ser utilizada pelo conector. Contas suportadas: ApiKey, AWS v4, Basic, Certificate Chain, Custom Auth Header, Google Key, Oauth2, Oauth Bearer Token e NTLM.	N/A	String
Custom Account #1	Conta adicional a ser utilizada pelo conector por meio de Double Braces _{{ account.custom-1.value }}.	N/A	String
Custom Account #2	Conta adicional a ser utilizada pelo conector 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). Este parâmetro suporta Double Braces, mas a referência a informações de conta não é permitida.	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 conector 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 conector 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. Este parâmetro suporta Double Braces, mas a referência a informações de conta não é permitida.

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. No entanto, a referência a informações da conta é permitida apenas para os campos de value.

Content-Type : application/json

Pares de chave-valor

Query Params (DB)

Configura os query parameters necessários para a chamada. Este parâmetro suporta Double Braces apenas para campos de value.

N/A

Pares de chave-valor

Verb

Especifica o verbo que indica o método HTTP.

GET

String

Account

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

N/A

String

Custom Account #1

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

N/A

String

Custom Account #2

Conta adicional a ser utilizada pelo conector 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). Este parâmetro suporta Double Braces, mas a referência a informações de conta não é permitida.

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

(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 conector

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

Usando contas

No REST V2, você pode configurar três tipos de parâmetros de conta:

Account
Custom Account #1
Custom Account #2

A diferença entre os parâmetros é que se você definir o parâmetro Account, o conector irá automaticamente preparar a requisição com as informações da conta, de acordo com a tecnologia de autenticação. No entanto, se você configurar uma ou mais Custom Accounts, elas só poderão ser usadas para referenciar suas informações em outros campos através de Double Braces.

O parâmetro Account sempre tem precedência sobre Custom Accounts.

Estes são os tipos de contas suportados no REST V2:

API Key
AWS V4
Basic
Certificate Chain
Custom Auth Header
Google Key
OAuth2
OAuth Bearer Token
NTLM

Saiba mais sobre como o REST V2 prepara a autorização dependendo do tipo de conta:

API Key

Com os valores URL-PARAM-NAME e API-KEY definidos no tipo de conta API Key, a Plataforma adiciona um novo conjunto de parâmetros de consulta e valores na requisição da seguinte forma:

https://www.address.com?<URL-PARAM-NAME>=<API-KEY>

AWS V4

Se você precisar acessar um serviço AWS através de uma chamada de API REST, é necessário usar este tipo de conta. Internamente, a plataforma gera os cabeçalhos de autenticação da AWS e assina a mensagem com a assinatura AWS 4.

Verifique a documentação do serviço AWS que você deseja acessar para ver quais cabeçalhos ou parâmetros adicionais precisam ser configurados para a chamada de API REST.

Basic

Se USERNAME e PASSWORD estiverem definidos no tipo de conta Basic, a Plataforma codifica os dados em formato BASE64 e adiciona um cabeçalho de autorização à requisição da seguinte forma:

Authorization: Basic <ENCODED-INFORMATION>

Certificate Chain

Quando este tipo de conta é definido, a Plataforma usa o CHAIN para validar e estabelecer uma conexão segura com o servidor da API.

Custom Auth Header

Com HEADER-NAME e HEADER-VALUE definidos no tipo de conta Custom Auth Header, a Plataforma cria um cabeçalho personalizado e o insere na requisição da seguinte forma:

<HEADER-NAME>: <HEADER-VALUE>

Google Key

Se você precisar acessar um serviço do Google através de uma chamada de API REST, é necessário usar este tipo de conta. Internamente, a plataforma gera o Google Authentication Token e o insere em um cabeçalho de autenticação da seguinte forma:

Authorization: Bearer <GOOGLE-JWT-TOKEN>

Verifique a documentação do serviço do Google que você deseja acessar para ver quais cabeçalhos ou parâmetros adicionais precisam ser configurados para a chamada de API REST.

OAuth 2

Este tipo de conta aciona diferentes comportamentos dependendo do que o respectivo provedor espera. Veja como a Plataforma lida com a autenticação OAuth 2 com os provedores suportados pela Digibee:

Microsoft e Google: para esses provedores, a Plataforma gera o access token e o insere em um cabeçalho de autorização da seguinte forma: Authorization: Bearer <PROVIDER_ACCESS_TOKEN>
Mercado Livre: para este provedor, a Plataforma gera o access token e o insere como o valor de um parâmetro de consulta na requisição, da seguinte forma: https://www.address.com?access_token=<API-KEY>

OAuth Bearer Token

Se você já tiver um token OAuth, pode armazená-lo neste tipo de conta e a Plataforma o criará da seguinte forma e o substituirá em um cabeçalho de Autorização:

Authorization: Bearer <TOKEN>

Mais informações podem ser encontradas na documentação de Contas.

AnteriorEmail V1: Exemplos de uso (Descontinuado)PróximoREST V1 (Descontinuado)

Atualizado há 5 meses