API de informes en tiempo real: autorización

En esta guía se describe cómo una aplicación autoriza solicitudes a la API de informes en tiempo real.

Autorizar solicitudes

Para que los usuarios puedan ver la información de sus cuentas en el sitio web de Google Analytics, primero 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 crees tu aplicación, debes registrarla con la consola de APIs de Google. A continuación, Google te proporciona la información que necesitará posteriormente, como un ID de cliente y un secreto de cliente.
  2. Activa la API de Analytics en la consola de APIs de Google. Si la API no aparece en la lista de la consola de APIs, sáltate este paso.
  3. Cuando tu aplicación necesite acceder a los datos del usuario, esta solicitará a Google un determinado alcance de acceso.
  4. Google muestra una pantalla de consentimiento al usuario pidiéndole su autorización para que la aplicación solicite algunos de sus datos.
  5. Si el usuario aprueba esta petición, Google proporcionará 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 alcance de OAuth 2.0 de la API de Analytics:

Alcance Significado
https://www.googleapis.com/auth/analytics.readonly Acceso de solo lectura a la API de 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 automáticamente algunos de los procesos de autorización. Se pueden usar con 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 prácticos habituales de determinados flujos de OAuth 2.0:

Servidor web

Este flujo resulta adecuado para el acceso automático, sin conexión 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 elaborar informes automatizados, sin conexión 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 se puede usar un solo proyecto de la consola de APIs 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, sin conexión 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 APIs 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 el par de claves 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 APIs de Google.

Se genera el par de claves pública/privada y se descarga en el equipo, lo que sirve de copia única de esta clave. Es responsabilidad tuya almacenarla de forma segura.

Solucionar problemas

No se otorgará la autorización 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 estar 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 solicitud una autorizada. Si no consigues que la autorización funcione en tu aplicación, debes probar que lo haga mediante el espacio de OAuth 2.0. Después, puedes comparar los encabezados HTTP y enviar una solicitud al espacio sobre lo que tu aplicación envía 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 tokens 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 emitió anteriormente deja de ser válido. El token de actualización número 27 que se solicite invalidará el segundo token emitido antes, y así sucesivamente.