Como a GraphQL API funciona

Uma API GraphQL responde a uma query que nomeia os dados a ler e os campos a retornar. A resposta é um objeto JSON que contém esses campos e nada mais, então um cliente nunca baixa colunas que não usa. Para obter dados diferentes, você altera os campos ou o filtro na query, e a requisição vai para o mesmo endpoint.

A GraphQL API lê os dados de métricas, eventos, billing, accounting e consumption da sua conta Azion. Ela responde apenas a queries: não tem mutations, e nenhuma query altera a sua conta. Qualquer cliente que envie um POST HTTP com um corpo JSON pode chamá-la, seja qual for a linguagem de programação ou o framework.

As seções cobrem as cinco APIs e os seus endpoints, os datasets, os dados brutos e agregados, as janelas de tempo, a resolução de tempo, a reamostragem, a retenção e onde executar queries.

Cinco APIs, uma por família de dados

A GraphQL API é formada por cinco APIs, cada uma com o próprio endpoint e o próprio schema. Cada uma serve uma família de dados:

Este diagrama acompanha uma query do seu cliente até as linhas que ela retorna:

1. O seu cliente envia a query em uma requisição POST para o endpoint da família de dados que ele lê, com o header Authorization: Token [TOKEN VALUE].
2. O endpoint verifica o token. Um token Bearer é recusado como um header ausente, com 401 e Authentication credentials were not provided.
3. A query nomeia um dataset desse endpoint, os argumentos que o filtram, agrupam e ordenam, e os campos a retornar.
4. O endpoint responde com um objeto JSON cuja chave data contém um array por dataset, com um objeto por linha.

Uma query precisa ir para o endpoint que serve o seu dataset. Por exemplo, uma query em workloadEvents enviada ao endpoint de métricas retorna 400, porque workloadEvents é um dataset de eventos. Para o token e uma primeira requisição, consulte Primeiros passos com a GraphQL API.

Datasets

Um dataset é uma tabela da qual uma query da GraphQL API seleciona dados. Cada endpoint serve os próprios datasets, e uma query nomeia um deles, como workloadMetrics ou workloadEvents. Todo dataset recebe os mesmos argumentos: filter, aggregate, groupBy, orderBy, offset e limit.

O endpoint de métricas serve 17 datasets atuais, todos de dados agregados, como workloadMetrics para as requisições aos seus workloads e dnsQueriesMetrics para as consultas DNS. O endpoint de eventos serve 19 datasets atuais de registros brutos, como workloadEvents e activityHistoryEvents. O endpoint de billing serve balanceFinancialEntry, paymentsClientDebt e billDetail; o endpoint de accounting, accountingDetail; e o endpoint de consumption, workloadConsumptionMetrics.

O schema mantém alguns nomes antigos de datasets como aliases deprecated, que retornam as mesmas linhas que os seus substitutos. httpMetrics está deprecated; use workloadMetrics. httpBreakdownMetrics está deprecated; use workloadBreakdownMetrics. httpEvents está deprecated; use workloadEvents. edgeFunctionsMetrics está deprecated; use functionsMetrics. edgeDnsQueriesMetrics e edgeDnsQueriesEvents estão deprecated; use dnsQueriesMetrics e dnsQueriesEvents.

Para cada dataset e os argumentos que ele aceita, consulte Datasets e argumentos de query. Os campos de cada dataset estão em Campos do Real-Time Metrics, Campos do Real-Time Events, Campos de Billing, Campos de Accounting e Campos de Consumption.

Dados brutos e agregados

A GraphQL API retorna dados de requisições em dois modelos. Os dados brutos vêm dos datasets de Events: cada registro é uma requisição ou um evento como a Azion o registrou, sem processamento adicional. Os dados agregados vêm dos datasets de Metrics: os registros já estão agrupados em buckets de tempo de um minuto, uma hora ou um dia.

Os dois modelos atendem a perguntas diferentes. Os dados brutos respondem a investigações detalhadas de requisições individuais, como os top endereços IP, URIs ou user agents, as requisições bloqueadas por endereço IP ou por país e os top endereços IP por método de requisição. Os dados agregados respondem a totais e tendências, como as requisições por método HTTP, os hosts ou domínios com mais ou com menos requisições, a origem das requisições que são ameaças, incluindo o tráfego de bots quando a conta usa Bot Manager, e os usuários conectados às suas transmissões ao vivo. Para ranquear endereços IP de clientes com dados agregados, use workloadBreakdownMetrics, que tem remoteAddress; workloadMetrics não tem campo de endereço IP do cliente.

A troca é entre detalhe e alcance. Um registro bruto traz todos os campos de uma requisição, mas os datasets de Events, como workloadEvents, mantêm os registros por cerca de sete dias. Uma linha agregada traz uma contagem ou um total de um bucket, então perde a requisição individual, mas cobre janelas de muitos dias de uma vez.

Uma query de Metrics não precisa de groupBy. Esta query seleciona o horário, o país e a região das linhas em uma janela de sete dias, sem groupBy:

A resposta contém cinco linhas, cortada aqui após a terceira:

Um campo de medida, como requests, funciona de outra forma: ele é selecionado por meio de aggregate, como aggregate: { sum: requests }. Selecionado diretamente, ele retorna 400 com The query includes fields that require grouping. Please ensure all non-aggregated fields are included in groupBy argument. Um aggregate sem groupBy retorna uma linha com o total da janela. Para cada formato de query com a sua resposta, consulte Queries.

Janelas de tempo

Uma query nos datasets de Metrics, Events ou Consumption precisa nomear uma janela de tempo no seu filter. A janela é tsRange, com um begin e um end, ou os limites tsGt e tsLt. tsGt sozinho é aceito e lê tudo depois desse horário. Sem nenhum deles, a query retorna 400 com To execute queries it is mandatory to provide the desired time interval.

Os dois limites de tsRange precisam ter o mesmo fuso horário. Um begin em UTC com um end sem offset retorna 400 com The start and end dates must have the same timezone. Dois limites com o mesmo offset, como -03:00, são aceitos, e a resposta dá cada ts em UTC. Um begin posterior ao end retorna um array vazio, não um erro.

Os datasets financeiros não têm o campo ts, então uma janela de tempo não se aplica a eles. balanceFinancialEntry, paymentsClientDebt e accountingDetail retornam linhas sem nenhum filtro. Para ler um período, filtre accountingDetail ou billDetail por periodFrom e periodTo, ou por uma forma de intervalo como periodFromRange.

Resolução de tempo

Os datasets de Metrics escolhem o tamanho do bucket a partir da duração da janela de tempo, por meio de um resolvedor adaptativo. Uma janela curta retorna buckets de um minuto, uma mais longa, buckets de uma hora, e uma longa, buckets de um dia. A query não define o tamanho do bucket: ele segue a janela.

Os limites, como a API os aplica a workloadMetrics:

A troca é entre precisão e extensão. Uma janela de 72 horas já retorna buckets de uma hora, então um pico que durou alguns minutos se mistura à sua hora. Para ver o detalhe por minuto, consulte uma janela de 48 horas ou menos.

Alguns datasets mantêm um único tamanho de bucket, que a descrição no schema informa. workloadBreakdownMetrics retorna buckets de uma hora, mesmo para uma janela de uma hora. workloadConsumptionMetrics é descrito por hora, objectStorageMetrics por dia, e connectedUsersMetrics e os datasets do Bot Manager por minuto.

Reamostragem

A reamostragem define o número de pontos de dados que uma query de Metrics retorna, para que um gráfico mostre o número de pontos que você quer. Ela complementa limit: limit limita as linhas, e resample define em quantos pontos de tempo a janela é dividida. A reamostragem funciona na maioria dos datasets de Metrics: objectStorageMetrics e connectedUsersMetrics não têm o argumento resample, e nenhum dataset de Events, Billing, Accounting ou Consumption recebe esse argumento. Em um dataset de Events, resample retorna 400 como um argumento desconhecido.

Um resample recebe uma function e um número de points, e a query precisa ter ts em groupBy. Sem ts em groupBy, a query retorna 400 com uma mensagem Query syntax error que pede o campo de timestamp (ts) no parâmetro group_by. A function decide como os valores de cada intervalo se combinam:

A API divide a janela por points e arredonda o intervalo para baixo, até um número inteiro, então a quantidade de pontos retornados pode passar da quantidade pedida. Por exemplo, uma janela de sete dias com points: 10 divide 168 horas em intervalos de 16,8 horas, arredondados para 16, e retorna 11 pontos.

Quando os dados têm menos pontos do que o pedido, a API não ignora o resample: ela preenche os intervalos vazios. Por exemplo, uma janela de sete dias consultada com points: 100 retorna um ponto por hora, incluindo as horas vazias.

Retenção

Cada tipo de dado fica disponível para a GraphQL API por um período próprio. Uma janela mais antiga que o período não retorna linhas para essa parte da janela, sem erro.

Como os registros brutos expiram após cerca de uma semana, uma investigação sobre um tráfego mais antigo lê dados agregados. Por exemplo, para encontrar os endereços IP de clientes por trás das requisições do mês passado, consulte workloadBreakdownMetrics, que mantém as suas linhas por hora por 90 dias, depois que workloadEvents já descartou os registros individuais. Para os outros limites dentro dos quais uma query é executada, consulte Limites da GraphQL API.

Onde executar queries

A GraphQL API executa uma query de qualquer cliente que envie um POST HTTP, então você não precisa de banco de dados, framework ou linguagem de programação específicos. Três rotas cobrem a maior parte do trabalho:

• O GraphiQL Playground serve as mesmas URLs de endpoint em um navegador. Ele valida a query enquanto você digita e a executa depois que você faz login no Azion Console.
• O curl, ou qualquer cliente HTTP, envia a query como um corpo JSON, {"query": "..."}, com Content-Type: application/json e o header Authorization.
• O repositório aziontech/azion-queries no GitHub contém exemplos de queries para adaptar, agrupados por Data Stream, Applications, Top X queries e Functions. Você pode enviar alterações para o repositório.

Recursos relacionados