Usa la API de informes personalizados asíncronos

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Información

Edge Analytics proporciona un amplio conjunto de paneles interactivos, generadores de informes personalizados y funciones relacionadas. Sin embargo, el propósito de estas funciones es que sean interactivas: debes enviar una solicitud a la API o a la IU y la solicitud se bloqueará hasta que el servidor de análisis proporcione una respuesta.

Sin embargo, es posible que se agote el tiempo de espera de las solicitudes de estadísticas si tardan demasiado en completarse. Si una solicitud de consulta necesita procesar una gran cantidad de datos (por ejemplo, cientos de GB), es posible que falle debido a un tiempo de espera agotado.

El procesamiento de consultas asíncronas te permite consultar conjuntos de datos muy grandes y recuperar los resultados más adelante. Puedes considerar el uso de una consulta sin conexión cuando descubras que tus consultas interactivas agotan el tiempo de espera. Algunos casos en los que el procesamiento de consultas asíncronas puede ser una buena alternativa incluyen los siguientes:

• Análisis y creación de informes que abarquen intervalos grandes
• Análisis de datos con una variedad de dimensiones de agrupación y otras restricciones que agregan complejidad a la consulta.
• Administración de consultas cuando se descubre que los volúmenes de datos aumentaron de forma significativa para algunos usuarios u organizaciones.

En este documento, se describe cómo iniciar una consulta asíncrona mediante la API. También puedes usar la IU, como se describe en Ejecuta un informe personalizado.

Compara la API de informes con la IU

En Crear y administrar informes personalizados, se describe cómo usar la IU de Edge para crear y ejecutar informes personalizados. Puedes ejecutar esos informes de forma síncrona o asíncrona.

La mayoría de los conceptos para generar informes personalizados con la IU se aplican al uso de la API. Es decir, cuando creas informes personalizados con la API, especificas las metrics, las dimensiones y los filtros integrados en Edge, así como cualquier métrica personalizada que hayas creado con la política de Statistics Collector.

Las diferencias principales entre los informes generados en la IU y en la API son que los informes generados con la API se escriben en archivos CSV o JSON (delimitados por saltos de línea) en lugar de un informe visual en la IU.

Límites en Apigee Hybrid

Apigee Hybrid aplica un límite de tamaño de 30 MB para el conjunto de datos resultante.

Cómo realizar una consulta de análisis asíncrono

Haz consultas de estadísticas asíncronas en tres pasos:

1. Envía la consulta

2. Obtén el estado de la consulta

3. Recupera los resultados de la consulta

Paso 1. Envía la consulta

Debes enviar una solicitud POST a la API de /queries. Esta API le indica a Edge que procese tu solicitud en segundo plano. Si el envío de la consulta se realiza correctamente, la API muestra un estado 201 y un ID que utilizarás para hacer referencia a la consulta en pasos posteriores.

Por ejemplo:

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

El cuerpo de la solicitud es una descripción JSON de la consulta. En el cuerpo JSON, especifica las metrics, las dimensiones y los filtros que definen el informe.

A continuación, se muestra un ejemplo de archivo json-query-file:

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

Consulta Información sobre el cuerpo de la solicitud a continuación para obtener una descripción completa de su sintaxis.

Respuesta de muestra:

Ten en cuenta que el ID de la consulta 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd se incluye en la respuesta. Además del estado HTTP 201, el state de enqueued significa que la solicitud se realizó de forma correcta.

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",
}

Paso 2. Obtén el estado de la consulta

Realiza una llamada GET para solicitar el estado de la consulta. Proporciona el ID de consulta que se mostró en la llamada POST. Por ejemplo:

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

Ejemplos de respuesta:

Si la consulta aún está en curso, obtendrás una respuesta como esta, en la que el state está en 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"
}

Una vez que la consulta se complete de forma correcta, verás una respuesta como esta, en la que state está configurado 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"
}

Paso 3. Recupera los resultados de la consulta

Una vez que el estado de la consulta sea completed, puedes usar la API de obtener resultados para recuperar los resultados, en los que el ID de la consulta vuelve a ser 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

Con el fin de recuperar el archivo descargado, debes configurar la herramienta que usas para que guarde un archivo descargado en tu sistema. Por ejemplo:

• Si usas cURL, puedes usar las opciones de -O -J, como se muestra arriba.

• Si usas Postman, debes seleccionar el botón Guardar y descargar. En este caso, se descarga un archivo ZIP llamado response.

• Si usas el navegador Chrome, la descarga se acepta automáticamente.

Si la solicitud se realiza correctamente y hay un conjunto de resultados que no es cero, el resultado se descarga al cliente como un archivo JSON comprimido (delimitado por saltos de línea). El nombre del archivo descargado será el siguiente:

OfflineQueryResult-<query-id>.zip

Por ejemplo:

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

El archivo ZIP contiene un archivo .gz de los resultados de JSON. Para acceder al archivo JSON, descomprime el archivo y, luego, usa el comando gzip a fin de extraerlo:

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

Información del cuerpo de la solicitud

En esta sección, se describe cada uno de los parámetros que puedes usar en el cuerpo de la solicitud JSON para una consulta. Si deseas obtener detalles sobre las métricas y dimensiones que puedes usar en tu consulta, revisa la referencia de 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"
}

Sintaxis de la expresión de filtro

En esta sección de referencia, se describen los tokens que puedes usar para compilar expresiones de filtro en el cuerpo de la solicitud. Por ejemplo, la siguiente expresión usa el token “ge” (mayor o igual que):

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

Restricciones y valores predeterminados

A continuación, se muestra una lista de restricciones y valores predeterminados para la función de procesamiento de consultas asíncronas.

Información acerca de los resultados de la consulta

El siguiente es un resultado de ejemplo en formato JSON. El resultado consiste en filas de JSON separadas por un nuevo delimitador de línea:

{"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"}    
…

Puedes recuperar los resultados de la URL hasta el vencimiento de los datos en el repositorio. Consulta Restricciones y valores predeterminados.

Ejemplos

Ejemplo 1: Suma de la cantidad de mensajes

La consulta de la suma de recuentos de mensajes de los ú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

Cuerpo de la solicitud de last60minutes.json

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

Ejemplo 2: Intervalo personalizado

Consulta mediante un intervalo 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

Cuerpo de la solicitud de 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"
   }
}

Ejemplo 3: Transacciones por minuto

Consulta la métrica por transacciones 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

Cuerpo de la solicitud 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 muestra

Salto del archivo 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"}
...

Ejemplo 4: Usa una expresión de filtro

Consulta con una expresión de filtro que use un 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

Cuerpo de la solicitud 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"
   }
}

Ejemplo 5: Pasa una expresión en el parámetro de las métricas

Consulta con una expresión que se pasa como parte del parámetro de métricas. Solo puedes usar expresiones simples de un operador.

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

Cuerpo de la solicitud de metricsExpression.json

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

Cómo realizar una consulta de informe de monetización asíncrona

Puedes capturar todas las transacciones de monetización exitosas dentro de un período determinado para un conjunto específico de criterios. Con ese objetivo, sigue los pasos que se describen en esta sección.

Al igual que con las consultas asíncronas de Analytics, puedes realizar consultas asíncronas de informes de monetización en tres pasos: (1) enviar la consulta, (2) obtener su estado y (3) recuperar los resultados.

A continuación, se describe el Paso 1, envíar la consulta.

Los pasos 2 y 3 son exactamente los mismos que para las consultas de estadísticas asíncronas. Para obtener más información, consulta Cómo realizar una consulta de estadísticas asíncrona.

Para enviar una consulta de un informe de monetización asíncrona, envía una solicitud POST a /mint/organizations/org_id/async-reports.

De manera opcional, puedes especificar el entorno pasando el parámetro de consulta environment. Si no se especifica, el parámetro de consulta predeterminado es prod. Por ejemplo:

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

En el cuerpo de la solicitud, especifica los siguientes criterios de búsqueda.

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

Por ejemplo, la siguiente solicitud genera un informe de monetización asíncrono correspondiente al mes de junio de 2017 para el producto de API y el ID de desarrollador especificados. Las fechas y horas de fromDate y toDate se indican en UTC/GMT y pueden incluir horarios.

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