Variáveis permitem que você dê um nome a um valor e o reutilize onde precisar.
Por exemplo, em vez de colar um token de API que muda frequentemente em cada requisição, defina uma variável como ACCESS_TOKEN e use {{ACCESS_TOKEN}} em suas requisições. Quando o token expirar, atualize a variável uma vez e todas as requisições que a utilizam pegarão automaticamente o novo valor.
Tipos de Variáveis em Destaque
O Apidog suporta vários tipos de variáveis, cada um projetado para cenários específicos. Você pode usar: variáveis globais de nível de equipe, variáveis globais de nível de projeto, variáveis de módulo, variáveis de ambiente, variáveis de dados de teste e variáveis locais.
Variáveis Globais
Variáveis globais permitem que você compartilhe dados amplamente. Existem dois tipos:
Variáveis Globais de Nível de Projeto: Limitadas ao projeto atual. Perfeitas para passar dados entre requisições no mesmo projeto. Por exemplo, armazene um token do endpoint de login como uma variável global de nível de projeto e, em seguida, reutilize-o em outras requisições dentro desse projeto.
Variáveis Globais de Nível de Equipe: Compartilhadas entre todos os projetos de uma equipe. Ideais para colaboração entre projetos. Por exemplo, se um serviço de autenticação emite um token usado por vários projetos, armazene-o como uma variável global de equipe.
Observação sobre Permissões: Membros regulares podem apenas visualizar e alterar os valores atuais das variáveis globais de nível de equipe existentes. Eles não podem adicionar/excluir variáveis ou renomeá-las. Somente administradores de equipe podem gerenciar totalmente as variáveis de nível de equipe em Recursos da Equipe → Variáveis.
Variáveis de Módulo
Variáveis de módulo são delimitadas a um módulo específico. Se você importar uma Coleção Postman, suas variáveis de coleção serão importadas como variáveis de módulo do Apidog.
Elas são ótimas para configuração específica do módulo. Por exemplo, um projeto pode ter módulos separados para usuários, pedidos e produtos — cada um pode manter sua própria configuração em variáveis de módulo.
Certifique-se de que o Apidog esteja atualizado para usar variáveis de módulo.
Variáveis de Ambiente
Variáveis de ambiente são provavelmente o tipo mais usado. Elas permitem que você alterne entre ambientes sem mudar a configuração para cada requisição.
Na prática, você geralmente tem múltiplos ambientes (local, teste, staging, produção). Cada um possui diferentes endereços de servidor, conexões de banco de dados ou configurações de terceiros. Com as variáveis de ambiente, você pode alternar entre eles instantaneamente.
Nota: Apenas um ambiente pode estar ativo por vez. Quando você seleciona um ambiente, todas as variáveis nele definidas entram em vigor.
Variáveis de Dados de Teste
Variáveis de dados de teste impulsionam testes baseados em dados. Quando você precisa testar o mesmo endpoint com muitos conjuntos de dados, esta é sua aliada.
Prepare um arquivo CSV ou JSON com múltiplas linhas (ou objetos). Em um cenário de teste automatizado, importe o arquivo, e o Apidog irá iterar cada linha como um conjunto de variáveis e executar o teste para cada uma.
Variáveis Locais
Variáveis locais têm o tempo de vida mais curto — válidas apenas durante uma única requisição ou execução de teste. Elas desaparecem após a execução.
Como as variáveis locais têm a maior prioridade, elas são perfeitas para sobrescrever momentaneamente outros tipos de variáveis. Por exemplo, seu ambiente define user_id, mas para um teste especial, você precisa de um valor diferente — defina uma variável local com o mesmo nome em vez de mudar o ambiente.
Prioridade das Variáveis
Quando múltiplas variáveis compartilham o mesmo nome, o Apidog as resolve por prioridade (da mais alta para a mais baixa): Variáveis Locais > Variáveis de Dados de Teste > Variáveis de Ambiente > Variáveis de Módulo > Variáveis Globais de Nível de Projeto > Variáveis Globais de Nível de Equipe
Exemplo: Se você definir três variáveis chamadas userId:
- Variáveis globais de nível de projeto:
userId = 1000 - Variáveis de módulo:
userId = 2000 - Variáveis de ambiente:
userId = 3000
Quando você usa {{userId}} em uma requisição, o valor efetivo é 3000 (do ambiente). Se não houver valor de ambiente, ele retorna para o valor do módulo (2000), e depois para o valor global do projeto (1000).
Valores Iniciais vs. Atuais
Variáveis globais, de módulo e de ambiente possuem valores iniciais e atuais — isso equilibra o compartilhamento da equipe com a privacidade pessoal.
- Valores iniciais ficam nos servidores do Apidog e sincronizam com os colegas de equipe. Use-os para configurações compartilhadas, como URLs de servidores de teste e chaves de API públicas.
- Valores atuais ficam apenas no seu dispositivo. Use-os para segredos como chaves de API pessoais, senhas ou configurações de ambiente privadas.
Quando um valor atual existe, o Apidog o prefere. Se o valor atual estiver vazio, o Apidog usa o valor inicial. Quer que o valor atual siga o inicial? Clique no ícone de link ao lado do valor atual para religar.
Os valores atuais são armazenados no seu dispositivo e podem ser perdidos se você limpar o cache ou trocar de dispositivo. Na versão web do Apidog, eles são armazenados no navegador. Para migrar para um novo dispositivo, exporte/importe ambientes para migrar os valores atuais.
Nota: Ao executar testes automatizados com o Apidog CLI, tenha em mente uma diferença fundamental: O cliente Apidog usa os valores atuais durante a execução, enquanto o CLI usa os valores iniciais. Se os resultados diferirem entre o cliente e o CLI, esta é uma razão comum.
Formas de Definir Variáveis
Escolha o método que melhor se alinha à origem do valor e como você o utilizará.
Definir Variáveis Diretamente na Página de Gerenciamento de Ambiente
O método mais direto. Clique no botão Gerenciamento de Ambiente (canto superior direito), mude para o ambiente global ou um ambiente específico e, em seguida, adicione nomes e valores.
Este método é ótimo para configurações estáveis, como conexões de banco de dados. Você pode definir valores iniciais (compartilhados) e atuais (privados).
Usar o recurso "Armazenar Variável"
Frequentemente, o valor da variável vem de uma resposta — como um token de um endpoint de login ou um ID de usuário de um endpoint de criação de usuário. Use o recurso visual "Armazenar Variável" nos Pós-Processadores para configurar uma nova variável.
Nos Pós-Processadores de uma requisição, adicione "Armazenar Variável", escolha a fonte (comumente a resposta JSON) e selecione o campo usando JSONPath.
Por exemplo, se a resposta JSON for:
{
"user": {
"id": "69",
"email": "Ralph85@gmail.com",
"first_name": "Katlynn",
"last_name": "Reichert",
"api_token": "dolore ut mollit Duis sit",
"created_at": "2025-09-19T01:03:50.236Z",
"updated_at": "2025-05-10",
"deleted_at": "2025-09-18T18:30:51.217Z",
"role": "developer",
"metadata": {}
}
}Use $.user.email para extrair o token.
Você também pode definir variáveis diretamente da seção de resposta de uma requisição.
Definir Variáveis via Scripts
Para lógicas mais complexas, use Script Personalizado nos Pré-Processadores ou Pós-Processadores. O Apidog fornece uma API de script completa para manipular todos os tipos de variáveis.
// Set a project‑level global variable
pm.globals.set('variable_key', 'variable_value');
// Set a team‑level global variable (must be defined on the Team Resources page first)
pm.globals.set('variable_key', 'variable_value', 'TEAM');
// Set an environment variable
pm.environment.set('variable_key', 'variable_value');
// Set a module variable
pm.moduleVariables.set('variable_key', 'variable_value');
// Set a local variable
pm.variables.set('variable_key', 'variable_value');Ao armazenar objetos ou arrays, transforme-os em string primeiro e analise-os ao ler. Por exemplo:
pm.environment.set('user', JSON.stringify(userObj));
const users = JSON.parse(pm.environment.get('user'));Nota: Scripts só podem definir os valores atuais das variáveis. Os valores iniciais devem ser definidos na Página de Gerenciamento de Ambiente.
Usar Dados de Banco de Dados como Variáveis
O Apidog pode buscar dados diretamente de um banco de dados e defini-los como variáveis — ótimo para testes que dependem de registros reais.
Adicione uma Operação de Banco de Dados nos Pós-Processadores, configure a conexão e escreva o SQL. Em seguida, extraia campos para variáveis usando JSONPath.
Dicas para Usar Variáveis
Onde as Variáveis Funcionam
As variáveis são resolvidas apenas quando uma requisição é realmente enviada. Isso significa que você pode usá-las em cabeçalhos, parâmetros, corpo, cenários de teste e scripts — em qualquer lugar envolvido no envio de uma requisição.
Como o Apidog é visual em primeiro lugar, uma regra prática simples: se você vir um botão "Valor Dinâmico", você pode usar variáveis ali.
Sintaxe Básica
Use chaves duplas para referenciar uma variável: {{variableName}}. Isso funciona em URL, cabeçalhos, parâmetros e corpo.
Por exemplo, em parâmetros:
E no corpo:
Notas para corpos JSON: variáveis de string precisam de aspas, variáveis numéricas não. Chaves duplas podem acionar avisos de lint JSON, mas podem ser ignoradas com segurança.
Se você vir "variável não resolvida", não entre em pânico. Variáveis definidas em Pós-Processadores ou scripts podem não existir até que a requisição seja executada, e variáveis locais desaparecem após a execução. A melhor forma de confirmar é realmente enviar a requisição.
Buscar Campos Filhos de uma Variável
Às vezes, suas variáveis armazenam objetos ou arrays, não apenas strings ou números. Por exemplo, uma API de usuário frequentemente retorna um objeto com id, nome, e-mail, etc.
Suponha que você armazenou este objeto de resposta como uma variável chamada user:
{
"id": 1001,
"name": "Joe",
"email": "joe@example.com",
"role": "admin"
}Você pode referenciar campos específicos com notação de ponto, como {{user.id}} (1001) ou {{user.name}} ("Joe").
Para arrays, é semelhante. Se você tiver uma variável users:
[
{"id": 1001, "name": "Joe"},
{"id": 1002, "name": "Rio"},
{"id": 1003, "name": "Outher"}
]Use {{users[0].name}} para obter o nome do primeiro usuário, ou {{users[1].id}} para o id do segundo usuário.
Isso segue semânticas semelhantes ao JSONPath — o nome da variável age como a raiz ($).
Usar Variáveis em Scripts
Você pode usar variáveis nos scripts personalizados dos Pré-Processadores ou Pós-Processadores. O Apidog fornece um conjunto completo de APIs de script, permitindo que você acesse flexivelmente diferentes tipos de variáveis.
// Get a project‑level global variable
pm.globals.get('variable_key');
// Get a team‑level global variable
pm.globals.get('variable_key', 'TEAM');
// Get an environment variable
pm.environment.get('variable_key');
// Get a module variable
pm.moduleVariables.get('variable_key');
// Get a local variable
pm.variables.get('variable_key');Para objetos/arrays armazenados como strings, analise primeiro:
const userObj = JSON.parse(pm.environment.get('user'));
console.log(userObj.name);Testes Orientados a Dados com Variáveis de Dados de Teste
Faça o upload de um arquivo CSV ou JSON contendo múltiplas linhas de dados. Durante a execução, o Apidog substitui {{variableName}} pelos valores de cada linha e executa o teste uma vez por linha — perfeito para validar a robustez com muitas entradas.
Expressões de Valor Dinâmico
Além de suas próprias variáveis, o Apidog suporta valores dinâmicos, que geram dados aleatórios seguindo regras específicas.
Em scripts, você pode processar strings que incluem expressões dinâmicas com await pm.variables.replaceInAsync():
const template = "Hello, {{$person.fullName}}";
const result = await pm.variables.replaceInAsync(template);
console.log(result); // Outputs a randomly generated name
Valores dinâmicos são perfeitos para gerar dados de teste aleatórios sem preparar um conjunto de dados com antecedência.
Resumo
Variáveis são uma das funcionalidades mais poderosas do Apidog. Elas reduzem a repetição, tornam os testes flexíveis e simplificam a alternância entre projetos e ambientes. Seja para compartilhar configurações globais entre equipes, conduzir testes com dados CSV ou sobrescrever valores localmente, as variáveis ajudam a manter seu fluxo de trabalho eficiente e organizado. Ao dominar os tipos de variáveis, suas prioridades e as formas de defini-las, você pode garantir que suas requisições de API permaneçam consistentes, manuteníveis e prontas para cenários do mundo real.