Cómo exportar datos desde Analytics

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

Configura los permisos de los agentes de servicio asignados

Para configurar los permisos de los agentes de servicio asignados, en preparación para los cambios descritos anteriormente, sigue estos pasos.

1. Ingresa el siguiente comando para encontrar el nombre de tu 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'

   ORG es 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 muestra 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 estadísticas de Apigee

Formato de exportación 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 estadísticas compiladas en Edge y 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:

• Google Cloud Storage
• Google BigQuery

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 de forma correcta y que la cuenta de servicio que se usa para escribir datos en el repositorio de datos tenga los permisos adecuados.

2. Crea un almacén de datos que defina las propiedades del repositorio de datos (Cloud Storage o BigQuery) donde exportas tus datos, incluidas las credenciales que se usan para acceder al repositorio de datos.

   Cuando creas un almacén de datos, subes las credenciales del repositorio de datos al Edge Credentials Vault para almacenarlas de forma segura. Luego, el mecanismo de exportación de datos usa esas credenciales para escribir datos en tu repositorio de datos.

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 completa 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 se realice esa escritura, debes hacer lo siguiente:

• Crea una cuenta de servicio de Google Cloud Platform.
• Establece el rol 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 tu aplicación, no a un usuario individual. Luego, tu 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 cadena JSON. Cuando creas el almacén de datos de Edge que define la conexión a tu repositorio de datos, le pasas esta clave. Luego, el mecanismo de exportación de datos usa la clave para acceder a tu repositorio de datos.

La cuenta de servicio asociada con la clave debe ser propietaria del 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 requerida, 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 APIs de BigQuery y Cloud Resource Manager estén habilitadas en tu proyecto de Google Cloud Platform. Consulta Habilita las APIs para obtener instrucciones. Apigee usa la API de BigQuery para aprovechar las funciones de exportación de BigQuery cuando realiza exportaciones 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 tenga asignados los siguientes roles:

  • Usuario de trabajo de BigQuery
  • Creador de objetos de almacenamiento
  • Administrador de almacenamiento (solo se requiere para probar el almacén de datos, como se describe en Cómo probar la configuración de un almacén de datos) Si este rol es demasiado amplio, puedes agregar el permiso storage.buckets.get a un rol existente.

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

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get (solo es obligatorio para probar el almacén de datos, como se describe en Cómo probar la configuración de un almacén de datos)

Configura Google BigQuery

Sigue estos pasos para exportar datos a Google BigQuery:

• Asegúrate de que las APIs de BigQuery y Cloud Resource Manager estén habilitadas en tu proyecto de Google Cloud Platform. Consulta Habilita las APIs para obtener instrucciones. Apigee usa la API de Cloud Resource Manager para verificar el permiso antes de cada exportación.
• Asegúrate de que la API de BigQuery esté habilitada en tu proyecto de Google Cloud Platform. Consulta Habilita o inhabilita APIs para obtener instrucciones.

• Asegúrate de que la cuenta de servicio tenga asignados los siguientes roles:

  • 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

Crea un almacén de datos

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

Acerca del almacén de credenciales de Edge

Edge usa el Credentials Vault para 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 Edge Credentials Vault, debes definir un consumidor de credenciales.

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

Prueba la configuración de un almacén de datos

Cuando creas el almacén de datos, Edge no prueba ni valida que tus credenciales y la configuración del repositorio de datos sean válidas. Esto significa que puedes crear el almacén de datos y no detectar ningún error hasta que ejecutes tu primera exportación de datos.

Como alternativa, prueba la configuración del almacén de datos antes de crearlo. Las pruebas son útiles porque un proceso de exportación de datos grande puede tardar mucho tiempo en ejecutarse. Si pruebas tus credenciales y la configuración del almacén de datos antes de comenzar a descargar grandes cantidades de datos, puedes corregir rápidamente cualquier problema con la configuración.

Si la prueba se realiza correctamente, crea el almacén de datos. Si la prueba falla, corrige los errores y, luego, vuelve a probar la configuración. Solo creas el almacén de datos después de que las pruebas se realicen correctamente.

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 Habilita o inhabilita APIs para obtener instrucciones.

Crea un almacén de datos

Para crear un almacén de datos en la IU, sigue estos pasos:

1. Accede a https://apigee.com/edge como administrador de la organización y selecciona tu organización.

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

2. Selecciona Administrador > Almacenamiento de datos de Analytics en la barra de navegación izquierda. Se mostrará la página Almacenamiento de datos de Analytics.

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

   

4. Elige un tipo de objetivo de datos de exportación:

   • 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 de las credenciales disponibles.

   Las credenciales son específicas de un tipo de repositorio de datos. Consulta Cómo crear una cuenta de servicio para Cloud Storage o BigQuery para 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 nuevas. En el cuadro de diálogo, ingresa lo siguiente:

     1. El nombre de las credenciales.
     2. El contenido de credenciales es la clave de la cuenta de servicio JSON específica de tu repositorio de datos, como se define en Crea 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 del 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	Es el nombre del bucket de 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, consulta Crea buckets de almacenamiento en la documentación de Google Cloud Platform.	Sí
     Ruta	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 del 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, consulta Crea y usa conjuntos de datos en la documentación de Google Cloud Platform.	Sí
     Prefijo de la tabla	Es el prefijo para los nombres de las tablas creadas para los datos de estadísticas en el conjunto de datos de BigQuery.	Sí

8. Selecciona Probar conexión para 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 realizarla. Coloca el cursor sobre el mensaje de error en la IU para que se muestre información adicional en un cuadro de información.

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

Modifica un almacén de datos

Para modificar un almacén de datos, sigue estos pasos:

1. Accede a https://apigee.com/edge como administrador de la organización y selecciona tu organización.

2. Selecciona Administrador > Almacenamiento de datos de Analytics en la barra de navegación izquierda. Se mostrará la página Almacenamiento de datos de Analytics.

3. Coloca el puntero del mouse sobre la columna Modificado del informe que deseas modificar. Aparecerán los íconos de editar y borrar.

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

5. Si editaste el almacén de datos, selecciona Probar conexión para asegurarte 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 realizarla.

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

Exporta 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 estadísticas en tu repositorio de datos.

Ejemplo 1: Exporta datos a Cloud Storage

En la siguiente solicitud, se exporta un conjunto completo de datos sin procesar durante las últimas 24 horas del entorno de prueba a 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

Con la siguiente solicitud, se 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 a 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.

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

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