Primeiros passos com a GraphQL API
Crie um personal token, execute sua primeira query da GraphQL API no GraphiQL ou com curl, leia a resposta e consulte eventos brutos de requisições.
Este guia orienta você na sua primeira query à GraphQL API.
- Crie um personal token no Azion Console.
- Consulte o total de requisições dos seus workloads com o dataset
workloadMetrics. - Leia a resposta e o formato de um erro.
- Consulte registros brutos de requisições com o dataset
workloadEvents.
Três elementos fazem uma query retornar dados, e cada um depende do anterior:
- O personal token autentica a requisição no header
Authorization. - O endpoint atende uma família de dados.
https://api.azion.com/v4/metrics/graphqlatende métricas agregadas, ehttps://api.azion.com/v4/events/graphqlatende eventos brutos. - O dataset nomeado na query, como
workloadMetrics, é a tabela de onde vêm as linhas. O endpoint precisa atender esse dataset.
A GraphQL API apenas lê dados: ela não tem mutations. Para mais informações, consulte Como a GraphQL API funciona.
Selecione a interface que você vai usar. Os pré-requisitos e cada etapa abaixo seguem essa escolha.
Pré-requisitos
- Uma conta Azion. Para criar uma, consulte Criar uma conta.
- Tráfego em pelo menos um workload nos últimos sete dias. Uma janela de tempo sem tráfego retorna um array vazio.
- Um navegador com login no Azion Console. Para fazer login, consulte Como acessar o Azion Console.
Crie um personal token
A GraphQL API autentica cada requisição com um personal token. Um personal token é adequado para uso com APIs porque pode ter uma expiração longa.
Para criar um personal token no Azion Console:
Acesse Azion Console > Account > Personal Token.
Em Name, digite um nome. Por exemplo: graphql-quickstart.
Em Expires within, selecione 90 days ou 1 year. Uma expiração mais longa é adequada para uso com APIs. Guarde o token como você guarda uma senha.
Na caixa de diálogo Personal Token has been created, selecione Copy. A caixa de diálogo mostra o token apenas uma vez.
O token aparece na página Personal Tokens com a sua Expiration Date. Para mais informações, consulte Como criar um personal token.
Execute sua primeira query
Esta query soma as requisições que os seus workloads receberam de 2026-09-26T14:00:00 a 2026-10-03T14:00:00. Ela agrupa os totais por tempo, do mais recente ao mais antigo, e retorna cinco linhas. Antes de executá-la, substitua as duas datas de tsRange por uma janela dentro dos últimos sete dias:
workloadMetrics é um dataset de métricas, então a query vai para o endpoint de métricas, https://api.azion.com/v4/metrics/graphql.
Para executar a query com curl, envie uma requisição POST ao endpoint de métricas. Substitua [TOKEN VALUE] pelo seu personal token:
O corpo é um objeto JSON cuja chave query contém a query como string. O header usa o esquema Token: um header Bearer retorna 401 com Authentication credentials were not provided., o mesmo resultado de um header ausente.
O endpoint retorna HTTP 200 e as linhas. A resposta abaixo está cortada após a terceira das suas cinco linhas:
Cada linha é uma hora da janela que recebeu requisições, com o total de requisições em sum.
Leia a resposta
Uma resposta da GraphQL API é um objeto JSON. A chave data contém um array por dataset da query, com o nome do dataset: data.workloadMetrics para a query de Execute sua primeira query. O array contém um objeto por linha, e cada objeto traz apenas os campos que a query selecionou.
A resposta de workloadMetrics se lê assim:
tsé o bucket de tempo em UTC. Uma janela de sete dias retorna buckets de uma hora.sumé o total derequestsnesse bucket, com o nome da função de agregação emaggregate: { sum: requests }.- As linhas seguem
orderBy, aquits_DESC, da mais recente à mais antiga. limitlimita o número de linhas. O padrão é10, e o argumento aceita até10000.
Uma janela sem dados retorna um array vazio com HTTP 200, não um erro.
Uma query que a API recusa retorna um status HTTP de erro e uma chave detail no lugar de data. Datasets de métricas e de eventos exigem uma janela de tempo, então esta query, que não tem filter, é recusada:
A API retorna HTTP 400:
Todo erro da GraphQL API tem este formato detail, não um array errors do GraphQL. Para cada mensagem e a sua causa, consulte Mensagens de erro.
Consulte eventos brutos
Eventos brutos são os registros de requisições individuais, uma linha por requisição, sem agregação. O dataset workloadEvents contém esses registros, e o endpoint de eventos, https://api.azion.com/v4/events/graphql, atende esse dataset. O endpoint de métricas recusa datasets de eventos com 400 e Cannot query field "workloadEvents" on type "Query".
Esta query retorna o horário, o host, o código de status e a URI das cinco requisições mais recentes. Datasets de eventos guardam registros por cerca de sete dias, então substitua as datas de tsRange por uma janela dentro da última semana:
Para executar a query com curl, envie uma requisição POST ao endpoint de eventos. Substitua [TOKEN VALUE] pelo seu personal token:
O endpoint retorna HTTP 200 e um objeto por requisição. A resposta abaixo está cortada após a terceira das suas cinco linhas:
Cada linha é uma requisição, sem groupBy e sem agregação. Os dados de faturamento, contabilidade e consumo têm os seus próprios endpoints, que recebem a mesma requisição POST e o mesmo header Authorization: https://api.azion.com/v4/billing/graphql, https://api.azion.com/v4/accounting/graphql e https://api.azion.com/v4/consumption/graphql. Os datasets e os filtros de tempo desses endpoints estão em Queries.
No GraphiQL, a URL da página é atualizada com um parâmetro codificado após a execução de uma query. Copie essa URL para compartilhar a query com outro usuário.