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