REST

A REST Task no Gaio DataOS permite conectar-se a qualquer API externa — pública ou privada — diretamente dentro do seu fluxo de dados. Ela pode ser utilizada para buscar dados, enviar informações, automatizar integrações via API, converter respostas JSON em tabelas utilizáveis no projeto e integrar IA, analytics e workflows com serviços externos.

---

Métodos HTTP suportados

A REST Task suporta os seguintes métodos HTTP:

Metódo
GET	Obter dados
POST	Enviar dados/Criar recursos
PUT	Substituir recursos
PATCH	Parcialmente atualizar recursos
DELETE	Remover recursos

O comportamento de PUT, PATCH e DELETE segue a semântica padrão utilizada em APIs REST.

Como usar a REST

1. Abrir a REST

No Studio, acesse o painel Tasks. Na seção ETL, selecione REST.

---

2. Escolher o método e configurar a URL

• Selecione o método HTTP: GET, POST, PUT, DELETE, etc.

• No campo URL, informe o endpoint da API.

É possível utilizar parâmetros dinâmicos na URL:

{{ params.param_name }}
{{ table.table_name.column_name }}

Exemplo:

https://api.example.com/users/{{user_id}}/posts?status={{status}}

Os parâmetros da URL são resolvidos automaticamente em tempo de execução.

3. Adicionar parâmetros

Na aba Parâmetros, defina parâmetros de URL:

• URL Parâmetro: Nome do parâmetro (ex.: userId)

• Valor: Valor estático ou dinâmico (ex.: {{ param.user_id }})

Clique em + Adicionar Parâmetro para adicionar novos parâmetros.

---

4. Definir o corpo da requisição (Body), se necessário

Na aba Corpo, você pode:

• Inserir conteúdo JSON para o corpo da requisição (principalmente em POST e PUT)

• Utilizar variáveis dinâmicas dentro do conteúdo

Para requisições do tipo POST,PUT e PATCH, você pode definir o corpo

Exemplo de corpo usando dados de uma tabela:

{
  "id": "{{ table.sales_rest.sale_id }}",
  "product": "{{ table.sales_rest.product }}"
}

Enviar todos os dados da tabela em lote

• Habilitar: envia toda a tabela em uma única requisição

• Desabilitar: envia uma requisição por linha

Isso é útil para:

• Inserções em massa

• Atualizações em lote

• Integrações de alta performance

---

5. Headers e autorização

• Cabeçalhos: adicione headers customizados como Authorization, Content-Type, Accept, Bearer Tokens, etc.

• Autorizações: configure autenticação Basic Auth, quando necessário.

---

6. Aba Resultado

Controla como a resposta da API será interpretada e convertida em tabela.

• Identificação da estrutura: Permite que o Gaio detecte automaticamente nomes de colunas e tipos de dados (padrão: Automatic).

• Propriedade do objeto: Define o caminho até o array dentro do JSON de resposta, caso seja aninhado (ex.: results.items).

• Sempre excluir tabela: Se habilitado, a tabela de resultado existente será substituída a cada execução.

• Colunas de entrada para manter: Seleciona quais colunas da resposta devem ser armazenadas.

• Propriedade do objeto que contém os resultados retornados: Define a propriedade JSON que contém a lista de resultados.

Comportamento:

• Se a API retornar um objeto JSON → uma linha será criada

• Se retornar um array JSON → cada item será inserido como uma linha separada

---

7. Aba Error Log

Permite capturar e armazenar erros ocorridos durante a execução.

• Tabela de log: Nome da tabela que receberá os logs de erro da REST. (ex.: log_api_errors)

Facilita depuração e monitoramento em ambientes produtivos.

REST Task · Bulk Mode

O REST Bulk Mode estende a REST Task padrão, permitindo requisições orientadas a lote. Em vez de enviar uma requisição por linha, os dados da tabela são agregados e enviados em blocos para a API externa. Ideal para integrações de alto volume, inserções em massa e fluxos otimizados para performance.

Quando usar REST Bulk

Use REST Bulk quando:

• A API suporta payloads em lote

• Você deseja reduzir o número de requisições HTTP

• Precisa enviar grandes volumes de dados de forma eficiente

• Está sincronizando tabelas com sistemas externos

Especialmente indicado para POST, PUT e PATCH.

Configuração do Bulk

As configurações de bulk ficam na aba Body e incluem:

• Controle de execução em lote

• Paginação sobre os dados da tabela

• Definição opcional de schema para o payload

---

Habilitar Bulk Mode

Ative Send all table data in a single batch.

Quando habilitado:

• A REST Task envia múltiplas linhas juntas

• O payload é construído a partir da tabela de origem

• A execução é otimizada para maior throughput

---

Batch Size (Paginação da tabela)

Define quantas linhas são enviadas por requisição:

• Valor numérico: número de linhas por lote

• 0: carrega e envia a tabela inteira em uma única requisição

---

Body Payload (Bulk)

O editor de Body define como os dados em lote são enviados.

Exemplo:

{
  "data": {{ table.sales_rest }}
}

Neste caso:

• table.sales_rest é resolvido como um array de linhas

• Cada lote injeta um subconjunto da tabela

• A API recebe uma lista estruturada de registros

Padrão comum para APIs que esperam:

{
  "data": [
    { ... },
    { ... }
  ]
}

---

Comportamento em tempo de execução (Bulk)

Durante a execução:

1. A task lê a tabela de origem

2. Divide os dados conforme o tamanho do lote

3. Injeta cada lote no body da requisição

4. Envia uma requisição por lote

5. Processa as respostas da API

6. Grava os resultados na tabela configurada

---

Relação com métodos HTTP

• POST: criação em lote

• PUT: substituição em lote

• PATCH: atualização em lote

• DELETE: exclusão em lote (dependente da API)

O modo bulk altera apenas a forma de envio dos dados, não o parsing da resposta.

REST Bulk at Root

O REST Bulk at Root é uma variação do modo Bulk onde os dados da tabela são enviados diretamente na raiz do body da requisição, sem um wrapper (como { data: [...] }).

---

Quando usar Bulk at Root

Use quando:

• A API espera um array JSON na raiz

• Nenhuma propriedade intermediária é permitida

• A API é estrita quanto ao formato do payload

Exemplo esperado pela API:

[
  { "id": 1, "product": "A" },
  { "id": 2, "product": "B" }
]

Exemplo de Body (Bulk at Root):

{{ table.sales_rest }}

REST Bulk With Schema

O REST Bulk With Schema permite definir explicitamente a estrutura de cada registro antes do envio à API externa.

Em vez de enviar linhas brutas da tabela, você define um schema customizado que controla:

• Quais campos são enviados

• Como os campos são nomeados

• Como as colunas da tabela são mapeadas no payload

Ideal para APIs com contratos rígidos.

---

Quando usar Bulk With Schema

Use quando:

• A API exige uma estrutura JSON específica

• Os nomes das colunas não coincidem com os nomes esperados pela API

• É necessário omitir ou renomear campos

• Você precisa de controle total sobre o payload

---

Como funciona o Bulk With Schema

Esse modo introduz duas camadas:

• Schema: define a estrutura de um único registro

• Body template: define como os registros são agrupados e enviados

O sistema aplica o schema dinamicamente a cada linha.

Exemplo de schema:

{
  "id": "{{ table.sales_rest.sale_id }}",
  "product": "{{ table.sales_rest.product }}"
}

Isso significa que:

• Cada linha de sales_rest é transformada nesse formato

• Apenas os campos mapeados são enviados

O schema é aplicado linha a linha, mesmo em modo bulk

Modo	Estrutura típica
Rest Bulk	{ "data": {{ table }} }
Rest Bulk at Root	{{ table }}
Rest Bul With Schema	{ "data": {{ schema }} }

---

Boas práticas

• Sempre utilize Executar teste antes de finalizar a configuração

• Use POST / PUT / PATCH para operações de mutação

• Utilize parâmetros dinâmicos para reaproveitar a mesma task

• Use batch mode para APIs de alto volume

• Em JSONs aninhados, defina corretamente o Object Property

• Ative a aba Error Log para rastrear falhas

• Valide as respostas da API antes de usá-las em etapas posteriores