Configurador HTTP

O Configurador HTTP faz uma chamada HTTP antes da carga e transforma campos da resposta em variáveis. Você diz qual campo vira qual variável, com um JSONPath por linha, e os nós seguintes usam o valor como se ele sempre tivesse existido.

Variável	JSONPath
ACCESSTOKEN	$.access_token
EXPIRESIN	$.expires_in

Com a resposta {"access_token": "eyJhbGciOi...", "expires_in": 3600}, o fluxo passa a ter {ACCESSTOKEN} e {EXPIRESIN}. Em SQL, DuckDB e HTTP Request você escreve com chaves; em Python a variável chega com o mesmo nome, sem chaves. Ver Variáveis para as formas de consumir uma.

Ele existe para o caso do token que expira. A API do parceiro exige login antes de cada consulta, o token dura uma hora, e não dá para deixá-lo fixo no Dataflow.

O token na mesma execução

Sem este nó, o desenho comum tinha três peças: um Dataflow só para buscar o token e gravá-lo no Datalake, com agendamento próprio; em cada fluxo consumidor, uma leitura do Datalake ligada a um Configurador Python que devolvia ACCESSTOKEN; e o HTTP Request usando a variável. Um fluxo, um agendamento e uma tabela existiam só para guardar um texto que expira.

Com o Configurador HTTP, cada Dataflow pede o próprio token no começo da execução. Um login OAuth2 client_credentials fica assim:

1. Na aba Requisição, método POST, a URL do endpoint de token e, em Corpo, o tipo Form URL Encoded com grant_type, client_id e client_secret.
2. Na aba Variáveis, clique em Adicionar variável e preencha ACCESSTOKEN e $.access_token.
3. No HTTP Request que busca os dados, na aba Autenticação, escolha Bearer Token e escreva {ACCESSTOKEN} no campo Token.

Não há ligação a desenhar entre o configurador e o HTTP Request. A variável chega por nome.

Ele roda antes do resto

O Agente ETL trata todo nó configurador do mesmo jeito: havendo um no fluxo, ele executa antes dos outros, num escalonamento próprio. Você não precisa ligá-lo aos extratores para garantir a ordem.

O Configurador HTTP não tem entrada nem saída de dados. Ele não recebe o resultado de outro nó, como o Python recebe em input_0. Se a chamada depende de um valor que está numa tabela, leia esse valor com um Configurador Python.

Dois configuradores no mesmo fluxo, um usando a variável do outro, não têm ordem garantida entre si. Se o segundo depende do primeiro, junte os dois num Configurador Python.

Configuração

O nó abre com cinco abas. Quatro são as mesmas do HTTP Request: Requisição (URL, método, query, headers e corpo), Autenticação (Nenhuma, Basic Auth, Bearer Token ou API Key), Opções (timeouts, redirecionamento, SSL) e Retry. A quinta, Variáveis, é a tabela de nome e JSONPath.

Paginação e laço de entrada ficam de fora: o configurador faz uma chamada.

Os campos aceitam variável. {API_BASE_URL}/oauth/token na URL, {ENV_CLIENT_SECRET} no corpo e {API_KEY} num header são resolvidos antes da chamada.

Variáveis e JSONPath

Cada linha da aba Variáveis lê um caminho da resposta JSON. O dialeto é o mesmo do campo Data Path do HTTP Request.

Resposta	JSONPath	Valor
{"access_token": "abc"}	$.access_token	abc
{"data": {"token": "abc"}}	$.data.token	abc
{"items": [{"id": 42}]}	$.items[0].id	42
{"scopes": ["read", "write"]}	$.scopes	["read","write"]

Número continua número, texto continua texto, e true/false viram booleano. Objeto e lista viram texto com o JSON compacto, como na última linha.

Campo de data em texto, como "expires_at": "2026-10-02T12:00:00Z", sai do jeito que o provedor mandou e também aceita formato: {expires_at:unix} devolve o timestamp em segundos. Ver Formato. Esse tratamento de data exige Agente ETL 1.29.3 ou mais novo.

O nome da variável aceita letra, número e sublinhado. Nome repetido, nome sem JSONPath e tabela vazia fazem o nó recusar a execução, no editor e no Agente.

Tudo ou nada

Se qualquer linha da tabela falha, o nó falha, o Dataflow para, e nenhuma variável muda. Com três variáveis, um erro na segunda deixa as três com o valor que tinham antes da execução.

Isso vale para todo erro que o nó conhece: JSONPath sem resultado, valor null, texto vazio, resposta que não é JSON, resposta vazia e status HTTP fora da faixa 2xx. Um token vazio não segue adiante, porque o Bearer sem token do nó seguinte voltaria 401 longe da causa, e o log apontaria para a consulta em vez do login.

Por isso a aba Opções do configurador não mostra Falhar nó se a requisição falhar. A opção está sempre ligada, mesmo num nó copiado de um HTTP Request que a tinha desligada.

Segredo

client_secret, senha e chave de API escritos direto no nó ficam salvos na definição do Dataflow e acompanham toda cópia dela. Prefira uma variável global ou uma variável de ambiente da máquina do Agente:

client_secret = {ENV_PARCEIRO_SECRET}

Três lugares mostram mais do que parece:

• URL no log — o Agente registra a URL de cada chamada. Segredo na query string (?apikey=...) aparece no log de execução. Use header ou corpo.
• Corpo do erro — com status fora de 2xx, a mensagem de erro traz o corpo da resposta quando ele tem menos de 500 caracteres. Um provedor que ecoa a credencial no erro a expõe no log.
• Teste no editor — executar o nó no editor grava as variáveis devolvidas, token incluído, nas variáveis de desenvolvimento do Dataflow, para que os nós seguintes possam ser testados. É o mesmo comportamento do Configurador Python.

Retentativa e tokens concorrentes

A retentativa da aba Retry repete qualquer falha, inclusive 401 e 403. Com o segredo errado e 3 tentativas, o endpoint de login recebe 4 chamadas inválidas em sequência a cada execução, e há provedor que bloqueia a credencial por excesso de tentativas. Ligue a retentativa só depois de ver o login funcionar.

Cada Dataflow pede o próprio token. Se o provedor invalida o token anterior quando emite um novo, dois fluxos que rodam ao mesmo tempo derrubam um ao outro, de forma intermitente: o que pediu primeiro recebe 401 no meio da carga. Antes de migrar vários fluxos do mesmo provedor, rode dois juntos e confira. Se o provedor invalida, espace os agendamentos.

Quando usar o Python

O Configurador HTTP cobre a chamada única cujo resultado vai direto para variável. Fica com o Configurador Python:

• Cálculo sobre a resposta — somar a expiração à hora atual, montar um header a partir de dois campos.
• Mais de uma chamada — login em duas etapas, ou um token que depende de outro.
• Valor vindo de tabela — o Python aceita nós ligados à entrada.
• Refresh token que muda a cada uso — o configurador não guarda estado entre execuções. Ele serve para refresh token fixo, e falha quando o provedor troca o refresh token a cada renovação.

Versão do Agente

O nó exige Agente ETL 1.29.0 ou mais novo. Num Agente anterior, o Dataflow falha com "Processador de nome HTTPConfigurator não encontrado.". Ver Gerenciamento de Agentes para atualizar.

Falhas comuns

"A variável 'ACCESSTOKEN' não foi encontrada na resposta". O JSONPath não achou o campo, ou o campo veio null. Execute o nó no editor com uma variável apontando para $ e confira a resposta inteira, que vem como texto.

"A resposta HTTP não é um JSON válido". O endpoint devolveu HTML ou texto. Costuma ser URL errada caindo numa página de login ou de erro do servidor web. A mensagem traz só linha e posição, sem o corpo, para não expor um token que tenha vindo em texto puro.

"Erro HTTP 401 ao acessar ...". Credencial errada, ou client_id e client_secret no lugar errado: alguns provedores querem os dois em Basic Auth, outros no corpo. Confira na documentação do provedor.

O HTTP Request seguinte volta 401 mesmo com o configurador verde. O nome da variável no campo Token não bate com o da aba Variáveis. Maiúscula conta.

Falha intermitente quando dois fluxos rodam juntos. O provedor invalida o token anterior. Ver Retentativa e tokens concorrentes.

Relacionados

• Configurador Python: o configurador por script, para o que a tabela de JSONPath não cobre
• HTTP Request: as abas de requisição, autenticação e opções, e o extrator que consome o token
• Variáveis: as origens, o formato e o que o sistema injeta sozinho