Cómo exportar datos desde Analytics

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

Configura permisos para los agentes de servicio asignados

Si deseas configurar permisos para los agentes de servicio asignados, mientras te preparas para los cambios descritos anteriormente, sigue estos pasos.

1. Para buscar el nombre de tu agente de servicio de Google Cloud, ingresa el siguiente comando:

   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 es tu organización. Esto muestra el nombre y el valor del agente de servicio como aparece 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. En la parte superior del panel IAM, haz clic en Agregar.
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 estadísticas de Apigee

Formato de datos de exportación

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

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 Vault de credenciales perimetrales 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 estadísticos escribe datos en Cloud Storage o BigQuery. Para que se produzca esa escritura, debes hacer lo siguiente:

• Crea una cuenta de servicio de Google Cloud Platform.
• Configura 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 en lugar de 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 string JSON. Cuando creas el almacén de datos perimetral que define la conexión a tu repositorio de datos, se le pasa 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 propietario 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 requerida, consulta Crea y administra claves de cuentas de servicio en la documentación de Google Cloud Platform.

Por ejemplo, cuando descargues tu 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 Cómo habilitar APIs 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 los permisos antes de cada exportación.

• Asegúrate de que la cuenta de servicio esté asignada a los siguientes roles:

  • 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 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 (obligatorio solo para probar el almacén de datos como se describe en Cómo probar la configuración del 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 Cómo habilitar APIs 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 APIs para obtener instrucciones.

• Asegúrate de que la cuenta de servicio esté asignada a 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 a tu repositorio de datos de exportación (Cloud Storage, BigQuery), incluidas las credenciales usadas para acceder al repositorio de datos.

Acerca de la bóveda de credenciales perimetrales

Edge usa Vault de credenciales 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 de la bóveda de credenciales perimetrales, 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 una configuración de 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. Eso 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 crearla. Las pruebas son útiles porque un proceso de exportación de datos grande puede demorar 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 solucionar rápidamente cualquier problema con tu configuración.

Si la prueba se realiza correctamente, crea el almacén de datos. Si la prueba falla, corrige los errores y vuelve a probar la configuración. Solo debes crear el almacén de datos después de que las pruebas se hayan realizado de forma correcta.

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

Crea un almacén de datos

Para crear un almacén de datos en la IU, haz lo siguiente:

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. En la barra de navegación izquierda, selecciona Administrador > Almacenes de datos de Analytics. Aparecerá la página Almacén de datos de Analytics.

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

   

4. Elige un tipo de segmentación 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 usa para acceder al repositorio de datos. Aparecerá una lista desplegable de las credenciales disponibles.

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

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

   • Si estás agregando 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 las credenciales es la clave de la cuenta de servicio JSON específica de tu repositorio de datos, según 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 Cómo crear y administrar proyectos en la documentación de Google Cloud Platform.	Sí
     Nombre del bucket	Nombre del bucket en Cloud Storage al que quieres 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 Cómo crear buckets 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 del proyecto	ID del proyecto de Google Cloud Platform. Para crear un proyecto de Google Cloud Platform, consulta Cómo crear y administrar 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 Cómo crear y usar conjuntos de datos en la documentación de Google Cloud Platform.	Sí
     Prefijo de la tabla	Prefijo para los nombres de las tablas creadas para los datos de análisis en el conjunto de datos de BigQuery.	Sí

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

   Si la prueba es exitosa, guarda tu almacén de datos.

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

9. Cuando se complete la prueba de conexión, selecciona Guardar para guardar el almacén de datos.

Modifica un almacén de datos

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

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

2. En la barra de navegación izquierda, selecciona Administrador > Almacenes de datos de Analytics. Aparecerá la página Almacén de datos de Analytics.

3. Mueve el puntero del mouse sobre la columna Modificada 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 Test connection para asegurarte de que se puedan usar las credenciales a fin de acceder al almacén de datos.

   Si la prueba es exitosa, puedes ver los datos de muestra en tu repositorio de datos.

   Si la prueba falla, soluciona los problemas y vuelve a intentar la prueba.

6. Una vez que se complete la prueba de conexión, actualiza el almacén de datos.

Exporta datos de estadísticas

Para exportar datos de estadísticas, emite 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 análisis en tu repositorio de datos.

Ejemplo 1: Exporta datos a Cloud Storage

La siguiente solicitud exporta un conjunto completo de datos sin procesar durante las últimas 24 horas desde el 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 las costosas llamadas 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 al mes por organización y 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, emite 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.

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