Usa la API de informes personalizados asíncronos

Estás viendo la documentación de Apigee Edge.
Ve a la documentación de Apigee X. info

Edge Analytics proporciona un amplio conjunto de paneles interactivos, generadores de informes personalizados y las funciones que están 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, 100 s de GB), puede fallar debido a que se agota el tiempo de espera.

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 Crea y administra 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 métricas, dimensiones y filtros integrados en Edge, así como las métricas personalizadas que creaste con la política StatisticsCollector.

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 estadísticas asíncrona

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 usará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 métricas, 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 del cuerpo de la solicitud a continuación para obtener una descripción completa de la sintaxis del cuerpo de la solicitud.

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 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. Para obtener más detalles sobre las métricas y dimensiones que puedes usar en tu consulta, consulta 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 de estadísticas asíncronas, puedes realizar consultas de informes de monetización asíncronas en tres pasos: (1) enviar la consulta, (2) obtener el estado de la consulta y (3) recuperar los resultados de las consultas.

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 análisis asíncrono.

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 para el mes de junio de 2017 para el producto de API y el ID de desarrollador especificados. Las fechas y horas de los informes fromDate y toDate están en UTC/GMT y pueden incluir horas.

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