Recursos API GraphQL

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, os requests 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

Filtrar

Ordenar

Paginar

1. Conjuntos de dados

A API GraphQL da Azion usa conjuntos de dados para indicar quais requests 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:

Dataset	Description
httpMetrics	Eventos de requests registradas pelo Edge Application e Edge Firewall.
l2CacheMetrics	Eventos de requests registradas pelo L2 Caching.
edgeFunctionsMetrics	Eventos de execução do Edge Functions.
imagesProcessedMetrics	Eventos de processamento de imagens do Image Processor.
idnsQueriesMetrics	Eventos de consultas realizadas no Intelligent DNS.
dataStreamedMetrics	Registros de envio de dados do Data Streaming para o endpoint do cliente.
httpEvents	Eventos de requests registradas pelo Edge Application e Edge Firewall..
l2CacheEvents	Eventos de requests registradas pelo L2 Caching.
edgeFunctionsEvents	Eventos de execução do Edge Functions.
imagesProcessedEvents	Eventos de processamento de imagens do Image Processor.
idnsQueriesEvents	Eventos de consultas realizadas no Intelligent DNS.
dataStreamedEvents	Registros de envio de dados do Data Streaming para o endpoint do cliente.
cellsConsoleEvents	Logs de eventos das aplicações usando o Edge Runtime retornados pelo Cells Console.

Para descobrir quais campos estão disponíveis em cada conjunto de dados, você pode rodar uma Introspection Query para consultar metadados. Veja mais no guia Como consultar metadados com a API GraphQL.

Veja mais sobre Como realizar consultas de Queries Top X com a API GraphQL.

Ao usar conjuntos de dados, é importante lembrar que você pode solicitar dados raw (brutos) ou aggregated (agregados). Ao solicitar informações de dados raw, usando os conjuntos Events, você recebe dados brutos relacionados ao conjunto específico sendo consultado. Ao solicitar informações de dados aggregated, usando os conjuntos Metrics, você recebe os dados relacionados ao conjunto específico sendo consultado em formato de gráficos.

Para especificar que você quer agregar dados dentro de um intervalo de tempo, adicione o operador aggregate na sua query junto ao campo group_by. A seguinte query, por exemplo, agrega dados:

query IdnsQuery {
  idnsQueriesMetrics(
    limit: 10
    aggregate: {sum:requests}
    groupBy: [ts]
    filter: {
      tsRange: {begin:"2022-10-20T10:10:10", end:"2022-10-23T10:10:10"}
    }
  ) 
  {	
    ts
    sum
  }
}

Veja mais sobre como agregar dados com o guia Como realizar consultas agregando dados com a API GraphQL.

Também é importante observar que, com o modelo de dados agregados, você recebe dados de acordo com um intervalo de tempo definido através de um adaptive resolver. Atualmente, há três intervalos possíveis para buscar seus dados: minuto, hora e dia.

Cada intervalo relativo a uma query é utilizado de acordo com as seguintes definições:

Minuto: usado para queries com intervalo de até 3 dias.
Hora: usado para queries com intervalo entre 3 e 60 dias.
Dia: usado para queries com intervalo acima de 60 dias.

Para receber os seus dados, você deve informar um intervalo de tempo utilizando os campos tsRange ou tsGt + tsLt nas suas queries com formato válido de data e hora. Se você usar o tsRange, você receberá os dados dentro do período de tempo que foi informado, incluindo o início e o fim da data informada.

Use o seguinte exemplo como base para utilizar o tsRange no seu request:

tsRange: {begin:"2022-06-23T09:10:10", end:"2022-06-23T16:10:10"}

Se você usar o tsGt + tsLt, você receberá os dados dentro do período de tempo que foi informado, sem considerar o início e o fim da data informada.

Use o seguinte exemplo como base para utilizar o tsGt + tsLt no seu request:

{

  "tsGt": "2022-07-22T10:10:10",

  "tsLt": "2022-09-19T10:10:10"

}

É importante definir e informar um intervalo de tempo em suas queries para que a API GraphQL consiga buscar os dados dos conjuntos de dados disponíveis e continue executando requests com os demais recursos disponíveis.

2. 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 um request de httpMetrics:

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

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

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

Você pode ajustar o seu request 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
  }
}

3. 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 o seu request 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
            }
        ]
    }
}

4. 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
    sourceLocPop
  }
}

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 um request com o uso desse mesmo recurso.

Não encontrou o que procurava? Abra um ticket.