# 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 | {% hint style="info" %} O comportamento de **PUT**, **PATCH** e **DELETE** segue a semântica padrão utilizada em APIs REST. {% endhint %} ## 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: ```json {{ params.param_name }} {{ table.table_name.column_name }} ``` **Exemplo:** ``` https://api.example.com/users/{{user_id}}/posts?status={{status}} ``` {% hint style="info" %} Os parâmetros da URL são resolvidos automaticamente em tempo de execução. {% endhint %} ### 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 {% hint style="info" %} Para requisições do tipo **POST**,**PUT** e **PATCH,** você pode definir o corpo {% endhint %} **Exemplo de corpo usando dados de uma tabela:** ```json { "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 {% hint style="info" %} Especialmente indicado para **POST**, **PUT** e **PATCH**. {% endhint %} #### 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:** ```json { "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: ```json { "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) {% hint style="info" %} O modo bulk altera apenas a forma de envio dos dados, não o parsing da resposta. {% endhint %} ### 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:** ```json [ { "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:** ```json { "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 {% hint style="info" %} O schema é aplicado linha a linha, mesmo em modo bulk {% endhint %} | 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gaiodataos.com/gaio-dataos-portuguese/tools/tarefas/etl/rest.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.