GraphQL API

GraphQL é uma linguagem de query para APIs. Um cliente envia uma query que nomeia os registros que deseja e os campos de cada registro, e o servidor retorna um objeto JSON com a mesma forma da query. O cliente escolhe os campos, então uma resposta não traz nada que o cliente não pediu, e uma pergunta diferente exige uma query diferente, não um endpoint diferente.

A GraphQL API lê os dados de métricas, eventos, faturamento, contabilização e consumo da sua conta Azion, com um endpoint por família de dados em https://api.azion.com/v4. Qualquer cliente que envie um POST HTTP com um corpo JSON e um personal token pode chamá-la. Use a GraphQL API para criar gráficos de tendências de requisições, ranquear os endereços IP, URIs ou user agents por trás do seu tráfego, investigar requisições bloqueadas ou ler suas faturas e o uso dos seus produtos.

Estrutura de uma query

Uma query nomeia um dataset, os argumentos que o filtram, agrupam e ordenam, e os campos a retornar. Esta query soma as requisições dos seus workloads por intervalo de tempo em uma janela de sete dias, das mais recentes para as mais antigas:

O endpoint de métricas retorna HTTP 200 e cinco linhas. A resposta abaixo está cortada após a terceira linha:

• workloadMetrics é o dataset, a tabela de onde vêm as linhas. Ele é servido pelo endpoint de métricas, https://api.azion.com/v4/metrics/graphql.
• filter leva a janela de tempo em tsRange. Datasets de métricas, eventos e consumo recusam uma query sem ela.
• aggregate: { sum: requests } e groupBy: [ts] somam requests por intervalo de tempo, e o campo de resultado se chama sum, como a função.
• limit limita as linhas a cinco. Sem ele, uma query retorna 10 linhas.

Se você já escreveu uma query GraphQL, a sintaxe é a mesma. A única diferença é uma query recusada: ela retorna um objeto JSON com uma chave detail, não um array errors do GraphQL.

Endpoints e datasets

A GraphQL API não é um único endpoint. São cinco APIs, cada uma com seu próprio endpoint e schema, e uma query vai para o endpoint que serve o dataset dela:

1. Seu cliente envia a query em uma requisição POST, com o header Authorization: Token [TOKEN VALUE] e o valor de um personal token.
2. A requisição vai para o endpoint da família de dados que a query lê. Uma query no dataset de eventos workloadEvents enviada ao endpoint de métricas retorna 400.
3. O endpoint seleciona as linhas do dataset que a query nomeia, filtradas, agrupadas e ordenadas pelos argumentos dela.
4. A resposta contém um array por dataset sob a chave data, com um objeto por linha e apenas os campos que a query selecionou.

Cada endpoint serve uma família de dados:

Para os datasets, a resolução de tempo e a retenção por trás de cada endpoint, consulte Como a GraphQL API funciona.

Escopo e limites

• Somente leitura: a GraphQL API responde a queries. Ela não tem mutations, e nenhuma query altera a sua conta.
• Autenticação: toda requisição leva Authorization: Token [TOKEN VALUE]. Um header Bearer é recusado como um header ausente, com 401 e Authentication credentials were not provided. Para criar um token, consulte Personal tokens.
• Clientes: o GraphiQL Playground é um editor no navegador servido em cada URL de endpoint para uma sessão do Azion Console com login feito. curl ou qualquer cliente HTTP envia a query como um corpo JSON, e Execute queries GraphQL no Postman cobre o Postman. O repositório aziontech/azion-queries contém exemplos de query para adaptar.
• Datasets e campos: Datasets e argumentos de query lista os datasets de cada endpoint e os argumentos que eles compartilham. Os campos de cada dataset estão em Campos de Real-Time Metrics, Campos de Real-Time Events, Campos de Billing, Campos de Accounting e Campos de Consumption. Queries mostra uma query de dados brutos, uma agregada, uma financeira e uma de uso, cada uma com a sua resposta.
• Limites: uma query retorna até 10.000 linhas e seleciona até 37 campos em um dataset de métricas, ou 36 em workloadEvents. Datasets de eventos mantêm registros por cerca de 7 dias. Além de um limite de linhas ou de campos, a query retorna 400, e Limites da GraphQL API lista todos os limites.
• Erros: todo erro é um código de status com um corpo JSON que contém uma chave detail. Respostas de erro lista cada mensagem e a sua causa, e Solucionar problemas da GraphQL API dá a causa e a correção de cada sintoma.
• Termos: o Glossário define os termos que estas páginas usam, como dataset, dados brutos e adaptive resolver.

Próximos passos