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:

Enviar a consulta.
Acessar o status da consulta.
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.

Por 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. Por exemplo:

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

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.

`getResulturl` (recomendado)

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

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"

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.

Observação: um arquivo zip é salvo porque, para arquivos muito grandes, a Apigee leva muito tempo para combinar os resultados. Portanto, por motivos de desempenho, a Apigee retorna um arquivo ZIP que consiste nas partes do resultado. Para evitar isso, use o método getResulturl.

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ório?
`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)
`or`	Permite que você use a lógica "or" para avaliar diferentes expressões de filtro possíveis. O filtro inclui os dados que atendem a pelo menos uma das condições.	(response_size ge 1000) or (response_status_code eq 500)

Restrições e padrões

Veja a seguir uma lista de restrições e padrões para o recurso de processamento de consulta assíncrona.

Restrição	Padrão	Descrição
Limite de chamadas de consulta	Consulte a descrição	É possível fazer até sete chamadas por hora à API /queries da Apigee para iniciar um relatório assíncrono. Se você exceder a cota de chamada, a API retornará uma resposta HTTP 429.
Limite de consultas ativas	10	É possível ter até 10 consultas ativas em uma organização/ambiente.
Limite de tempo de execução da consulta	6 horas	As consultas que levam mais de seis horas serão encerradas.
Período da consulta	Consulte a descrição	O período máximo permitido para uma consulta é de 365 dias.
Limite de dimensões e métricas	25	O número máximo de dimensões e métricas que é possível especificar no payload da consulta.

Sobre os resultados da consulta

Veja a seguir um exemplo de resultado no formato JSON. A forma como você visualiza os resultados depende do método usado para recuperar os resultados da consulta:

Se você usou o método getResulturl, é possível conferir os resultados no URL fornecido no campo uri do resultado. Esse método não tem limite de tamanho nos resultados de uma consulta.
Se você usou o método getResult, os resultados são transferidos por download em um arquivo ZIP.

O método getResult impõe um limite de tamanho de 32 MB aos resultados de uma consulta. Se os resultados excederem 32 MB, a consulta retornará um código de status 400 com a mensagem "o resultado da consulta é maior que 32 MB". Para evitar esse limite, use o método getReulturl, conforme descrito em Recuperar os resultados da consulta.

Os resultados consistem em linhas JSON separadas por um novo delimitador de linha, conforme mostrado no seguinte exemplo:

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

É possível buscar os resultados do URL até a expiração dos dados no repositório. Consulte Restrições e padrões.

Exemplos

Exemplo 1: soma das contagens de mensagens

Consulta da soma das contagens de mensagens nos últimos 60 minutos.

Consulta

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

Corpo da solicitação de last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

Exemplo 2: período personalizado

Consulta que usa um período personalizado.

Consulta

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

Corpo da solicitação de custom-timerange.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Exemplo 3: transações por minuto

Consulta com base na métrica de transações por minuto (tpm).

Consulta

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

Corpo da solicitação de tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

Resultado de amostra

Trecho do arquivo de resultados:

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

Exemplo 4: como usar uma expressão de filtro

Consulta com uma expressão de filtro que usa um operador booleano.

Consulta

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

Corpo da solicitação de filterCombo.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Exemplo 5: expressão de passagem no parâmetro de métricas

Consulta com uma expressão passada como parte do parâmetro de métricas. Somente é possível usar expressões simples de operador único.

Consulta

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

Corpo da solicitação de metricsExpression.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

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

Comparação da API Reports com a IU

Limite de tempo em consultas

Como fazer uma consulta de análise assíncrona

Etapa 1. enviar a consulta

Etapa 2. acessar o status da consulta

Etapa 3. recuperar os resultados da consulta

getResulturl (recomendado)

getResult

Sobre o corpo da solicitação

Sintaxe da expressão do filtro

Restrições e padrões

Sobre os resultados da consulta

Exemplos

Exemplo 1: soma das contagens de mensagens

Exemplo 2: período personalizado

Exemplo 3: transações por minuto

Exemplo 4: como usar uma expressão de filtro

Exemplo 5: expressão de passagem no parâmetro de métricas

`getResulturl` (recomendado)

`getResult`