Como usar a API de relatórios personalizados assíncronos

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

O Apigee Analytics oferece um conjunto avançado de painéis interativos, geradores de relatórios personalizados e recursos relacionados. No entanto, esses recursos são interativos: você envia uma solicitação de IU ou API e a solicitação fica bloqueada até o servidor de análise retornar uma resposta.

Porém, as solicitações de análise poderão expirar se levarem muito tempo para serem concluídas. Se uma solicitação de consulta precisar processar uma grande quantidade de dados (por exemplo, centenas de GB), ela poderá expirar.

O processamento de consulta assíncrona permite consultar conjuntos de dados muito grandes e recuperar os resultados depois. Convém usar uma consulta off-line quando você achar que as consultas interativas podem expirar. Veja a seguir algumas situações em que o processamento de consulta assíncrona pode ser uma boa alternativa:

  • Análise e criação de relatórios que abrangem períodos longos
  • Análise de dados com uma variedade de dimensões de agrupamento e outras restrições que aumentam a complexidade da consulta
  • Gerenciamento de consultas quando você perceber que os volumes de dados aumentaram significativamente para alguns usuários ou organizações

Neste documento, descrevemos como iniciar uma consulta assíncrona usando a API. Também é possível usar a IU, conforme descrito em Como gerar um relatório personalizado.

Comparação da API Reports com a IU

O documento Criar e gerenciar relatórios personalizados detalha como usar a IU da Apigee para criar e executar relatórios personalizados. É possível gerar esses relatórios de maneira síncrona ou assíncrona.

A maioria dos conceitos para a geração de relatórios personalizados com a IU envolve o uso da API. Ou seja, ao criar relatórios personalizados com a API, você especifica métricas, dimensões e filtros incorporados à Apigee.

A principal diferença entre os relatórios gerados com a API e os gerados com a IU é que os primeiros são gravados em arquivos CSV ou JSON (delimitados por novas linhas), enquanto os últimos são exibidos na IU.

Limite de tempo em consultas

A Apigee impõe no máximo 365 dias no período para uma consulta assíncrona.

Como fazer uma consulta de análise assíncrona

Você realiza consultas de análise assíncronas em três etapas:

  1. Enviar a consulta.

  2. Acessar o status da consulta.

  3. Recuperar os resultados da consulta.

Etapa 1: enviar a consulta

É necessário enviar uma solicitação POST à API Queries. Essa API instrui a Apigee a processar sua solicitação em segundo plano. Se o envio da consulta for bem-sucedido, a API retornará o status 201 e um ID que você usará para se referir à consulta em etapas posteriores.

Exemplo:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @json-query-file

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

O corpo da solicitação é uma descrição JSON da consulta. No corpo do JSON, especifique as métricas, as dimensões e os filtros que definem o relatório.

Veja abaixo um exemplo de arquivo json-query-file:

{
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"
}

Consulte Sobre o corpo da solicitação abaixo para uma descrição completa da sintaxe do corpo da solicitação.

Exemplo de resposta:

O ID da consulta 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd está incluído na resposta. Além do status HTTP 201, o state de enqueued significa que a solicitação foi bem-sucedida.

HTTP/1.1 201 Created

{
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

Etapa 2: acessar o status da consulta

Para solicitar o status da consulta, envie uma solicitação GET para a API Queries. Você insere o ID da consulta retornado da chamada POST. Exemplo:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Exemplos de respostas:

Se a consulta ainda estiver em andamento, você receberá uma resposta como esta, em que state é running:

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

Depois que a consulta for concluída, você verá uma resposta como esta, em que state está definido como completed:

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

Etapa 3: recuperar os resultados da consulta

Depois que o status da consulta for completed, será possível usar dois métodos para recuperar os resultados dela:

  • getResulturl (recomendado): esse é um método mais recente que retorna um URL em que é possível conferir os resultados da consulta. Ele não tem limite de tamanho nos resultados de uma consulta.
  • getResult: esse é um método mais antigo para fazer o download de um arquivo ZIP que contém os resultados da consulta. Esse método impõe um limite de tamanho de 32 MB aos resultados de uma consulta.

As guias abaixo mostram chamadas de API para recuperar os resultados da consulta usando qualquer um dos métodos. Como mostrado acima, o ID da consulta é 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID/resulturl" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Confira a seguir um exemplo de resposta para a chamada:

{
  "urls": [
    "uri": "https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T181309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7",
  "md5": "23db6982caef9e9152f1a5b2589e6ca3",
  "sizeBytes": 1024
  ]
}

A resposta contém uma lista de urls[] com os seguintes campos:

  • uri: uma string que é o URL assinado dos dados JSON do relatório. Confira o relatório no URL.
  • md5: o hash MD5 dos dados JSON.
  • sizeBytes: o tamanho do arquivo retornado em bytes.

Consulte Sobre os resultados da consulta para conferir um exemplo de resultado no formato JSON.

getResult

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID/result" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

Para recuperar o arquivo do download, você precisa configurar a ferramenta usada de modo que ela salve esses arquivos no seu sistema. Por exemplo:

  • Se você usa cURL, pode usar as opções -O -J, como mostrado acima.
  • Se você usa Postman, precisa selecionar o botão Save and Download. Nesse caso, um arquivo ZIP chamado response é transferido por download.
  • Se você usa o navegador Chrome, o download é aceito automaticamente.

Se a solicitação for bem-sucedida e houver um conjunto de resultados diferente de zero, o download do resultado será feito no cliente como um arquivo JSON (delimitado por nova linha) compactado. O nome do arquivo baixado será OfflineQueryResult-.zip.

Por exemplo, OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip .

O arquivo ZIP contém um arquivo .gz dos resultados do JSON. Para acessar o arquivo JSON, descompacte o arquivo de download e use o comando gzip para extrair o arquivo JSON:

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

Sobre o corpo da solicitação

Nesta seção, descrevemos cada um dos parâmetros que é possível usar no corpo da solicitação JSON em uma consulta. Veja mais detalhes sobre as métricas e dimensões que podem ser usadas na consulta em Referência do Analytics.

{
   "metrics":[
      {
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_display_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}
Propriedade Descrição Obrigatória?
metrics

Matriz de métricas. É possível especificar uma ou mais métricas na consulta que cada métrica inclui. Apenas o nome da métrica é obrigatório:

  • name: (obrigatório) o nome da métrica conforme definido pela tabela em métricas.
  • function: (opcional) a função de agregação como avg, min, max ou sum.

    Algumas métricas não aceitam todas as funções de agregação. A documentação sobre métricas inclui uma tabela que especifica o nome da métrica e a função (avg, min, max, sum) que ela aceita.

  • alias: (opcional) o nome da propriedade que contém os dados da métrica na saída. Se omitido, o padrão é o nome da métrica combinado com o nome da função de agregação.
  • operator: (opcional) uma operação que será realizada na métrica após o cálculo do valor. Funciona com a propriedade value. As operações aceitas incluem: + - / % *.
  • value: (opcional) o valor aplicado à métrica calculada pelo operator especificado.

As propriedades operator e value definem uma operação de pós-processamento realizada com base na métrica. Por exemplo, se você especificar a métrica response_processing_latency, ela retornará a latência média de processamento de resposta com uma unidade de milissegundos. Para converter as unidades em segundos, defina operator como "/" e value como ”1000.0“:


"metrics":[
  {
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

Para mais informações, consulte a Referência de métricas, dimensões e filtros do Analytics.

Sim
dimensions Matriz de dimensões para agrupar as métricas. Para mais informações, consulte a lista de dimensões compatíveis. É possível especificar várias dimensões. Sim
timeRange Período da consulta.

É possível usar as seguintes strings predefinidas para especificar o período:

  • last60minutes
  • last24hours
  • last7days

Se preferir, especifique timeRange como uma estrutura que descreve os carimbos de data/hora de início e de término no formato ISO: yyyy-mm-ddThh:mm:ssZ. Por exemplo:


"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}
Sim
limit Número máximo de linhas que podem ser retornadas no resultado. Não
filter Expressão booleana que pode ser usada para filtrar dados. As expressões de filtro podem ser combinadas com termos AND/OR e devem ser colocadas entre parênteses para evitar ambiguidade. Consulte a Referência de métricas, dimensões e filtros do Analytics para mais informações sobre os campos disponíveis para filtragem. Para mais informações sobre os tokens que você usa para criar expressões de filtro, consulte Sintaxe da expressão de filtro. Não
groupByTimeUnit Unidade de tempo usada para agrupar o conjunto de resultados. Os valores válidos incluem: second, minute, hour, day, week ou month.

Se uma consulta incluir groupByTimeUnit, o resultado será uma agregação com base na unidade de tempo especificada e o carimbo de data/hora resultante não incluirá a precisão em milissegundos. Se uma consulta omitir groupByTimeUnit, o carimbo de data/hora resultante incluirá a precisão em milissegundos.

Não
outputFormat Formato da saída. Os valores válidos incluem csv ou json. O padrão é json correspondente ao JSON delimitado por nova linha.

Observação: configure o delimitador para a saída CSV usando a propriedade csvDelimiter.

Não
csvDelimiter Delimitador usado no arquivo CSV, se outputFormat estiver definido como csv. O padrão é o caractere , (vírgula). Os caracteres delimitadores aceitos são vírgula (,), barra vertical (|) e tabulação (\t). Não

Sintaxe da expressão do filtro

Nesta seção de referência, descrevemos os tokens que podem ser usados para criar expressões de filtro no corpo da solicitação. Por exemplo, a expressão a seguir usa o token "ge" (maior ou igual a):

"filter":"(message_count ge 0)"
Token Descrição Exemplos
in Incluir na lista

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

Observação: as strings precisam estar entre aspas.

notin Excluir da lista

(response_status_code notin 400,401,500,501)
eq Igual a (==)

(response_status_code eq 504)

(apiproxy eq 'non-prod')
ne Diferente de (!=)

(response_status_code ne 500)

(apiproxy ne 'non-prod')
gt Maior que (>)

(response_status_code gt 500)
lt Menor que (<)

(response_status_code lt 500)
ge Maior que ou igual a (>=)

(target_response_code ge 400)
le Menor que ou igual a (<=)

(target_response_code le 300)
like Retorna verdadeiro se o padrão de string corresponder ao padrão fornecido.

O exemplo à direita corresponde da seguinte maneira:

- qualquer valor que tenha a palavra "buy"

- qualquer valor que termine em "item"

- qualquer valor que comece com "Prod"

- qualquer valor que comece com 4. Observe que response_status_code é numérico


(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')
not like Retorna falso se o padrão de string corresponder ao padrão fornecido.

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')
and Permite que você use a lógica "and" para incluir mais de uma expressão de filtro. O filtro inclui os dados que atendem a todas as condições.

(target_response_code gt 399) and (response_status_code ge 400)