Consultar uma API

A etapa Ação do fluxo com a ação de consulta HTTP chama um sistema externo e devolve a resposta. É determinística: mesma entrada, mesmo resultado.

O formulário

Campo	Uso
Endereço	A URL completa. http ou https
Método	GET, POST, PUT, PATCH, DELETE — escolhido de uma lista
Parâmetros de consulta	Campo próprio, codificado pela plataforma
Cabeçalhos	Nome e valor
Corpo	Para os métodos que o aceitam
Tempo limite	Dentro do teto da plataforma

Produz: código HTTP, corpo em JSON, corpo em texto, cabeçalhos e se a resposta foi truncada.

Use o campo de parâmetros, não a URL

Concatenar parâmetros na URL faz um valor com espaço, acento ou & montar uma requisição diferente da que você escreveu. O campo próprio é codificado corretamente.

Autenticação

Quase toda API pede credencial. A seção Autenticação do formulário cobre as formas usuais, e em nenhuma delas você digita a credencial dentro da etapa:

Forma	Quando usar
Sem autenticação	APIs públicas
Bearer	Um token no cabeçalho Authorization — o mais comum
API Key	Uma chave em um cabeçalho de nome próprio, ou em um parâmetro da URL
Basic	Usuário e senha
OAuth 2.0 (client credentials)	A plataforma obtém o token com o cliente e o segredo, e o renova sozinha
Personalizada	Quando o sistema exige um arranjo que não é nenhum dos anteriores

Escolhida a forma, você indica qual segredo do espaço fornece o valor. A etapa guarda a referência ao segredo; o valor fica no cofre e entra na requisição só no instante da chamada.

Por que a credencial não fica na etapa

Uma versão publicada é imutável. Uma chave digitada num cabeçalho entraria nela e não sairia mais — nem por edição, nem por rotação. Por isso a publicação recusa valores que parecem credencial.

Com a credencial como segredo, três coisas passam a funcionar:

• Rotação sem republicar. Você substitui o valor do segredo e todos os agentes que o referenciam passam a usar o novo. Nenhuma definição muda, nenhuma versão é republicada.
• Revogação imediata. Desativar o segredo corta o uso na hora, sem apagar o registro de que ele existiu.
• Nada aparece no histórico. O que fica registrado da execução mostra o cabeçalho de autenticação como ••••••••. Nem quem tem acesso ao histórico vê o valor.

Criar o segredo

Segredos são criados na configuração do espaço, não dentro da etapa. Cada um recebe um identificador próprio — que começa com ags_ — e um nome que você escolhe para reconhecê-lo na lista.

Quem cria informa o valor uma vez. Depois disso ele não é exibido de novo em lugar nenhum: o cofre aceita substituir, nunca mostrar. Se você perdeu o valor, o caminho é gerar outro no sistema de origem e substituir aqui.

Ver Recursos liberados.

Um segredo de produção não vale em desenvolvimento

Um segredo declarado como exclusivo de produção é recusado quando o agente roda em development. A separação é proposital: um teste não deve alcançar o sistema real por descuido.

O endereço precisa estar liberado

O espaço mantém uma lista de endereços liberados. Um endereço fora dela é recusado na publicação, e não na primeira execução.

Se você precisa chamar um sistema novo, peça a liberação a quem administra o espaço. Ver Recursos liberados.

O que a publicação recusa

Estas verificações acontecem antes de a versão existir:

Situação	Por quê
Endereço ausente ou inválido	Publicar sem endereço criaria uma versão imutável que falha na primeira execução
Esquema diferente de http/https	Fora do que a plataforma executa
Endereço fora da lista liberada	Governança do espaço
Método inventado	Só os métodos da lista
Método montado a partir de dados	O método precisa ser fixo
Tempo limite fora da faixa	Fora do teto da plataforma
Cabeçalho reservado	Host, Content-Length e afins são da plataforma
Valor de cabeçalho que parece credencial	Ver abaixo
Parâmetro que a ação não tem	Erro de digitação vira recusa, não comportamento estranho

Credencial em cabeçalho é recusada

Ver Autenticação. A publicação recusa um valor de cabeçalho que pareça credencial; o caminho é a seção de autenticação, com um segredo do espaço.

Proteção de rede

Mesmo com o endereço liberado, a plataforma resolve o nome no momento da chamada e bloqueia destinos internos — endereços privados, locais e de serviços de metadados —, inclusive quando um redirecionamento tenta levar para lá.

Um endereço montado a partir de dados publica com aviso: a plataforma não consegue afirmar de antemão para onde ele aponta, e a proteção passa a agir a cada conexão.

O que a publicação não faz

Ela não resolve o nome nem abre conexão para validar. Um agente correto não pode ficar impublicável porque o servidor do outro lado caiu naquele minuto.

Executar automação

Quando a chamada envolve mais do que uma requisição — autenticar, paginar, tratar erro específico —, o caminho é a etapa Executar automação: um programa publicado, com entrada e saída declaradas, adotado pela organização.

A diferença: a consulta HTTP é uma requisição; a automação é um procedimento. Nenhuma das duas usa IA.

Erros comuns

Sintoma	Causa	O que fazer
Publicação recusada por endereço não liberado	O host não está na lista do espaço	Peça a liberação
Publicação recusada por parecer credencial	Chave escrita direto no cabeçalho	Use uma referência a segredo
A chamada é bloqueada em execução	O destino resolveu para um endereço interno	Confirme o endereço público do sistema
Resposta truncada	A resposta é maior que o limite	Reduza o escopo da consulta ou pagine

Próximos passos

• Recursos liberados
• Quando algo falha
• Tipos de etapa