Usar a API de relatórios personalizados assíncronos

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

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á 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 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 documento Criar e gerenciar relatórios personalizados descreve como usar a interface 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 métricas, dimensões e filtros integrados ao Edge, e quaisquer métricas personalizadas criadas usando a política StatisticsCollector.

As principais diferenças entre os relatórios gerados na IU 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), em vez de um relatório visual exibido na IU.

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 sua solicitação em segundo plano. Se o envio da consulta for bem-sucedido, a API vai retornar o status 201 e um ID que você vai usar para se referir à consulta em 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 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

Faça uma chamada GET para solicitar o status da consulta. Você insere o ID da consulta retornado da chamada POST. Por 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, será possível usar 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. 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 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"
}

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

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

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)"

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

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(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.

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ê faz consultas de relatório de monetização assíncronas em três etapas: (1) envia a consulta, (2) recebe o status da consulta e (3) recupera 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. Por exemplo:

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

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

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

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