Recursos API GraphQL

Explore como utilizar a API GraphQL da Azion para filtros precisos, ordenação de dados e paginamento eficiente em Real-Time Metrics e Events.

Ver como Markdown

Os recursos disponíveis para uso com a GraphQL são conjuntos de dados, filtrar, ordenar e paginar. Esses recursos possibilitam fácil acesso a seus dados. Assim, ao utilizar e combinar esses recursos disponíveis, o resultado será queries mais personalizadas e específicas. Dessa forma, as requisições buscam as informações exatas que você precisa.

As próximas seções detalham cada um dos recursos disponíveis na GraphQL e como eles podem ser utilizados.

Conjuntos de dados

A API GraphQL da Azion usa conjuntos de dados para indicar quais requisições você consegue executar através de queries e busca os dados do Real-Time Metrics e do Real-Time Events. Os conjuntos consistem de tabelas organizadas que trazem seus dados.

Veja cada um dos conjuntos de dados disponíveis e o que eles buscam.

Sete conjuntos de dados foram descontinuados e substituídos por outros:

  • cellsConsoleEvents por functionConsoleEvents
  • edgeFunctionEvents por functionEvents
  • httpEvents por workloadEvents
  • idnsQueriesMetrics por edgeDnsQueriesMetrics
  • idnsQueriesEvents por edgeDnsQueriesEvents
  • l2CacheMetrics por tieredCacheMetrics
  • l2CacheEvents por tieredCacheEvents

Real-Time Metrics GraphQL API

Conjunto de dadosDescrição
dataStreamedMetricsRegistros de envio de dados do Data Stream para o endpoint do cliente
edgeFunctionsMetricsEventos de execução do Functions
httpMetricsEventos de requisições registradas pelo Applications e Firewall
httpBreakdownMetricsConsulte dados agregados, detalhados e em tempo real sobre eventos de requisições HTTP bloqueadas
edgeDnsQueriesMetricsEventos de consultas realizadas no Edge DNS
imagesProcessedMetricsEventos de processamento de imagens do Image Processor
tieredCacheMetricsEventos de requisições registradas pelo Tiered Cache
connectedUsersMetricsConsulte o número de usuários conectados às suas aplicações, usando Live Ingest
botManagerMetricsConsulte o número de requisições avaliadas e as ações realizadas pelo Azion Bot Manager (se inscrito)
botManagerBreakdownMetricsConsulte as URLs mais impactadas por bots maliciosos, de acordo com os dados do Azion Bot Manager (se inscrito)
veja as descrições dos Campos da API GraphQL do Real⁠-⁠Time Metrics

Real-Time Events GraphQL API

Conjunto de dadosDescrição
activityHistoryEventsLogs de eventos de uma conta no Azion Console relacionados às atividades registradas no Activity History. Armazena dados por 2 anos e exibe dados a partir de 22 de setembro de 2023.
functionConsoleEventsLogs de eventos das aplicações usando o Azion Runtime retornados pelo Cells Console.
dataStreamedEventsRegistros de envio de dados do Data Stream para o endpoint do cliente.
functionEventsEventos de execução do Functions.
workloadEventsEventos de requisições registradas pelo Applications e Firewall.
idnsQueriesEventsEventos de consultas realizadas no Edge DNS.
imagesProcessedEventsEventos de processamento de imagens do Image Processor.
l2CacheEventsEventos de requisições registradas pelo Tiered Cache.
telemetryDeviceInfoEventsEventos relacionados ao dispositivo sendo utilizado para acesso e registrados pelo Azion Mobile SDK, tanto a nível de hardware quanto de software.
telemetrySensorsEventsEventos relacionados aos sensores dos dispositivos registrados pelo Azion Mobile SDK, como toque de tela e informações de giroscópio.
veja as descrições dos Campos da API GraphQL do Real⁠-⁠Time Events

Billing GraphQL API

A Billing GraphQL API está disponível apenas para contas do tipo Online Sales.

Conjunto de dadosDescrição
balanceFinancialEntryRegistros relacionados aos tipos de entradas financeiras e valores monetários
paymentsClientDebtRegistros relacionados aos débitos de clientes e pagamentos e valores monetários
billDetailRegistros detalhados de faturamento por produto, métrica e região para cada período de cobrança
veja as descrições dos Campos da API GraphQL de Billing

Accounting GraphQL API

Conjunto de dadosDescrição
accountingDetailRegistros relacionados aos dados contabilizados para produtos e suas métricas
veja as descrições dos Campos da API GraphQL de Accounting

Consumption GraphQL API

Conjunto de dadosDescrição
workloadConsumptionMetricsLogs relativos aos dados contabilizados para uso dos produtos e suas métricas.
Veja as descrições dos campos da API GraphQL de Consumption

dica — Você também pode rodar uma Introspection Query para consultar os metadados dos datasets de Metrics e Events. Os metadados fornecem o que cada dataset das APIs GraphQL permite e informações específicas: nome, descrição e formato. Veja mais no guia Como consultar metadados com a API GraphQL.

Você pode solicitar dados raw (brutos), usando os conjuntos Events, ou aggregated (agregados), usando os conjuntos Metrics.

ir para referência de queries brutas

ir para referência de queries agregadas

ir para guia Como realizar consultas agregando dados com a API GraphQL

Filtrar

Ao usar o recurso de filtrar, o retorno das suas queries se torna mais específico e preciso, de acordo com os dados que você deseja buscar. É possível utilizar a filtragem com qualquer um dos campos disponíveis no conjunto de dados que você está consultando.

Ao solicitar dados complexos ou em grande quantidade, os retornos da API podem conter ruídos e se tornar mais complicados. Filtrar queries permite consultar os seus dados de forma exata e direta. Por exemplo, se você usar a seguinte query para uma requisição de httpMetrics:

query HttpQuery {
httpMetrics(
limit: 10
filter: {
tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
}
)
{
ts
geolocCountryName
}
}

Você pode filtrar a query ao solicitar dados espeíficos sobre o campo geolocCountryName:

query HttpQuery {
httpMetrics(
limit: 10
filter: {
tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
geolocCountryName: "Brazil"
}
)
{
ts
geolocCountryName
}
}

Você pode ajustar a sua requisição conforme necessário para usar um campo de seu interesse, contanto que ele faça parte dos campos disponíveis no conjunto de dados que você está consultando naquele momento.

Você também pode filtrar usando múltiplos parâmetros AND e OR. Você deve definir todos os campos que deseja filtrar dentro do parâmetro, como no exemplo a seguir:

query totalImagesProcessedRequests {
imagesProcessedMetrics(
aggregate: {sum: requests}
limit: 100
filter: {
tsRange: {begin:"2023-03-20T19:52:00", end:"2023-03-20T20:52:00"}
or: {
status:304
statusRange: {begin: 200, end: 299}
}
}
groupBy:[ts]
orderBy:[ts_ASC]
)
{
ts
sum
}
}

Ordenar

O recurso ordenar permite que você organize e ordene os dados sendo recebidos de um conjunto de dados de acordo com a ordem daquele evento. Por exemplo, se você está recebendo dados do campo host como resposta para a sua requisição da API, você pode organizar esses dados para recebê-los:

  • Em ordem ascendente (ASC)
  • Em ordem decrescente (DESC)

Ao usar a propriedade orderBy, você deve adicionar ou a especificação ASC ou a especificação DESC.

Por exemplo, para utilizar o recurso de ordenar através de ordem ascendente, você deve adicionar orderBy na sua query e o campo que você deseja ordenar + ASC:

{
orderBy: [host_ASC]
}

Para ordenar seus dados em ordem decrescente (DESC), você deve adicionar o campo que deseja ordenar + DESC:

{
orderBy: [ts_DESC]
}

Se você usar esta query com DESC:

query SumBytesSentByHost {
httpMetrics(
limit: 1000
filter: {
tsRange: {begin:"2023-01-01T17:03:00", end:"2023-06-01T18:05:00"}
}
aggregate: {sum: bytesSent}
groupBy: [host]
orderBy: [sum_DESC]
)
{
host
sum
}
}

Você receberá uma resposta semelhante a:

{
"data": {
"httpMetrics": [
{
"host": "g1sdetynmxe0ao.map.azionedge.net",
"sum": 606226
},
{
"host": "uaykhefjdk9or.map.azionedge.net",
"sum": 583059
},
{
"host": "wz0ywpod397zk.map.azionedge.net",
"sum": 567633
},
{
"host": "zi1435nbhec7.map.azionedge.net",
"sum": 96002
}
]
}
}

E se você usar esta query com ASC:

query AvgRequesTimeByHost {
httpMetrics(
limit: 1000
filter: {
tsRange: {begin:"2023-01-01T17:03:00", end:"2023-06-01T18:05:00"}
}
aggregate: {avg:requestTime}
groupBy: [ts, host]
orderBy: [avg_ASC]
)
{
ts
host
avg
}
}

Você receberá uma resposta semelhante a:

{
"data": {
"httpMetrics": [
{
"ts": "2023-04-21T00:00:00Z",
"host": "zipo145nbhc7.map.azionedge.net",
"avg": 0.04871428571428572
},
{
"ts": "2023-04-13T00:00:00Z",
"host": "g1snmxepa0ao.map.azionedge.net",
"avg": 0.561
},
{
"ts": "2023-04-11T00:00:00Z",
"host": "g1syinmxe2ao.map.azionedge.net",
"avg": 4.101833333333333
},
{
"ts": "2023-04-11T00:00:00Z",
"host": "wz1yd307zk.map.azionedge.net",
"avg": 8.705666666666668
},
{
"ts": "2023-05-22T00:00:00Z",
"host": "uaifjdk6or.map.azionedge.net",
"avg": 31.493818181818185
}
]
}
}

Paginar

O recurso paginar permite definir a partir de que ponto você deseja que seus resultados sejam exibidos e quantos resultados você deseja visualizar. Atualmente, a API GraphQL da Azion usa offset e limit pagination para este recurso.

Paginar seus dados pode ser vantajoso quando você recebe grandes quantidades de dados na resposta da API. Você pode utilizar o recurso informando o offset e os limits. Assim, a API consegue retornar dados dentro da variação solicitada.

O parâmetro offset define o número de registros de dados que você deseja pular ao receber uma resposta. O parâmetro limit define o número de resultados que você deseja receber.

Definir os parâmetros offset e limit não é obrigatório. Se você não defini-los, a API GraphQL automaticamente define o offset para 0 e o limit para 10.

Veja o exemplo a seguir para entender o uso dos parâmetros offset e limit:

query HttpQuery {
httpMetrics(
offset: 15
limit: 30
filter: {
tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
}
)
{
ts
requestMethod
}
}

O offset está definido para 15, o que significa que a sua resposta exibirá a partir do 16º resultado. O limite está definido para 30, o que significa que a sua resposta exibirá um total de 30 resultados. Nesse caso, você receberá uma resposta exibindo do 16º resultado até o 45º resultado.

Se os seus dados são atualizados constantemente, o uso do recurso paginar pode resultar em falta ou duplicação de dados ao solicitar mais de uma requisição com o uso desse mesmo recurso.

Reamostrar

Disponível para: Real-Time Metrics GraphQL API

O recurso Reamostrar permite que você faça uma reamostragem dos seus dados a fim de exibir uma quantidade menor de pontos exibidos em gráficos. Ele funciona de acordo com a regra que você informa no campo function.

Você pode usá-lo para complementar o limite que adiciona à sua consulta, pois os pontos de dados padrão nos gráficos podem não ser o número ideal para sua análise ou para a sua ferramenta de visualização.

Se ocorrer uma extrapolação de dados, a API substituirá o valor que você informou e executará o cálculo mais próximo possível de acordo com os dados disponíveis.

A consulta deve conter o campo function e suas propriedades, bem como o campo groupBy e a variável ts.

Ao especificar sum, você receberá uma soma total dos pontos de dados naquele intervalo. Ao especificar mean, você receberá um cálculo de média (soma + divisão).

Veja um exemplo:

query httpRequestCount {
httpMetrics(
limit: 10000,
resample: {
function: sum
points: 100
}
filter: {
tsRange: {
begin:"2023-08-16T20:17:00", end:"2023-09-17T21:16:00"
}
},
groupBy: [ts]
orderBy: [ts_ASC]
)
{
ts
dataTransferredIn
dataTransferredOut
dataTransferredTotal
}
}

Suponha que o resultado original da sua consulta, sem reamostragem, retornou 1.456 logs. Como você fez uma consulta para uma reamostragem de 100 pontos, o cálculo que a API faz é 1.456 // 100 = 14,56 minutos de intervalo. Como a API só usa integer (números inteiros), ela arredondará o resultado para um intervalo de 14 minutos entre cada ponto retornado.

No entanto, a API não descarta os 0,56 minutos restantes. Ela continua adicionando-os até que o número se torne um inteiro e então soma ao número original de pontos solicitados.

No exemplo usado, retornou os 100 pontos solicitados originalmente mais os 4 pontos restantes, resultando em um total de 104 pontos para a consulta reamostrada.

Se você usar uma consulta com reamostragem, mas seus dados já retornam uma quantidade de pontos que são acessíveis aos gráficos, como 30 pontos, a API ignorará o pedido de reamostragem e retornará todos os pontos.