Como Configurar Parâmetros Globais no Apidog (Enviar Cabeçalhos de Autenticação em Todas as Requisições)

Você tem quarenta endpoints em um projeto, e cada um deles precisa do mesmo cabeçalho Authorization: Bearer ... e de um cabeçalho X-Api-Version em cada chamada. Adicionar essas duas linhas manualmente a cada requisição é lento e, pior, pode levar a inconsistências. Um endpoint recebe o token, outro é esquecido, e você perde uma tarde procurando por um erro 401 que só aparece em três rotas das quarenta.

Existe uma maneira melhor. O Apidog permite que você defina parâmetros uma única vez e os aplique automaticamente a cada requisição. Defina o cabeçalho no nível do projeto, referencie seu token como uma variável, e cada endpoint o herdará sem que você precise tocar em uma única requisição. Este guia explora as três alavancas documentadas para isso: parâmetros globais, variáveis de ambiente e um fallback de script com escopo de pasta. Você terminará com uma configuração funcional que anexa um cabeçalho de autenticação e um cabeçalho de versão a tudo, além de uma forma de provar que o cabeçalho realmente foi enviado. Se você quiser um contexto mais aprofundado sobre variáveis primeiro, nosso guia para dominar variáveis no Apidog complementa bem este.

botão

A ideia de uma requisição que carrega um cabeçalho padrão em cada chamada não é exclusiva do Apidog. É o mesmo padrão descrito pela referência de cabeçalhos HTTP da MDN: um pequeno conjunto de pares chave/valor que acompanham cada requisição. O trabalho do Apidog é permitir que você defina esse conjunto uma única vez.

O que "parâmetros globais" realmente significa

Um parâmetro global no Apidog é um parâmetro de requisição que se aplica a todo o projeto, em vez de a um único endpoint. Você o define uma vez, e o Apidog o anexa automaticamente às requisições correspondentes.

Os parâmetros globais cobrem quatro locais, e esta é a chave para toda a funcionalidade:

Cabeçalhos (Request Header) para coisas como Authorization ou X-Api-Version.
Cookies (Cookie Information) para cookies de sessão.
Query (URL Query Parameter) para valores como ?api_key= anexados a cada URL.
Corpo (Request Body Parameter) para um campo que cada corpo de requisição deve conter.

Para o caso de uso de cabeçalho de autenticação, você vai querer Cabeçalhos. Os outros três funcionam da mesma forma se o seu valor padrão estiver em um cookie, uma string de consulta ou um campo de corpo, em vez disso.

Uma regra importante antes de começar: parâmetros globais têm prioridade menor do que parâmetros definidos no nível do endpoint. Se uma requisição específica já define seu próprio cabeçalho Authorization, esse valor no nível do endpoint prevalece e o global é ignorado. Pense em um parâmetro global como o padrão que preenche quando um endpoint não definiu seu próprio valor, não como uma substituição rígida que sobrescreve tudo. Essa precedência é o que torna os parâmetros globais seguros para serem ativados em um projeto grande.

Definir um cabeçalho global em cada requisição

Aqui está o passo a passo principal. O objetivo: anexar Authorization e X-Api-Version a cada endpoint no projeto sem editar nenhum deles.

Passo 1: Abrir Gerenciamento de Ambiente

Parâmetros globais residem no Gerenciamento de Ambiente, que você abre no canto superior direito da página. Este é o ponto de entrada para parâmetros que se aplicam a todo o projeto, e a documentação do Apidog o descreve como o lar para valores que acompanham cada requisição. Abra-o, e você verá as seções onde você adiciona parâmetros por localização.

Passo 2: Escolher o local dos Cabeçalhos

Escolha Cabeçalhos (a localização Request Header) já que você está adicionando um cabeçalho de autenticação. Se o seu valor padrão fosse um cookie, um parâmetro de consulta ou um campo de corpo, você escolheria Cookies, Query ou Body, respectivamente. A mecânica é idêntica para todos os quatro.

Passo 3: Preencher os detalhes do parâmetro

Cada parâmetro global possui um conjunto fixo de propriedades. Preencha-as para o seu primeiro cabeçalho:

Nome: Authorization
Tipo: o tipo do parâmetro (string para um valor de cabeçalho).
Valor Padrão: Bearer {{token}} (mais sobre essa parte {{token}} abaixo).
Descrição: uma breve nota como "Token Bearer para todos os endpoints autenticados."

Um campo `Default` e um marcador de obrigatório (um asterisco `*`) também aparecem em parâmetros obrigatórios. Adicione uma segunda linha da mesma forma para o cabeçalho de versão:

Nome: X-Api-Version
Tipo: string
Valor Padrão: 2024-08-01
Descrição: "Versão da API fixada para cada requisição."

Passo 4: Ativar o parâmetro

Cada parâmetro tem um botão de ativar/desativar no lado direito. Ligue-o para ativar o parâmetro. Esse botão é útil mais tarde: se você precisar desativar um cabeçalho global para uma sessão de depuração, você o desabilita aqui em vez de deletá-lo e redigitar tudo.

Passo 5: Salvar

Salve a configuração. Ambos os cabeçalhos agora são globais. Cada requisição no projeto carregará Authorization e X-Api-Version, a menos que um endpoint específico sobrescreva um deles.

Passo 6: Provar que realmente foi enviado

Não confie que funcionou; verifique. Envie qualquer requisição no projeto e, em seguida, abra a aba Actual Request (Requisição Real) no console de resposta. Essa aba mostra a requisição exatamente como foi enviada, com as variáveis já substituídas pelos seus valores reais. Você deve ver ambos os cabeçalhos listados lá:

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01

Se os cabeçalhos aparecerem em Actual Request, eles foram enviados. Este é o ponto mais útil de toda a configuração, porque transforma "Acho que foi aplicado" em "Posso ver que foi aplicado".

Mantenha o segredo fora do cabeçalho: use uma variável

Note que o Valor Padrão acima era `Bearer {{token}}`, e não `Bearer sk_live_7f3a9c2e1b8d4056`. Essa sintaxe de chaves duplas referencia uma variável em vez de codificar o token bruto diretamente no parâmetro. O próprio esquema `Bearer` é definido na RFC 6750, e a referência do cabeçalho Authorization da MDN explica como os servidores o leem. A documentação do Apidog é explícita sobre o aspecto de segurança: para dados sensíveis como tokens de autenticação e chaves de API, use variáveis de ambiente em vez de armazenar o valor bruto como um Valor Padrão em texto simples. Uma variável é um placeholder dinâmico para um valor que você usa em muitas requisições e scripts, e mantém o segredo fora da definição do parâmetro.

Veja como configurar a variável `token`:

Clique no ícone de ambiente (o ícone ≡) no canto superior direito. Note que este é um ponto de entrada diferente do Gerenciamento de Ambiente: o ícone ≡ é onde as variáveis residem.
Encontre a seção Global Variables (Variáveis Globais).
Crie uma variável, por exemplo token com o valor do seu segredo bearer.
Clique em Salvar.

Agora, o valor do seu cabeçalho global `Bearer {{token}}` se resolve para `Bearer` no momento do envio, e a aba Actual Request confirma a substituição. Passar o mouse sobre um nome de variável em qualquer lugar mostra seu valor atual e escopo, o que é uma maneira rápida de verificar se você referenciou a variável correta.

Esta combinação é o padrão recomendado: o parâmetro global detém o slot do cabeçalho, e a variável detém o segredo. Nosso aprofundamento em gerenciamento de ambiente e segredos de clientes API detalha como manter os tokens fora de qualquer coisa que você possa compartilhar ou submeter.

Alternar valores por ambiente

Variáveis se tornam mais úteis quando você tem mais de uma. Projetos reais acessam servidores diferentes para Desenvolvimento, Teste e Produção, e cada um geralmente quer um token diferente. Agrupe cada conjunto em seu próprio ambiente, então alterne entre eles com o dropdown Ambientes ao lado do ícone ≡ (um ambiente de exemplo pode ser nomeado Local Mock). Mudar um ambiente direciona suas requisições para um conjunto diferente de servidores e troca os valores das variáveis desse ambiente. Seu cabeçalho global `Bearer {{token}}` permanece o mesmo; apenas o segredo resolvido muda com o ambiente. Se você está construindo fluxos de autenticação em cima disso, os conceitos em nosso guia de esquemas de segurança explicam como as definições de bearer, chave de API e OAuth são mapeadas para requisições reais.

Quando você quer o cabeçalho apenas em uma pasta

Parâmetros globais afetam todo o projeto. Às vezes, isso é muito abrangente. Digamos que apenas seus endpoints `/admin` precisem de um cabeçalho `X-Admin-Scope`, e o restante do projeto não deva carregá-lo.

Aqui está a limitação honesta: o Apidog não possui um campo nativo de "adicionar cabeçalho" nas configurações de pasta. Não há uma interface de usuário de cabeçalho no nível da pasta para preencher. O que a documentação descreve, em vez disso, é uma solução alternativa usando um script de pré-requisição no nível da pasta, para que cada requisição dentro dessa pasta herde o cabeçalho. O script usa a sintaxe `pm.*` compatível com Postman:

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });

Adicione isso como um script de pré-requisição na pasta, e cada requisição na pasta pegará o cabeçalho, enquanto as requisições fora da pasta não o farão. É um script, não um botão de configuração, então trate-o como um fallback intencional para necessidades com escopo de pasta, em vez do caminho principal. Para o modelo de script mais amplo em que isso se baseia, consulte nosso guia sobre scripts de pré-requisição e pós-requisição no Apidog.

Qual alavanca usar e quando

Você agora tem três maneiras de anexar um cabeçalho sem editar endpoints. Escolha por escopo:

Parâmetro global (Cabeçalhos) via Gerenciamento de Ambiente: o cabeçalho se aplica a todo o projeto. Este é o seu padrão para um cabeçalho de autenticação ou cabeçalho de versão compartilhado.
Variável de ambiente ({{token}}): combine-a com o parâmetro global para que o slot do cabeçalho seja global, mas o segredo seja armazenado com segurança e troque por ambiente.
Script de pré-requisição em nível de pasta (pm.request.headers.add): o cabeçalho se aplica apenas a uma pasta. Recorra a isso quando a abrangência do projeto for muito ampla.

Algumas coisas para observar. Verifique se há nomes de parâmetros duplicados para que dois cabeçalhos globais não entrem em conflito, e certifique-se de que o Tipo de cada parâmetro corresponda à sua forma de uso. E lembre-se da regra de precedência: um endpoint que define seu próprio `Authorization` sobrescreve o global, o que é um recurso quando uma rota precisa de um token diferente, mas uma surpresa se você esqueceu que essa rota tinha seu próprio valor. Nenhuma dessas três funcionalidades possui restrição de plano na documentação, então você não precisa de um nível específico para usá-las.

Automatize o fluxo de trabalho com o CLI do Apidog

Parâmetros globais e ambientes não são apenas uma conveniência da interface gráfica; eles também são levados em consideração em execuções automatizadas. Quando você constrói um cenário de teste salvo no Apidog e o executa a partir da linha de comando, a execução herda um ambiente que você passa por ID, de modo que o mesmo cabeçalho `Bearer {{token}}` e o valor `X-Api-Version` que funcionaram na interface gráfica se resolvem da mesma forma na CI.

Instale o CLI (Node.js v16+) e autentique-se:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Em seguida, execute um cenário salvo em um ambiente específico:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

A flag `-e` seleciona o ambiente, então o cenário utiliza as variáveis desse ambiente, incluindo seu token. A flag `-t` é o ID do cenário de teste e `-r` é o reporter (`cli`, `html` ou `junit`). Essa é a conexão: defina o cabeçalho e a variável uma vez, e cada execução de cenário através do CLI os carregará. Para detalhes de configuração e token, consulte o guia de instalação do CLI do Apidog, e para integrar execuções à automação, nosso passo a passo CLI do Apidog em GitHub Actions mostra o pipeline completo.

FAQ

Os parâmetros globais sobrescrevem um cabeçalho que eu defini em um endpoint específico?

Não. Parâmetros globais têm prioridade menor do que parâmetros de nível de endpoint. Se uma requisição define seu próprio cabeçalho `Authorization`, esse valor prevalece e o global é ignorado para essa requisição. Os globais atuam como o padrão do projeto, preenchendo onde um endpoint não definiu seu próprio valor.

Onde devo armazenar o token real para que ele não fique em texto simples?

Use uma variável de ambiente ou global, e não um Valor Padrão bruto. Defina o cabeçalho global como `Bearer {{token}}` e mantenha o segredo real em uma variável criada através do ícone de ambiente ≡. A documentação recomenda variáveis ou métodos seguros para dados sensíveis especificamente para que o token não seja armazenado inline. Nosso guia para extrair variáveis com JSONPath aborda como capturar um token de uma resposta de login e reutilizá-lo da mesma forma.

Como confirmo que o cabeçalho global foi realmente enviado?

Envie qualquer requisição e, em seguida, abra a aba Actual Request (Requisição Real) no console de resposta. Ela mostra a requisição como realmente foi enviada, com {{token}} e outras variáveis já substituídas pelos seus valores. Se o seu cabeçalho aparecer lá, ele foi enviado.

Posso adicionar um cabeçalho padrão a apenas uma pasta em vez de todo o projeto?

Sim, mas não através de um campo de configurações, porque o Apidog não possui uma interface de usuário de cabeçalho de pasta nativa. Adicione um script de pré-requisição na pasta usando pm.request.headers.add({ key, value }), e cada requisição nessa pasta herdará o cabeçalho, enquanto o restante do projeto não.

Preciso de um plano pago para usar parâmetros globais ou variáveis de ambiente?

A documentação para essas funcionalidades não lista nenhuma restrição de nível. Parâmetros globais, variáveis de ambiente e scripts de pré-requisição em nível de pasta são todos documentados sem uma barreira de gratuito versus pago.

Conclusão

Definir um cabeçalho em cada requisição é um trabalho único no Apidog: defina o cabeçalho como um parâmetro global em Gerenciamento de Ambiente, referencie o segredo como uma variável {{token}} para que ele não fique em texto simples, e confirme se foi enviado com a aba Actual Request. Quando você precisar de um cabeçalho em apenas uma pasta, o fallback do script de pré-requisição resolve. Para acompanhar em seu próprio projeto, Baixe o Apidog e configure seu primeiro cabeçalho global. É grátis, sem necessidade de cartão de crédito.

botão