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 nos parâmetros de configuração do conector. Parâmetros suportados por expressões Double Braces estão marcados com (DB).

Aba Section Rest Connector V2

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

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. Este parâmetro fica disponível apenas se o parâmetro Use Dynamic Account estiver ativo.

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. Este parâmetro fica disponível apenas se o parâmetro Use Dynamic Account estiver ativo. Para saber mais sobre a funcionalidade Scoped, leia a documentação de Suporte a credenciais dinâmicas.

False

Booleano

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 máximo para estabelecer uma conexão com o servidor. Começa a contar ao tentar se conectar (DNS + handshake TCP + TLS, se aplicável). Saiba mais.

30000

Inteiro

Read Timeout

Tempo máximo de espera para ler dados do servidor (após a conexão ser estabelecida). Começa a contar após o envio da requisição, enquanto aguarda a resposta. Saiba mais.

30000

Inteiro

Write Timeout

Tempo máximo para enviar dados da requisição para o servidor, em milissegundos. Começa a contar durante o envio do corpo da requisição. Saiba mais.

30000

Inteiro

Call Timeout

Tempo total permitido para a requisição inteira (conexão, escrita, leitura), em milissegundos. Começa a contar desde o início até o fim de toda a chamada HTTP. Saiba mais.

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

Enable Follow Redirect

Quando ativado, a execução do pipeline seguirá automaticamente os redirecionamentos para respostas 302. Caso contrário, a resposta original com status 302 será retornada, permitindo a inspeção dos dados antes que o redirecionamento seja seguido.

True

Booleano

Atualmente, os parâmetros Use Dynamic Account, Account Name e Scoped podem ser usados apenas no Pipeline Engine v2.

Aba Documentation

Parâmetro

Descrição

Valor padrão

Tipo de dado

Documentation

Seção para documentar qualquer informação necessária sobre a configuração do conector e regras de negócio.

N/A

String

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: "content in base64 format",
    headers: {}
}

em caso de sucesso (com a utilização da flag “Save As Local File”)

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {
        file: "name of the file defined in the Response File Name property"
    },
    headers: {}
}

em caso de erro

{
    error: "error message",
    code: XXX,
    body: {},
    headers: {}
}

REST V2 em Ação

Configurando os timeouts

Connect Timeout

Define o tempo máximo permitido para estabelecer uma conexão com o servidor.

Se o servidor estiver lento para aceitar a conexão ou indisponível, a requisição falhará após esse tempo.

Exemplo: O servidor demora mais de 10 segundos para completar o handshake. A conexão falha por timeout.

Read Timeout

Especifica o tempo máximo para aguardar uma resposta após o envio da requisição.

Evita que o cliente fique esperando indefinidamente por dados.

Exemplo: O servidor aceitou a conexão, mas demora mais de 15 segundos para começar a responder. Um erro de timeout é retornado.

Write Timeout

Define o tempo máximo permitido para enviar o corpo da requisição ao servidor.

Especialmente relevante para requisições com payloads grandes (por exemplo, uploads de arquivos).

Exemplo: O upload de um arquivo leva mais de 30 segundos. A requisição falha por timeout na escrita.

Call Timeout

Define o timeout total para toda a chamada HTTP, incluindo conexão, envio e recebimento.

Se a soma dos tempos ultrapassar esse valor, a requisição é abortada.

Exemplo: Você configura um timeout de 60 segundos para toda a operação. Se conectar, enviar e receber juntos ultrapassarem esse limite, a requisição é cancelada.

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á 27 dias

Isto foi útil?