Cómo exportar datos desde Analytics

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

Configura los permisos para los agentes de servicio asignados

A fin de configurar los permisos para los agentes de servicio asignados, prepárate para los cambios descritos anteriormente, sigue estos pasos.

  1. Ingresa el siguiente comando para buscar el nombre del agente de servicio de Google Cloud:
    curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/ORG" \
  -u email:password \
  | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

    fueron ORG tu organización. Esto muestra el nombre y el valor del agente de servicio, como se muestra a continuación:

    "property" : [
  {
   "name" : "serviceAgent.analytics",
   "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
   },
  2. Abre el panel de IAM en la consola de Google Cloud.
  3. Selecciona tu proyecto de Google Cloud.
  4. Haz clic en Agregar en la parte superior del panel IAM.
  5. En el campo Principales nuevas, ingresa el agente de servicio value que se mostró en el paso 1. Por ejemplo, el value que se muestra en el paso 1 es service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
  6. Haz clic en el botón +Agregar otro rol y agrega los siguientes roles:
    • Usuario de BigQuery
    • Administrador de almacenamiento
  7. Haz clic en Guardar.

Datos de Apigee Analytics

Apigee Analytics recopila y analiza un amplio espectro de datos que fluyen a través de tus API y proporciona herramientas de visualización, que incluyen paneles interactivos, informes personalizados y otras herramientas que identifican tendencias en el rendimiento del proxy de API. Ahora puedes desbloquear este contenido enriquecido si exportas los datos de estadísticas de Apigee Analytics a tu propio repositorio de datos, como Google Cloud Storage o Google BigQuery. Luego, puedes aprovechar las potentes capacidades de consulta y aprendizaje automático que ofrecen Google BigQuery y TensorFlow para realizar tu propio análisis de datos. También puedes combinar los datos de estadísticas exportados con otros datos, como registros web, para obtener estadísticas nuevas sobre tus usuarios, las API y las aplicaciones.

Exportar formato de datos

Exporta datos de estadísticas a uno de los siguientes formatos:

  • Valores separados por comas (CSV)

    El delimitador predeterminado es un carácter de coma (,). Los caracteres delimitadores admitidos incluyen coma (,), barra vertical (|) y tabulación (\t). Configura el valor con la propiedad csvDelimiter, como se describe en Referencia de la propiedad de la solicitud de exportación.

  • JSON (delimitado por saltos de línea)

    Permite usar el carácter de nueva línea como delimitador.

Los datos exportados incluyen todas las métricas y dimensiones de Analytics integradas en Edge, además de cualquier dato de estadísticas personalizado que agregues. Para obtener una descripción de los datos exportados, consulta la Referencia sobre las métricas, las dimensiones y los filtros de Analytics.

Puedes exportar datos de estadísticas a los siguientes repositorios de datos:

Descripción general del proceso de exportación

Los siguientes pasos resumen el proceso que se usa para exportar tus datos de estadísticas:

  1. Configura tu repositorio de datos (Cloud Storage o BigQuery) para la exportación de datos. Debes asegurarte de que tu repositorio de datos se haya configurado correctamente y que la cuenta de servicio que se usa para escribir los datos en el repositorio tenga los permisos correctos.

  2. Cree un almacén de datos que defina las propiedades del repositorio de datos (Cloud Storage o BigQuery) a la que se exportarán los datos, incluidas las credenciales que se usan para acceder a él.

    Cuando crea un almacén de datos, sube las credenciales del repositorio de datos a Vault Credentials para almacenarlas de forma segura. Luego, el mecanismo de exportación de datos usa esas credenciales para escribir datos en su repositorio.

  3. Usa la API de exportación de datos para iniciar la exportación de datos. La exportación de datos se ejecuta de forma asíncrona en segundo plano.

  4. Usa la API de exportación de datos para determinar cuándo se completará la exportación.

  5. Cuando se complete la exportación, accede a los datos exportados en tu repositorio de datos.

En las siguientes secciones, se describen esos pasos con más detalle.

Configura tu repositorio de datos

El mecanismo de exportación de datos de estadísticas escribe datos en Cloud Storage o BigQuery. Para que esa escritura ocurra, debes hacer lo siguiente:

  • Crear una cuenta de servicio de Google Cloud Platform
  • Configura la función de la cuenta de servicio para que pueda acceder a Cloud Storage o BigQuery.

Crea una cuenta de servicio para Cloud Storage o BigQuery

Una cuenta de servicio es un tipo de Cuenta de Google que pertenece a su aplicación en lugar de a un usuario individual. Luego, su aplicación usa la cuenta de servicio para acceder a un servicio.

Una cuenta de servicio tiene una clave de cuenta de servicio representada por una string JSON. Cuando crees el almacén de datos de Edge que define la conexión con tu repositorio de datos, debes pasarle esta clave. Luego, el mecanismo de exportación de datos usa la clave para acceder a su repositorio de datos.

La cuenta de servicio asociada con la clave debe ser propietaria de un proyecto de Google Cloud Platform y tener acceso de escritura al bucket de Google Cloud Storage. Para crear una clave de servicio y descargar la carga útil necesaria, consulta Crea y administra claves de cuentas de servicio en la documentación de Google Cloud Platform.

Por ejemplo, cuando descargues la clave por primera vez, tendrá el formato de un objeto JSON: 

{ 
  "type": "service_account", 
  "project_id": "myProject", 
  "private_key_id": "12312312", 
  "private_key": "-----BEGIN PRIVATE KEY-----\n...", 
  "client_email": "client_email@developer.gserviceaccount.com", 
  "client_id": "879876769876", 
  "auth_uri": "https://accounts.google.com/organizations/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2", 
  "client_x509_cert_url": "https://www.googleapis.com" 
}

Configura Google Cloud Storage

Antes de poder exportar datos a Google Cloud Storage:

  • Asegúrate de que las API de BigQuery y Cloud Resource Manager estén habilitadas en tu proyecto de Google Cloud Platform. Consulta Cómo habilitar las API para obtener instrucciones. Apigee usa la API de BigQuery para aprovechar las funciones de BigQuery Export cuando exporta a Cloud Storage y la API de Cloud Resource Manager para verificar el permiso antes de cada exportación.

  • Asegúrate de que la cuenta de servicio esté asignada a las siguientes funciones:

    • Usuario de trabajo de BigQuery
    • Creador de objetos de almacenamiento
    • Administrador de almacenamiento (obligatorio solo para probar el almacén de datos, como se describe en Cómo probar una configuración del almacén de datos) Si esta función es demasiado amplia, puedes agregar el permiso storage.buckets.get a una función existente).

    Como alternativa, si quieres modificar una función existente o crear una función personalizada, agrega los siguientes permisos a la función:

Configure Google BigQuery

Sigue estos pasos para exportar datos a Google BigQuery:

  • Asegúrate de que las API de BigQuery y Cloud Resource Manager estén habilitadas en tu proyecto de Google Cloud Platform. Consulta Cómo habilitar las API para obtener instrucciones. Apigee usa la API de Cloud Resource Manager para verificar los permisos antes de cada exportación.
  • Asegúrate de que la API de BigQuery esté habilitada en tu proyecto de Google Cloud Platform. Consulta Cómo habilitar o inhabilitar API para obtener instrucciones.

  • Asegúrate de que la cuenta de servicio esté asignada a las siguientes funciones:

    • Usuario de trabajo de BigQuery
    • Editor de datos de BigQuery

    Si deseas modificar una función existente o crear una función personalizada, agrega los siguientes permisos a la función:

    • bigquery.datasets.create
    • bigquery.datasets.get
    • bigquery.jobs.create
    • bigquery.tables.create
    • bigquery.tables.get
    • bigquery.tables.updateData

Cree un almacén de datos

El almacén de datos define la conexión con su repositorio de datos de exportación (Cloud Storage, BigQuery), incluidas las credenciales utilizadas para acceder al repositorio de datos.

Acerca de Vault de credenciales de Edge

Edge usa Vault de credenciales a fin de almacenar de forma segura las credenciales que se usan para acceder a tu repositorio de datos de exportación. Para que un servicio pueda acceder a las credenciales del Vault Credentials Vault, debe definir un consumidor de credenciales.

Cuando se crea un almacén de datos con la IU de Edge, como se describe a continuación, Edge crea de forma automática el consumidor que se usó para acceder a las credenciales.

Prueba una configuración del almacén de datos

Cuando crees el almacén de datos, Edge no probará ni validará que la configuración de credenciales y repositorio de datos sea válida. Eso significa que puede crear el almacén de datos y no detectar ningún error hasta que ejecute su primera exportación de datos.

También puedes probar la configuración del almacén de datos antes de crearla. Las pruebas son útiles porque los procesos de exportación de datos grandes pueden tardar mucho tiempo en ejecutarse. Prueba tus credenciales y la configuración del almacén de datos antes de comenzar a descargar grandes cantidades de datos para solucionar rápidamente cualquier problema con la configuración.

Si la prueba tiene éxito, cree el almacén de datos. Si la prueba falla, corrige los errores y vuelve a probar la configuración. Solo se creará el almacén de datos después de que las pruebas sean exitosas.

Para habilitar la función de prueba, debes hacer lo siguiente:

  • Asegúrate de que la API de Cloud Resource Manager esté habilitada en tu proyecto de Google Cloud Platform. Consulta Cómo habilitar o inhabilitar API para obtener instrucciones.

Cree un almacén de datos

Siga estos pasos para crear un almacén de datos en la IU:

  1. Acceda a https://apigee.com/edge como administrador de la organización y seleccione su organización.

    NOTA: Debes ser administrador de la organización de Edge para poder crear un almacén de datos.

  2. En la barra de navegación izquierda, seleccione Administrador > Almacenes de datos de Analytics. Se mostrará la página Analytics Datastore.

  3. Selecciona el botón + Agregar almacén de datos. Se te pedirá que selecciones el tipo de almacén de datos:

  4. Elija un tipo de destino de exportación de datos:

    • Google Cloud Storage
    • Google BigQuery

    Aparecerá la página de configuración:

  5. Ingresa el Nombre del almacén de datos.

  6. Selecciona una credencial que se use para acceder al repositorio de datos. Aparecerá una lista desplegable con las credenciales disponibles.

    Las credenciales son específicas de un tipo de repositorio de datos. Consulta Crea una cuenta de servicio para Cloud Storage o BigQuery si deseas obtener más información.

    • Si ya subiste las credenciales, selecciónalas en la lista desplegable. Asegúrate de seleccionar las credenciales adecuadas para el tipo de repositorio de datos.

    • Si agregas credenciales nuevas al almacén de datos, selecciona Agregar nueva. En el cuadro de diálogo, ingresa lo siguiente:

      1. El Nombre de las credenciales.
      2. El contenido de credenciales es la clave de cuenta de servicio JSON específica de su repositorio de datos, según se define en Cree una cuenta de servicio para Cloud Storage o BigQuery.
      3. Selecciona Crear.

  7. Ingresa las propiedades específicas del tipo de repositorio de datos:

    • Para Google Cloud Storage:
      Propiedad Descripción ¿Es obligatorio?
      ID de proyecto ID del proyecto de Google Cloud Platform.

      Para crear un proyecto de Google Cloud Platform, consulta Crea y administra proyectos en la documentación de Google Cloud Platform.

      		Sí
      Nombre del bucket Nombre del bucket en Cloud Storage al que deseas exportar los datos de estadísticas. El bucket debe existir antes de realizar una exportación de datos.

      Para crear un bucket de Cloud Storage, consulte Cómo crear bucket s de almacenamiento en la documentación de Google Cloud Platform.

      		Sí
      Ruta de acceso Directorio en el que se almacenan los datos de estadísticas en el bucket de Cloud Storage. Sí
    • Para BigQuery:
      Propiedad Descripción ¿Es obligatorio?
      ID de proyecto ID del proyecto de Google Cloud Platform.

      Para crear un proyecto de Google Cloud Platform, consulta Crea y administra proyectos en la documentación de Google Cloud Platform.

      		 Sí
      Nombre del conjunto de datos Nombre del conjunto de datos de BigQuery al que deseas exportar datos de estadísticas. Asegúrate de que el conjunto de datos se cree antes de solicitar la exportación de datos.

      Para crear un conjunto de datos de BigQuery, consulte Cómo crear y usar conjuntos de datos en la documentación de Google Cloud Platform.

      		 Sí
      Prefijo de la tabla Es el prefijo de los nombres de las tablas creadas para los datos estadísticos en el conjunto de datos de BigQuery. Sí

  8. Selecciona Probar conexión a fin de asegurarte de que se puedan usar las credenciales para acceder al repositorio de datos.

    Si la prueba se realiza correctamente, guarda tu almacén de datos.

    Si la prueba falla, corrige los problemas y vuelve a intentarlo. Mueve el mouse sobre el mensaje de error en la IU para mostrar información adicional en la información sobre la herramienta.

  9. Después de pasar la prueba de conexión, guarda el almacén de datos.

Modifica un almacén de datos

Siga estos pasos para modificar un almacén de datos:

  1. Acceda a https://apigee.com/edge como administrador de la organización y seleccione su organización.

  2. En la barra de navegación izquierda, seleccione Administrador > Almacenes de datos de Analytics. Se mostrará la página Analytics Datastore.

  3. Mueva el puntero del mouse sobre la columna Modificado del informe para modificarlo. Aparecerán los íconos editar y borrar.

  4. Edita o borra el almacén de datos.

  5. Si editó el almacén de datos, seleccione Probar conexión a fin de asegurarse de que se puedan usar las credenciales para acceder al almacén de datos.

    Si la prueba se realiza correctamente, puedes ver los datos de muestra en tu repositorio de datos.

    Si la prueba falla, corrige los problemas y vuelve a intentarlo.

  6. Después de pasar la prueba de conexión, actualiza el almacén de datos.

Exportar datos de estadísticas

Para exportar datos de estadísticas, envía una solicitud POST a la API de /analytics/exports. Pasa la siguiente información en el cuerpo de la solicitud:

  • Nombre y descripción de la solicitud de exportación
  • Período de los datos exportados (el valor solo puede abarcar un día)
  • Formato de los datos exportados
  • Nombre del almacén de datos
  • Si la monetización está habilitada en la organización

A continuación, se proporcionan ejemplos de solicitudes de exportación. Para obtener una descripción completa de las propiedades del cuerpo de la solicitud, consulta Referencia de la propiedad de la solicitud de exportación.

La respuesta del POST tiene el siguiente formato:

{
    "self": "/organizations/myorg/environments/test/analytics/exports/a7c2f0dd-1b53-4917-9c42-a211b60ce35b",
    "created": "2017-09-28T12:39:35Z",
    "state": "enqueued"
}

Ten en cuenta que la propiedad state de la respuesta se configura como enqueued. La solicitud POST funciona de forma asíncrona. Esto significa que continuará ejecutándose en segundo plano después de que la solicitud muestre una respuesta. Los valores posibles para state incluyen enqueued, running, completed, failed.

Usa la URL que se muestra en la propiedad self para ver el estado de la solicitud de exportación de datos, como se describe en Visualiza el estado de una solicitud de exportación de estadísticas. Cuando la solicitud se completa, el valor de la propiedad state en la respuesta se configura como completed. Luego, puedes acceder a los datos de Analytics en tu repositorio de datos.

Ejemplo 1: Exporta datos a Cloud Storage

La siguiente solicitud exporta un conjunto completo de datos sin procesar de las últimas 24 horas del entorno test en la organización myorg. El contenido se exporta a Cloud Storage en JSON:

curl -X POST -H "Content-Type:application/json" \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }' \
  -u orgAdminEmail:password

Usa el URI que especifica la propiedad self para supervisar el estado del trabajo como se describe en Visualiza el estado de una solicitud de exportación de estadísticas.

Ejemplo 2: Exporta datos a BigQuery

La siguiente solicitud exporta un archivo CSV delimitado por comas a BigQuery:

curl -X POST -H "Content-Type:application/json"  \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export query results to BigQuery",
    "description": "One-time export to BigQuery",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",", 
    "datastoreName": "My BigQuery data repository"
  }' \
  -u orgAdminEmail:password

Nota: El archivo CSV exportado crea una tabla de BigQuery con el siguiente prefijo:

<PREFIX>_<EXPORT_DATE>_api_<UUID>_from_<FROM_DATE>_to_<TO_DATE>

Usa el URI que especifica la propiedad self para supervisar el estado del trabajo, como se describe en Visualiza el estado de una solicitud de exportación de estadísticas.

Ejemplo 3: Exporta los datos de monetización

Si la monetización está habilitada en un entorno de la organización, puedes realizar dos tipos de exportación de datos:

  • Exportación de datos estándar, como se muestra en los dos ejemplos anteriores
  • Exportación de datos a la exportación para exportar datos específicos de la monetización

Para realizar una exportación de datos de monetización, especifica "dataset":"mint" en la carga útil de la solicitud. La organización y el entorno deben admitir la monetización para configurar esta opción; de lo contrario, omiten la propiedad dataset de la carga útil:

  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository",
    "dataset":"mint"
  }'

Información sobre las cuotas de la API de exportación

Para evitar el uso excesivo de llamadas costosas a la API de exportación de datos, Edge aplica una cuota a las llamadas a la API de /analytics/exports:

  • Para las organizaciones y los entornos que no tienen habilitada la monetización, la cuota es la siguiente:

    • 70 llamadas por mes, por organización o entorno

    Por ejemplo, si tienes dos entornos en tu organización, prod y test, puedes realizar 70 llamadas a la API por mes de cada entorno.

  • Para las organizaciones y los entornos con monetización habilitada, la cuota es la siguiente:

    • 70 llamadas por mes para cada organización y entorno de los datos estándar
    • 70 llamadas por mes para cada organización y entorno de los datos de monetización

    Por ejemplo, si habilitas la monetización en la organización prod, puedes realizar 70 llamadas a la API para los datos estándar y 70 llamadas a la API adicionales para datos de monetización.

Si excedes la cuota de llamada, la API muestra una respuesta HTTP 429.

Visualiza el estado de todas las solicitudes de exportación de estadísticas

Para ver el estado de todas las solicitudes de exportación de estadísticas, envía una solicitud GET a /analytics/exports.

Por ejemplo, la siguiente solicitud muestra el estado de todas las solicitudes de exportación de estadísticas para el entorno test en la organización myorg:

curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -u email:password

A continuación, se proporciona un ejemplo de la respuesta que muestra dos solicitudes de exportación, una en cola (creada y en la cola) y otra completada:

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My Cloud Storage data store",
    "executionTime": "36 seconds",
    "created": "2018-09-28T12:39:35Z",
    "updated": "2018-09-28T12:39:42Z",
    "state": "enqueued"
  },
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/9870987089fe03-4364-aaf2-6d4f110444ba"
    "name": "Export raw results to BigQuery",
    "description": "One-time export to BigQuery",
    ... 
  }
]

Visualiza el estado de una solicitud de exportación de estadísticas

Para ver el estado de una solicitud de exportación de estadísticas específica, envía una solicitud GET a /analytics/exports/{exportId}, en la que {exportId} es el ID asociado con la solicitud de exportación de estadísticas.

Por ejemplo, la siguiente solicitud muestra el estado de la solicitud de exportación de estadísticas con el ID 4d6d94ad-a33b-4572-8dba-8677c9c4bd98.

curl -X GET \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
-u email:password

A continuación, se proporciona un ejemplo de la respuesta.

{
  "self":
"/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98",
  "name": "Export results To Cloud Storage",
  "description": "One-time export to Google Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My Cloud Storage data store",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

Si la exportación de estadísticas no muestra datos de estadísticas, executionTime se establece en "0 segundos".

Referencia de la propiedad de la solicitud de exportación

En la siguiente tabla, se describen las propiedades que puedes pasar en el cuerpo de la solicitud en formato JSON cuando se exportan datos de estadísticas.

Property Descripción ¿Es obligatorio?
description Descripción de la solicitud de exportación. No
name Nombre de la solicitud de exportación. Sí
dateRange

Especifica la fecha start y end de los datos que se exportarán, en el formato yyyy-mm-dd. Por ejemplo:

"dateRange": {
    "start": "2018-07-29",
    "end": "2018-07-30"
}

El valor dateRange solo puede abarcar un día. El período comienza a las 00:00:00 UTC de la fecha de start y termina a las 00:00:00 UTC de la fecha de end.

NOTA: Para garantizar que se capturen todos los datos del día anterior, es posible que deba retrasar la hora de inicio de la solicitud de exportación (por ejemplo, 00:05:00 a.m. UTC).

Sí
outputFormat Especifica como json o csv. Sí
csvDelimiter

El delimitador que se usa en el archivo de salida CSV, si outputFormat se configura como csv. El valor predeterminado es el carácter , (coma). Los caracteres delimitadores admitidos incluyen coma (,), barra vertical (|) y tabulación (\t).

 No
datastoreName El nombre del almacén de datos que contiene la definición de su almacén de datos. Sí

Por ejemplo:

{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }