Datasets e argumentos de query

Um dataset é o conjunto de registros que uma query da GraphQL API lê, nomeado como o campo de nível superior da query. Cada um dos cinco endpoints atende os seus próprios datasets. Todo dataset aceita os mesmos argumentos para filtrar, agregar, agrupar, ordenar e paginar os seus registros, e a maioria dos datasets de metrics também aceita resample.

Datasets

A tabela lista os datasets de cada endpoint. A coluna Endpoint indica o segmento da URL: um dataset de metrics vai para https://api.azion.com/v4/metrics/graphql, e o mesmo padrão vale para events, billing, accounting e consumption. Envie cada query em uma requisição POST com o header Authorization: Token [TOKEN VALUE]:

Os datasets do endpoint events retornam registros brutos, um por evento, como mostra Dados brutos. Os datasets do endpoint metrics retornam dados agrupados em buckets de tempo, como mostra Dados agregados.

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. Uma query de introspecção retorna as mesmas informações a partir do próprio endpoint: todo dataset e todo campo que ele atende, com as suas descrições e tipos. Para mais informações, consulte Consulte os metadados do schema GraphQL.

Datasets descontinuados

O schema marca como descontinuados os nomes de dataset abaixo. Um dataset descontinuado aceita os mesmos campos do seu substituto e retorna as mesmas linhas, então mover uma query para o substituto muda apenas o nome do dataset:

Argumentos de query

Todo dataset da GraphQL API, em todo endpoint, aceita os seis primeiros argumentos abaixo, e resample se aplica apenas a datasets de metrics. Todos são opcionais, mas uma query em um dataset de metrics, events ou consumption precisa de uma janela de tempo dentro de filter:

As funções de aggregate, e o que groupBy faz com elas, estão em Queries.

Filtragem

O argumento filter seleciona os registros que uma query da GraphQL API lê e aceita qualquer campo do dataset. Cada chave nomeia um campo e, por meio de um sufixo, um operador: statusGte: 400 mantém os registros cujo status é 400 ou maior. Uma chave sem sufixo compara por igualdade, então host: "www.example.com" e hostEq: "www.example.com" retornam os mesmos registros.

Esta query retorna os buckets de tempo de uma janela de sete dias que contêm requisições do Brasil:

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

Operadores

Os operadores que um campo aceita dependem do seu tipo. Um campo de string contém texto, como host. Um campo numérico contém um valor bruto, como status ou requestTime. Um campo calculado contém um valor que a API calcula, como requestsTotal ou dataTransferredTotal:

Um operador que o campo não aceita retorna 400. Por exemplo, requestsTotalLte em workloadMetrics retorna Unknown field., porque campos calculados não aceitam Lte nem Gte.

Um padrão de Like ou Ilike usa % para qualquer sequência de caracteres. "Braz%" corresponde a valores que começam com Braz, "%ao Paulo" corresponde a valores que terminam com ao Paulo e "%ttp%" corresponde a valores que contêm ttp. Maiúsculas e minúsculas no padrão importam apenas com Like: hostLike: "%EXAMPLE%" não corresponde a www.example.com, e hostIlike: "%EXAMPLE%" corresponde.

Os datasets dos endpoints billing e accounting não têm campo ts. Os seus filtros aceitam o campo sem sufixo, Eq, In e Range, em campos como periodFrom, periodTo e created.

Condições combinadas

As chaves dentro de um mesmo objeto filter se aplicam todas juntas. Para combinar condições de forma explícita, and e or recebem uma lista de filtros, e not recebe um filtro:

• and mantém os registros que correspondem a todos os filtros da lista, como and: [{ hostEq: "www.example.com" }, { statusGte: 400 }].
• or mantém os registros que correspondem a pelo menos um filtro da lista.
• not exclui os registros que correspondem ao seu filtro, como not: { requestUriLike: "%/_astro/%" }.

Esta query conta, por status, as requisições de uma janela de sete dias cujo status é 304 ou fica entre 200 e 299:

A resposta aparece cortada após a terceira linha:

O schema tipa or como uma lista. A API também aceita or como um único objeto, por exemplo or: { status: 304, statusRange: {begin: 200, end: 299} }, e trata as suas chaves como alternativas.

Janela de tempo

Uma query em um dataset de metrics, events ou consumption define a sua janela de tempo dentro de filter. tsRange recebe um begin e um end. tsGt e tsLt definem um limite cada, e tsGt sozinho é aceito. Sem nenhum deles, a API retorna 400 com To execute queries it is mandatory to provide the desired time interval.

Os dois limites de uma janela usam o mesmo fuso horário. Um limite com Z ao lado de um limite sem ele retorna 400 com The start and end dates must have the same timezone. Limites com o mesmo offset, como -03:00, são aceitos, e a API os converte para UTC. Uma janela cujo begin vem depois do seu end retorna uma lista vazia.

Esta query soma as requisições de uma janela de uma hora por bucket de tempo, com tsGt e tsLt:

A resposta contém apenas os buckets da janela que contêm requisições:

Os datasets de billing e accounting filtram por período, como mostra Queries.

Ordenação

O argumento orderBy ordena as linhas que uma query da GraphQL API retorna. Ele recebe uma lista de chaves, e cada chave é um campo ou uma saída de função seguida de _ASC, do menor para o maior, ou _DESC, do maior para o menor. Por exemplo, orderBy: [avg_ASC] coloca a menor média primeiro. Uma query pode listar várias chaves, como orderBy: [ts_ASC, requestId_ASC].

Uma chave sem direção retorna 400. Para orderBy: [host] em workloadMetrics, a mensagem termina com Expected type "WorkloadMetricsOrderByFields", found host.

Esta query soma os bytes enviados por host em uma janela de sete dias, do maior para o menor:

A resposta aparece cortada após a terceira linha:

Paginação

Os argumentos offset e limit paginam as linhas de uma query da GraphQL API. offset define quantas linhas a API pula, 0 por padrão. limit define quantas linhas ela retorna, 10 por padrão e no máximo 10.000. Por exemplo, offset: 15 com limit: 30 retorna as linhas 16 a 45. Um limit fora do intervalo de 0 a 10.000 retorna 400, como descreve Limites da GraphQL API.

Esta query retorna as linhas 6 a 10 das requisições de uma janela de 24 horas, ordenadas por tempo e depois por ID da requisição:

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

A mesma query com limit: 10 e sem offset retorna as linhas 1 a 10, e as suas últimas cinco linhas são as cinco linhas acima. Um offset além da última linha retorna uma lista vazia.

Cada página é uma query separada. Quando os dados mudam entre duas queries, linhas podem passar de uma página para a seguinte, então uma página pode deixar de trazer uma linha ou repetir uma. A query acima ordena por ts e depois por requestId, então linhas com o mesmo timestamp voltam na mesma ordem em todas as páginas.

Reamostragem

O argumento resample combina as linhas de um dataset de metrics em menos pontos no tempo, para caber em um gráfico. Ele complementa limit: limit limita as linhas, e resample define em quantos pontos a janela de tempo é dividida. Ele recebe duas chaves:

• function, obrigatória, define como os pontos dentro de cada intervalo se combinam.
• points, um Int, define o número de intervalos a buscar.

function aceita um de quatro valores:

• sum retorna o total dos pontos no intervalo.
• mean retorna a média deles.
• max retorna o maior ponto.
• min retorna o menor ponto.

Todo dataset de metrics aceita resample, exceto connectedUsersMetrics e objectStorageMetrics. Em um dataset de events, o argumento retorna 400 com Unknown argument "resample" on field "workloadEvents" of type "Query". Uma query com resample também precisa de ts em groupBy, com todos os campos de groupBy selecionados. Sem eles, a API retorna 400 com uma mensagem que começa com Query syntax error. In resample queries, you must provide the timestamp (ts) field in the group_by parameter.

A API divide a janela de tempo por points e arredonda o intervalo para baixo, até um número inteiro de buckets de tempo, então a resposta pode conter mais pontos que points. Por exemplo, uma janela de sete dias com points: 10 retorna 11 pontos, com 16 horas de distância entre eles, porque 168 horas divididas por 10 dão 16,8 horas. Um intervalo sem dados ainda retorna um ponto, com valor zero. Com points: 100, a mesma janela retorna um ponto por hora, incluindo as horas vazias, enquanto a mesma query sem resample retorna apenas as horas que contêm dados.

Esta query calcula a média das contagens de requisições por hora de uma janela de sete dias em cerca de dez pontos:

A resposta contém 11 linhas, com 16 horas de distância entre elas, cortada aqui após a terceira:

Recursos relacionados