Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
Apigee Analytics ofrece un amplio conjunto de paneles interactivos, generadores de informes personalizados y funciones relacionadas. Sin embargo, estas funciones están diseñadas para ser interactivas: envías una solicitud de API o de interfaz de usuario y la solicitud se bloquea hasta que el servidor de analíticas proporciona una respuesta.
Sin embargo, las solicitudes de analíticas pueden agotar el tiempo de espera si tardan demasiado en completarse. Si una solicitud de consulta necesita procesar una gran cantidad de datos (por ejemplo, cientos de GB), puede fallar debido a un tiempo de espera agotado.
El procesamiento de consultas asíncronas le permite consultar conjuntos de datos muy grandes y obtener los resultados más adelante. Puedes usar una consulta sin conexión cuando veas que tus consultas interactivas agotan el tiempo de espera. Estas son algunas situaciones en las que el procesamiento de consultas asíncrono puede ser una buena alternativa:
- Analizar y crear informes que abarquen intervalos de tiempo grandes.
- Analizar datos con varias dimensiones de agrupación y otras restricciones que añaden complejidad a la consulta.
- Gestionar las consultas cuando detectes que el volumen de datos ha aumentado significativamente en el caso de algunos usuarios u organizaciones.
En este documento se describe cómo iniciar una consulta asíncrona mediante la API. También puede usar la interfaz de usuario, como se describe en el artículo Generar un informe personalizado.
Comparación de la API Reports con la interfaz de usuario
En Crear y gestionar informes personalizados se describe cómo usar la interfaz de usuario de Apigee para crear y ejecutar informes personalizados. Puede generar esos informes de forma síncrona o asíncrona.
La mayoría de los conceptos para generar informes personalizados con la interfaz de usuario se aplican al uso de la API. Es decir, al crear informes personalizados con la API, debe especificar las métricas, las dimensiones y los filtros integrados en Apigee.
La principal diferencia entre los informes generados con la API y los que se generan con la interfaz de usuario es que los primeros se escriben en archivos CSV o JSON (delimitados por saltos de línea), mientras que los segundos se muestran en la interfaz de usuario.
Límite de tiempo de las consultas
Apigee aplica un máximo de 365 días al intervalo de tiempo de una consulta asíncrona.
Cómo hacer una consulta analítica asíncrona
Para hacer consultas analíticas asíncronas, siga estos tres pasos:
Paso 1. Enviar la consulta
Debes enviar una solicitud POST a la API Queries. Esta API indica a Apigee que procese tu solicitud en segundo plano. Si la consulta se envía correctamente, la API devuelve el estado 201 y un ID que usarás para hacer referencia a la consulta en pasos posteriores.
Por ejemplo:
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
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
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 la sección Acerca del cuerpo de la solicitud más abajo para ver una descripción completa de la sintaxis del cuerpo de la solicitud.
Respuesta de ejemplo:
Ten en cuenta que el ID de 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 ha completado correctamente.
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: Obtener el estado de la consulta
Para solicitar el estado de la consulta, envía una solicitud GET a la API Queries. Proporciona el ID de consulta que se devolvió en la llamada POST. Por ejemplo:
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID" \ -X GET \ -H "Authorization: Bearer $TOKEN"
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
Respuestas de ejemplo:
Si la consulta sigue en curso, recibirás una respuesta como esta, donde state
es 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 haya completado correctamente, verás una respuesta como esta, donde state
se ha 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"
}
Paso 3: Recuperar los resultados de la consulta
Cuando el estado de la consulta sea completed
, podrá utilizar dos métodos para obtener los resultados:
getResulturl
(recomendado): este es un método más reciente que devuelve una URL en la que puedes ver los resultados de la consulta. Este método no tiene límite de tamaño en los resultados de una consulta.getResult
: este es un método antiguo que descarga un archivo zip que contiene los resultados de la consulta. Este método aplica un límite de tamaño de 32 MB a los resultados de una consulta.
En las pestañas de abajo se muestran las llamadas a la API para obtener los resultados de la consulta con cada método. Como se ha indicado anteriormente, el ID de consulta es 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"
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
A continuación se muestra un ejemplo de respuesta a la llamada:
{ "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 ] }
La respuesta contiene una lista urls[]
con los siguientes campos:
uri
: cadena que es la URL firmada de los datos JSON del informe. Puede consultar el informe en la URL.md5
: el hash MD5 de los datos JSON.sizeBytes
: el tamaño del archivo devuelto en bytes.
Consulta Información sobre los resultados de las consultas para ver un ejemplo de resultado en formato JSON.
getResult
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID/result" \ -X GET \ -H "Authorization: Bearer $TOKEN"
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
Para recuperar el archivo descargado, debes configurar la herramienta que utilices para que guarde el archivo descargado en tu sistema. Por ejemplo:
- Si usas cURL, puedes usar las opciones
-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 distinto de cero, el resultado se descarga en el cliente como un archivo JSON comprimido (delimitado por saltos de línea). El nombre del archivo descargado será OfflineQueryResult-
.
Por ejemplo: OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
.
El archivo ZIP contiene un archivo .gz de los resultados JSON. Para acceder al archivo JSON, descomprime el archivo descargado y, a continuación, usa el comando gzip
para extraer el archivo JSON:
unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz
Acerca 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 de una consulta. Para obtener información sobre las métricas y dimensiones que puede usar en su consulta, consulte la referencia de 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" }
Propiedad | Descripción | ¿Es obligatorio? |
---|---|---|
metrics
|
Array de métricas. Puede especificar una o varias métricas en una consulta, donde cada métrica incluye lo siguiente: Solo es necesario indicar el nombre de la métrica:
Las propiedades "metrics":[ { "name":"response_processing_latency", "function":"avg", "alias":"average_response_time_in_seconds", "operator":"/", "value":"1000" } ] Para obtener más información, consulte la referencia de las métricas, dimensiones y filtros de analíticas. |
Sí |
dimensions
|
Matriz de dimensiones por las que agrupar las métricas. Para obtener más información, consulta la lista de dimensiones admitidas. Puedes especificar varias dimensiones. | Sí |
timeRange
|
Intervalo de tiempo de la consulta.
Puede usar las siguientes cadenas predefinidas para especificar el intervalo de tiempo:
También puedes especificar el "timeRange": { "start": "2018-07-29T00:13:00Z", "end": "2018-08-01T00:18:00Z" } |
Sí |
limit
|
Número máximo de filas que se pueden devolver en el resultado. | No |
filter
|
Expresión booleana que se puede usar para filtrar datos. Las expresiones de filtro se pueden combinar con los términos AND y OR, y deben incluirse entre paréntesis para evitar ambigüedades. Consulte la referencia de las métricas, dimensiones y filtros de analíticas para obtener más información sobre los campos por los que puede filtrar. Para obtener más información sobre los tokens que se usan para crear expresiones de filtro, consulta Sintaxis de las expresiones de filtro. | No |
groupByTimeUnit
|
Unidad de tiempo usada para agrupar el conjunto de resultados. Los valores válidos son second , minute , hour , day , week o month .
Si una consulta incluye |
No |
outputFormat
|
Formato de salida. Los valores válidos son csv o json . El valor predeterminado es json
, que corresponde a JSON delimitado por líneas nuevas.
Nota: Configura el delimitador de la salida CSV mediante la propiedad |
No |
csvDelimiter
|
Delimitador usado en el archivo CSV, si outputFormat se define como csv . El valor predeterminado es el carácter , (coma). Los caracteres delimitadores admitidos son la coma (, ), la barra vertical (| ) y la tabulación (\t ).
|
No |
Sintaxis de las expresiones de filtro
En esta sección de referencia se describen los tokens que puede usar para crear 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)"
Token | Descripción | Ejemplos |
---|---|---|
in
|
Incluir en la lista | (apiproxy in 'ethorapi','weather-api') (apiproxy in 'ethorapi') (apiproxy in 'Search','ViewItem') (response_status_code in 400,401,500,501) Nota: Las cadenas deben ir entre comillas. |
notin
|
Excluir de la lista | (response_status_code notin 400,401,500,501) |
eq
|
Igual a (==)
|
(response_status_code eq 504) (apiproxy eq 'non-prod') |
ne
|
No es igual a (!=)
|
(response_status_code ne 500) (apiproxy ne 'non-prod') |
gt
|
Mayor que (>)
|
(response_status_code gt 500) |
lt
|
Menos de (<)
|
(response_status_code lt 500) |
ge
|
Mayor o igual que (>=)
|
(target_response_code ge 400) |
le
|
Menor o igual que (<=)
|
(target_response_code le 300) |
like
|
Devuelve "true" si el patrón de cadena coincide con el patrón proporcionado.
El ejemplo de la derecha coincide de la siguiente manera: - cualquier valor que contenga la palabra "comprar" - cualquier valor que termine en "item" - cualquier valor que empiece por "Prod" - Cualquier valor que empiece por 4. Ten en cuenta que response_status_code es numérico.
|
(apiproxy like '%buy%') (apiproxy like '%item') (apiproxy like 'Prod%') |
not like
|
Devuelve false si el patrón de cadena coincide con el patrón proporcionado. | (apiproxy not like '%buy%') (apiproxy not like '%item') (apiproxy not like 'Prod%') |
and
|
Te permite usar la lógica "y" para incluir más de una expresión de filtro. El filtro incluye los datos que cumplen todas las condiciones. | (target_response_code gt 399) and (response_status_code ge 400) |
or
|
Le permite usar la lógica "o" para evaluar diferentes expresiones de filtro posibles. El filtro incluye datos que cumplen al menos una de las condiciones. | (response_size ge 1000) or (response_status_code eq 500) |
(response_size ge 1000 and response_status_code eq 500) or (developer_app eq 'api_prod')
En su lugar, cuando se combinen las lógicas "and" u "or", cada subcláusula debe incluirse entre paréntesis. Por ejemplo:
((response_size ge 1000) and (response_status_code eq 500)) or (developer_app eq 'api_prod')
Restricciones y valores predeterminados
A continuación se muestra una lista de las restricciones y los valores predeterminados de la función de procesamiento de consultas asíncronas.
Restricción | Predeterminado | Descripción |
---|---|---|
Límite de llamadas de consulta | Ver descripción | Puedes hacer hasta siete llamadas por hora a la API de Apigee /queries para iniciar un informe asíncrono. Si superas la cuota de llamadas, la API devuelve una respuesta HTTP 429. |
Límite de consultas activas | 10 | Puedes tener hasta 10 consultas activas por organización o entorno. |
Umbral de tiempo de ejecución de consultas | 6 horas | Las consultas que tarden más de 6 horas se cancelarán. |
Intervalo de tiempo de la consulta | Ver descripción | El intervalo de tiempo máximo permitido para una consulta es de 365 días. |
Límite de dimensiones y métricas | 25 | Número máximo de dimensiones y métricas que puede especificar en la carga útil de la consulta. |
Acerca de los resultados de la consulta
A continuación se muestra un ejemplo de resultado en formato JSON. La forma en que veas los resultados depende del método que hayas usado para obtener los resultados de la consulta:
- Si has usado el método
getResulturl
puedes ver los resultados en la URL que se indica en el campouri
del resultado. Este método no tiene límite de tamaño en los resultados de una consulta. Si has usado el método
getResult
, los resultados se descargarán en un archivo ZIP.El método
getResult
aplica un límite de tamaño de 32 MB a los resultados de una consulta. Si los resultados superan los 32 MB, la consulta devolverá un código de estado 400 con el mensaje "query result is larger than 32 MB" (el resultado de la consulta es superior a 32 MB). Para evitar este límite, usa el métodogetReulturl
, tal como se describe en Recuperar los resultados de la consulta.
Los resultados constan de filas JSON separadas por un delimitador de salto de línea, como se muestra en el siguiente ejemplo:
{"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 obtener los resultados de la URL hasta que caduquen los datos del repositorio. Consulta Restricciones y valores predeterminados.
Ejemplos
Ejemplo 1: Suma de recuentos de mensajes
Consulta la suma del número de mensajes de los ú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
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
Cuerpo de la solicitud de last60minutes.json
{
"metrics":[
{
"name":"message_count",
"function":"sum"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":"last60minutes"
}
Ejemplo 2: Periodo personalizado
Consultar por un periodo 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
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
Cuerpo de la solicitud 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"
}
}
Ejemplo 3: Transacciones por minuto
Consulta la métrica de transacciones 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
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
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 ejemplo
Fragmento 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: Usar una expresión de filtro
Consulta con una expresión de filtro que usa un 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
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
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: Transferencia de una expresión en el parámetro metrics
Consulta con una expresión que se transmite como parte del parámetro metrics. Solo puedes usar expresiones sencillas con un operador.
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
Donde $TOKEN
es tu token de acceso OAuth 2.0, tal como se describe en Obtener un token de acceso OAuth 2.0. Para obtener información sobre las opciones de curl
que se usan en este ejemplo, consulta Usar curl. Para ver una descripción de las variables de entorno que puedes usar, consulta Definir variables de entorno para solicitudes a la API de Apigee.
Cuerpo de la solicitud de metricsExpression.json
{
"metrics":[
{
"name":"message_count",
"function":"sum",
"operator":"/",
"value":"7"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":10,
"timeRange":"last60minutes"
}