Usar a API de relatórios personalizados assíncronos

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O Edge 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á falhar por causa de um tempo limite.

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 consultas assíncronas 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 artigo Criar e gerenciar relatórios personalizados descreve como usar a IU do Edge 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 metrics, dimensões e filtros integrados ao Edge e qualquer métrica personalizada criada usando a política Statisticscollector.

As principais diferenças entre os relatórios gerados na interface e na API são que os relatórios gerados com a API são gravados em arquivos CSV ou JSON (delimitados por nova linha), e não em um relatório visual exibido na interface.

Limites na Apigee híbrida

A Apigee híbrida aplica um limite de tamanho de 30 MB ao conjunto de dados de resultado.

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 para a API /queries. Essa API instrui o Edge a processar a solicitação em segundo plano. Se o envio da consulta for bem-sucedido, a API retornará um status 201 e um ID que você usará para se referir à consulta nas etapas posteriores.

Exemplo:

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

O corpo da solicitação é uma descrição JSON da consulta. No corpo do JSON, especifique as metrics, 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 ver 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

Faça uma chamada GET para solicitar o status da consulta. Você insere o ID da consulta retornado da chamada POST. Exemplo:

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

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, use a API get results para recuperar os resultados, em que o ID da consulta é novamente 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

Para recuperar o arquivo do download, você precisa configurar a ferramenta usada de modo que ela salve esses arquivos no seu sistema. 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 salvo será:

OfflineQueryResult-<query-id>.zip

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_dispaly_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 metrics.
  • 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 metrics 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.

Não
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. Não
timeRange Período da consulta.

Use as strings predefinidas a seguir 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. 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 ou igual a (>=))
(target_response_code ge 400)
le Menor 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 ao seguinte:

- 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; note 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 de gerenciamento /queries 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 levarem mais de 6 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 saída consiste em linhas JSON separadas por um delimitador de nova linha:

{"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 -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Corpo da solicitação do 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 -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Corpo da solicitação do last60minutes.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 -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

Corpo da solicitação do 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 -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

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 -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

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 fazer uma consulta assíncrona ao relatório de monetização

É possível capturar todas as transações de monetização bem-sucedidas em um determinado período para um conjunto específico de critérios usando as etapas descritas nesta seção.

Assim como acontece com as consultas de análise assíncronas, você realiza consultas assíncronas de relatórios de monetização em três etapas: (1) envie a consulta, (2) receba o status da consulta e (3) recupere os resultados da consulta.

Veja abaixo a etapa 1, como enviar a consulta.

As etapas 2 e 3 são iguais às consultas de análises assíncronas. Para mais informações, consulte Como fazer uma consulta de análise assíncrona.

Para enviar uma consulta para um relatório de monetização assíncrono, emita uma solicitação POST para /mint/organizations/org_id/async-reports.

Opcionalmente, é possível especificar o ambiente transmitindo o parâmetro de consulta environment. Se não for especificado, o parâmetro de consulta será prod por padrão. Exemplo:

/mint/organizations/org_id/async-reports?environment=prod

No corpo da solicitação, especifique os seguintes critérios de pesquisa.

Nome Descrição Padrão Obrigatório?
appCriteria ID e organização de um aplicativo específico a ser incluído no relatório. Se esta propriedade não for especificada, todos os aplicativos serão incluídos no relatório. N/A Não
billingMonth Mês de faturamento do relatório, como JULHO. N/A Sim
billingYear Ano de faturamento do relatório, como 2015. N/A Sim
currencyOption Moeda do relatório. Alguns dos valores válidos são:
  • LOCAL: cada linha do relatório é exibida usando o plano de tarifas aplicável. Isso significa que pode haver várias moedas em um relatório se os desenvolvedores tiverem planos que usam moedas diferentes.
  • EUR: as transações na moeda local são convertidas e exibidas em euros.
  • GPB: as transações em moeda local são convertidas e exibidas em libras no Reino Unido.
  • USD: as transações em moeda local são convertidas e exibidas em dólares americanos.

Se você selecionar EUR, GBP ou USD, o relatório exibirá todas as transações que usam essa moeda única com base na taxa de câmbio em vigor na data da transação.

N/A Não
devCriteria

ID do desenvolvedor ou endereço de e-mail e nome da organização de um desenvolvedor específico que serão incluídos no relatório. Se esta propriedade não for especificada, todos os desenvolvedores serão incluídos no relatório.

Exemplo:

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
N/A Não
fromDate Data de início do relatório em UTC. N/A Sim
monetizationPakageIds ID de um ou mais pacotes de API a serem incluídos no relatório. Se essa propriedade não for especificada, todos os pacotes de API serão incluídos no relatório. N/A Não
productIds ID de um ou mais produtos da API a serem incluídos no relatório. Se essa propriedade não for especificada, todos os produtos da API serão incluídos no relatório. N/A Não
ratePlanLevels

Tipo de plano de preços a ser incluído no relatório. Valores válidos:

  • DEVELOPER: plano de taxas do desenvolvedor
  • STANDARD: plano de taxas padrão

Se essa propriedade não for especificada, os planos de taxa padrão e de desenvolvedor específicos serão incluídos no relatório.

N/A Não
toDate Data de término do relatório em UTC. N/A Sim

Por exemplo, a solicitação a seguir gera um relatório de monetização assíncrono para o mês de junho de 2017 referente ao produto da API e ao ID do desenvolvedor especificados. Denunciar fromDate e toDate datas e horários estão em UTC/GMT e podem incluir horários.

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password