Buscar K
Aparência
Requisição HTTP
- Tipo
- Referência
- Para
- Engenharia de dados, Desenvolvedor
- Na tela
- HorusETL › Dataflows › editor do Dataflow › Configurar Requisição HTTP
O nó Requisição HTTP chama uma API, lê a resposta em JSON e devolve as linhas para o próximo nó. Ele percorre as páginas da resposta sozinho e pode repetir a chamada para cada linha que recebe de um nó anterior. No YAML, o kind é HTTPRequest.
A biblioteca de nós tem duas entradas para ele, no grupo Web & APIs: Requisição HTTP, sem entrada, e Requisição HTTP - Parametrizada, com uma entrada. É o mesmo nó; a entrada é o que habilita a aba Input Loop.
A configuração abre na janela Configurar Requisição HTTP, com as abas Requisição, Autenticação, Saída, Opções e Retry, mais Input Loop quando o nó tem entrada. Testar API roda a chamada sem salvar, e Importar cURL preenche a requisição a partir de um comando curl.
Requisição
| Na tela | No YAML (options) | Padrão | Regra |
|---|---|---|---|
| URL: | url | vazio | Obrigatória. Sem ela, o nó falha com "URL é obrigatória. Forneça uma URL válida nas configurações." |
| Método HTTP: | method | POST na tela; obrigatório no YAML | GET, POST, PUT, PATCH, DELETE, HEAD |
| Parâmetros de Query (URL): | payload.query[] (key, value) | nenhum | Entram codificados na URL. Parâmetro de paginação com o mesmo nome substitui este |
| Cabeçalhos HTTP: | payload.headers[] (key, value) | nenhum | A autenticação sobrescreve um cabeçalho de mesmo nome |
| Tipo de Corpo: | payload.body.type | none | JSON (application/json) (json), Form (x-www-form-urlencoded) (formUrlEncoded), Raw (Texto/XML/Outro) (raw), Nenhum (none). A aba Corpo some em GET e HEAD |
| Conteúdo JSON: | payload.body.rawContent | {} | Validado antes do envio. JSON vazio ou inválido falha o nó |
| Campos do Formulário: | payload.body.formContent[] | nenhum | Lista vazia falha o nó |
| Content-Type: e Conteúdo: | payload.body.rawContentType, payload.body.rawContent | text/plain | text/plain, text/xml, application/xml, text/html, text/csv. Enviado em UTF-8 |
Autenticação
| Tipo de Autenticação: | No YAML | Campos | O que vai na chamada |
|---|---|---|---|
| Nenhuma | auth.type: none | nenhum | nada |
| Basic Auth | basic | Usuário: (auth.user), Senha: (auth.pass) | Authorization: Basic <base64 de usuario:senha> |
| Bearer Token | bearer | Token: (auth.token) | Authorization: Bearer <token> |
| API Key | apikey | Chave (Key): (auth.key), Valor: (auth.value), Adicionar em: (auth.addTo: header ou query; a tela começa em Header) | a chave num cabeçalho ou na query. No YAML sem auth.addTo, a chave não é enviada |
Não há OAuth2 no nó. Para API que exige login antes de cada consulta, gere o token num Configurador e use a variável no campo Token:.
Saída
| Na tela | No YAML | Padrão | Regra |
|---|---|---|---|
| Seletor de Dados (JSONPath): | output.dataPath | $.data na tela; vazio no YAML | Caminho até a lista de itens na resposta. Vazio lê a raiz. Precisa achar uma lista ou um objeto; se não achar nada, falha com "JSONPath '...' não retornou resultados na resposta." |
| Retornar Resposta Completa | output.returnFullResponse | desligado | Ignora o seletor e devolve uma linha por resposta, com as colunas STATUS, STATUS_TEXT, HEADERS e DATA (o corpo bruto) |
| Inferir Schema Automaticamente | schema.inferSchema | ligado | Monta as colunas a partir da primeira página |
| Colunas (Nome, Tipo, JSONPath) | schema.columns[] (name, type, jsonPath) | nenhuma | Só com a inferência desligada. Tipo Texto (string), Número (number) ou Data/Hora (datetime). O JSONPath é relativo a cada item e aceita só caminho com ponto ($.cliente.nome) |
Com a inferência ligada, as colunas são a união das chaves dos itens, em ordem alfabética. O nome perde acento, vai para maiúsculas, perde todo caractere fora de letra, número, espaço e hífen, é cortado em 45 caracteres e troca espaço por _. Por isso user_id vira USERID e first name vira FIRST_NAME. O tipo vem do primeiro valor não nulo em até 10 itens: número vira número, texto em formato ISO de data vira data, e o resto (booleano, objeto, lista) vira texto. Lista de valores simples vira uma coluna VALUE.
Coluna de nome manual sai exatamente como foi escrita, sem essa limpeza.
Paginação
Tipo de Paginação: (pagination.type) define como o nó pede a próxima página. Os campos ficam na janela Configurar Paginação, em pagination.config.
| Tipo | No YAML | Campos (padrão) | Para quando |
|---|---|---|---|
| Nenhuma | none | nenhum | depois da primeira chamada |
| Paginação por Página | page | Nome do Parâmetro de Página: pageParam (page), Nome do Parâmetro de Tamanho: pageSizeParam (per_page), Itens por Página: pageSize (100), Página Inicial: startPage (1), Máximo de Páginas: maxPages (100) | a condição de Parar quando: |
| Paginação por Offset | offset | Nome do Parâmetro de Offset: offsetParam (offset), Nome do Parâmetro de Limite: limitParam (limit), Tamanho do Limite: pageSize (100), Offset Inicial: startOffset (0), Máximo de Requisições: maxPages (100) | a condição de Parar quando: |
| Paginação por Cursor/URL | cursor | Localização do Cursor/URL: cursorLocation (Corpo da Resposta (JSONPath) ou Header da Resposta), JSONPath do Cursor/URL: ou Nome do Header: cursorPath, Máximo de Páginas: (100) | o cursor vem nulo ou some |
| Paginação por Cursor (Param) | cursor_param | Nome do Parâmetro de Cursor: cursorParam, JSONPath do Próximo Cursor: cursorPath, Valor Inicial do Cursor: startCursor, Máximo de Páginas: (100) | o cursor vem nulo, vazio ou "0" |
Nas paginações por página e por offset, Parar quando: (stopCondition) tem três opções:
| Opção | No YAML | Regra |
|---|---|---|
| Resposta (Data Path) Vazia | onEmpty | Padrão. Para quando o seletor de dados volta sem itens |
| Nº de Itens Menor que Tamanho da Página (no offset, Nº de Itens Menor que o Limite) | onLessThanPageSize | Para quando vem menos itens que o tamanho pedido |
| Total de Páginas na Primeira Resposta | onTotalPages | Lê o total de páginas na primeira resposta, pelo campo JSONPath para Total de Páginas: (totalPagesPath) |
O Máximo de Páginas: vale sempre: ao chegar nele, o nó para mesmo que a API tenha mais. No YAML sem maxPages, não há teto. Na paginação por Cursor/URL, o valor achado é a URL inteira da próxima chamada, e no modo cabeçalho o nó entende o cabeçalho Link com rel="next".
Opções
| Na tela | No YAML | Padrão | Regra |
|---|---|---|---|
| Timeout da Requisição (segundos): | settings.timeout | 30 | De 1 a 600 |
| Timeout de Conexão (segundos): | settings.connectTimeout | 10 | O Agente ETL ignora este campo e usa a configuração dele mesmo, de 10 s por padrão |
| Seguir Redirecionamentos (location) | settings.followRedirects | ligado | |
| Ignorar erros de certificado SSL (insecure) | settings.ignoreSsl | desligado | Aceita qualquer certificado. Use só em teste |
| Falhar nó se a requisição falhar (status ≥ 400) | settings.failOnError | ligado | Falha com qualquer status fora de 200 a 299, inclusive 3xx quando os redirecionamentos estão desligados. Desligado, o corpo do erro segue como se fosse dado |
Retry
| Na tela | No YAML | Padrão | Regra |
|---|---|---|---|
| Habilitar Retentativa Automática | retry.enabled | desligado | |
| Máximo de Tentativas: | retry.maxRetries | 3 | De 1 a 10. Conta as tentativas depois da primeira: com 3, são até 4 chamadas |
| Delay Inicial (segundos): | retry.delaySeconds | 2 | A espera dobra a cada falha, até 60 s |
| Estratégia de Backoff: | retry.strategy | fixed | O Agente ETL ignora este campo: a espera é sempre a que dobra |
O retry entra em qualquer falha da chamada: erro de rede, timeout e, com Falhar nó se a requisição falhar ligado, qualquer status fora de 2xx, inclusive 4xx.
Input Loop
A aba aparece quando o nó tem uma entrada ligada. Com o loop ligado, o nó faz uma chamada para cada linha da entrada.
| Na tela | No YAML | Padrão | Regra |
|---|---|---|---|
| Habilitar Input Loop | inputLoop.enabled | desligado | Desligado, a entrada é ignorada |
| Campo Fonte (Lista): | inputLoop.sourceField | vazio | Coluna da entrada que dá o valor de cada chamada |
| Nome do Parâmetro: | inputLoop.parameterName | vazio | O nome que vai entre ${...} |
| Campo de ID na Saída: e Habilitar | inputLoop.outputIdField, inputLoop.outputIdFieldEnabled | vazio, ligado | Acrescenta uma coluna de texto com o valor usado em cada chamada. Preencha o nome. No YAML sem outputIdField, a coluna se chama INPUT_PARAMETER_ID |
| Execução Paralela e Grau Máximo de Paralelismo: | inputLoop.parallelExecution, inputLoop.maxDegreeOfParallelism | desligado, 1 | Até 50 chamadas ao mesmo tempo |
${parametro} é trocado pelo valor da linha na URL, nos campos de autenticação, nos parâmetros de query, nos cabeçalhos e no corpo (JSON, raw e formulário). Não é trocado na paginação, no seletor de dados nem nas colunas.
text
https://api.exemplo.com/clientes/${cliente_id}/comprasAs colunas da entrada não passam para a saída: saem as colunas da API e, se habilitada, a coluna de ID. Cada chamada pagina sozinha. O primeiro item que responde define as colunas de todos, e um erro em qualquer item derruba o nó inteiro.
Variáveis do Dataflow
{NOME} e {NOME:formato} valem em todos os campos de texto do nó, inclusive URL, cabeçalhos, corpo, autenticação e paginação. Os formatos unix e unixms dão a data em segundos e em milissegundos. A lista de variáveis e de formatos está em variáveis.
text
https://api.exemplo.com/vendas?inicio={StartDate:yyyy-MM-dd}&fim={EndDate:yyyy-MM-dd}
https://api.exemplo.com/vendas?alterado_desde={LastDataPoint:yyyy-MM-dd HH:mm:ss}Na Extração Incremental, {LastDataPoint} traz o ponto onde a carga anterior parou; a regra está em tipos de carga.
Não use o mesmo nome para uma variável do Dataflow e para o parâmetro do Input Loop: ${id} contém {id}, e a variável seria trocada primeiro, deixando um $ sobrando.
Limites
- Não há limite de linhas nem de tamanho de resposta no nó.
- Na tela, itens por página vão até 10.000 e o máximo de páginas até 1.000.
- Corpo de resposta vazio falha o nó. Com seletor de dados preenchido, a mensagem é "JSON vazio fornecido para extração."
- Primeira página com lista vazia e inferência ligada falha com "Array retornado está vazio. Não é possível inferir schema." Com colunas manuais, devolve uma tabela vazia.
- Inferência desligada sem nenhuma coluna falha com "Para schema manual (InferSchema=false), é necessário definir pelo menos uma coluna."
- No Input Loop, se nenhum item devolver dado, o nó falha com "Nenhum dado retornado no loop."
Relacionado
Pelo Lumo CLI
O nó também pode ser escrito e versionado em YAML. Veja a referência de flow.