API de administración: autorización

En esta guía se describe cómo una aplicación autoriza solicitudes a la API de administración.

Autorizar solicitudes

Para poder ver la información de sus cuentas en el sitio web de Google Analytics, primero los usuarios deben iniciar sesión en sus cuentas de Google. Del mismo modo, cuando los usuarios acceden por primera vez a tu aplicación, deben concederle autorización para que acceda a sus datos.

Cada solicitud que envía tu aplicación a la API de Analytics debe incluir un token de autorización. El token también identifica tu aplicación en Google.

Acerca de los protocolos de autorización

Tu aplicación debe utilizar OAuth 2.0 para autorizar las solicitudes. No se admite ningún otro protocolo de autorización. Si tu aplicación usa el inicio de sesión de Google, algunos aspectos de la autorización se gestionan automáticamente.

Autorizar solicitudes con OAuth 2.0

Todas las solicitudes a la API de Analytics deben estar autorizadas por un usuario autenticado.

Los detalles del proceso de autorización para OAuth 2.0, o "flujo", varían ligeramente dependiendo del tipo de aplicación que estés creando. El siguiente proceso general se aplica a todos los tipos de aplicación:

  1. Cuando creas tu aplicación, debes registrarla con la consola de la API de Google. A continuación, Google te proporciona la información que necesitarás posteriormente, como un ID de cliente y un secreto de cliente.
  2. Activa la API de Analytics en la consola de la API de Google. (Si la API no aparece en la lista de la consola de la API de Google, sáltate este paso.)
  3. Cuando tu aplicación necesite acceder a los datos del usuario, solicitará a Google un determinado ámbito de acceso.
  4. Google muestra una pantalla de consentimiento al usuario pidiéndole su autorización para que la aplicación le solicite algunos datos.
  5. Si el usuario aprueba esta petición, Google ofrecerá a la aplicación un token de acceso de corta duración.
  6. Tu aplicación solicita los datos del usuario y adjunta el token de acceso a la solicitud.
  7. Si Google determina que tu solicitud y el token son válidos, muestra los datos solicitados.

En algunos flujos se incluyen pasos adicionales, como el uso de tokens de actualización para adquirir nuevos tokens de acceso. Para obtener más información acerca de los flujos de los distintos tipos de aplicaciones, consulta la documentación de OAuth 2.0 de Google.

A continuación se presenta la información de ámbito de OAuth 2.0 de la API de Analytics:

Ámbito Significado
https://www.googleapis.com/auth/analytics.readonly Acceso de solo lectura a la API de Analytics.
https://www.googleapis.com/auth/analytics.edit Modificar entidades de administración de Google Analytics.
https://www.googleapis.com/auth/analytics.manage.users Ver y administrar los permisos de usuario de las cuentas de Analytics.
https://www.googleapis.com/auth/analytics.manage.users.readonly Ver permisos de usuarios de Google Analytics.

Para solicitar el acceso utilizando OAuth 2.0, tu aplicación necesita la información del ámbito, así como la información que proporciona Google durante el registro de la aplicación (como el ID y el secreto de cliente).

Consejo: Las bibliotecas de cliente de las API de Google pueden gestionar algunos de los procesos de autorización automáticamente. Están disponibles para varios lenguajes de programación; consulta la página con bibliotecas y ejemplos para obtener más detalles.

Flujos de OAuth 2.0 habituales

A continuación se enumeran los casos de uso habituales de determinados flujos de OAuth 2.0:

Servidor web

Este flujo resulta adecuado para el acceso automático, offline o programado de los datos de Google Analytics de un usuario.

Ejemplo:

  • Actualizar automáticamente los paneles de usuario con los datos de Google Analytics más recientes.

Cliente

Resulta ideal en el caso de que los usuarios interactúen directamente con la aplicación para acceder a sus datos de Google Analytics desde un navegador. Con este flujo no se necesitan funciones en el servidor, pero no se pueden llevar a cabo los informes automatizados, offline o programados.

Ejemplo:

Aplicaciones instaladas

Este flujo es para aplicaciones que se distribuyen en paquetes y que instala el usuario. Es necesario que la aplicación o el usuario tengan acceso a un navegador para completar el flujo de autenticación.

Ejemplos:

  • Un widget de ordenador en un PC o Mac.
  • Un complemento de un sistema de gestión de contenido. La ventaja de este flujo, en relación con el de servidor web o de cliente, es que puede usar un solo proyecto de la consola de la API para la aplicación. De este modo, se pueden elaborar informes consolidados y se simplifica la instalación para los usuarios.

Cuentas de servicio

Las cuentas de servicio son útiles para el acceso automatizado, offline o programado a los datos de Google Analytics de tu propia cuenta. Por ejemplo, para crear un panel activo de tus propios datos de Google Analytics y compartirlo con otros usuarios.

Para empezar a usar la API de Analytics, primero debes utilizar la herramienta de configuración, que te guiará por los pasos necesarios para crear un proyecto en la consola de la API de Google, habilitar la API y crear las credenciales.

Para crear una cuenta de servicio, sigue estos pasos:

  1. Haz clic en Create credentials > Service account key (Crear credenciales > Clave de cuenta de servicio).
  2. Decide si quieres descargar la clave pública/privada de la cuenta de servicio como un archivo P12 estándar o como un archivo JSON que pueda cargar una biblioteca de cliente de la API de Google.

El nuevo par de claves pública/privada se genera y se descarga en el equipo, lo que sirve de copia única de esta clave. Eres responsable de almacenarla de forma segura.

Solucionar problemas

La autorización no se producirá en los casos siguientes:

  • Se muestra el código de estado 401 si tu access_token ha caducado o si utilizas un alcance erróneo para la API.

  • Se muestra el código de estado 403 si el usuario autorizado no tiene acceso a la vista (perfil). Asegúrate de que estés autorizado con el usuario correcto y que este tenga la vista (perfil) que has seleccionado.

Espacio de OAuth 2.0

Esta herramienta te permite llevar a cabo todo el proceso de autorización mediante una interfaz web. En la herramienta también se muestran todos los encabezados de solicitud HTTP necesarios para realizar una consulta autorizada. Si no consigues que la autorización funcione en tu aplicación, debes probar que lo haga a través del espacio de OAuth 2.0. Después, puedes comparar los encabezados HTTP y enviar una solicitud al espacio sobre qué envía tu aplicación a Google Analytics. Esta comprobación es una forma sencilla de garantizar que aplicas el formato correcto a tus solicitudes.

Concesión no válida

Cuando intentas utilizar un token de actualización, obtienes un error invalid_grant en los casos siguientes:

  • El reloj de tu servidor no está sincronizado con el protocolo NTP.
  • Se ha superado el límite de token de actualización.

Las aplicaciones pueden solicitar varios tokens de actualización para acceder a una sola cuenta de Google Analytics.

Por ejemplo, si un usuario quiere instalar una aplicación en varios ordenadores y acceder a la misma cuenta de Google Analytics, necesitará un token distinto para cada ordenador. Cuando el número de tokens de actualización supera el límite, los tokens anteriores dejan de ser válidos. Si la aplicación intenta utilizar un token de actualización invalidado, se devuelve la respuesta de error invalid_grant.

El límite para cada par único de cliente OAuth 2.0 y cuenta de Google Analytics es de 25 tokens de actualización. Si la aplicación sigue solicitando tokens de actualización para el mismo par de cliente y cuenta, cuando se solicita el token número 26, el primer token de actualización que se ha emitido anteriormente deja de ser válido. El token de actualización número 27 que se solicite invalidará el segundo token emitido anteriormente, y así sucesivamente.