API de Management: Autorización

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

Autoriza solicitudes

Para que los usuarios puedan ver la información de su cuenta en el sitio web de Google Analytics, primero deben acceder a sus Cuentas de Google. Del mismo modo, cuando los usuarios acceden por primera vez a tu aplicación, deben autorizarla para que acceda a sus datos.

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

Acerca de los protocolos de autorización

Tu aplicación debe usar OAuth 2.0 para autorizar solicitudes. No se admiten otros protocolos de autorización. Si tu aplicación usa Acceder con Google, tú controlarás algunos aspectos de la autorización.

Solicitudes de autorización 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, o "flujo", para OAuth 2.0 varían de alguna manera según el tipo de aplicación que estás escribiendo. El siguiente proceso general se aplica a todos los tipos de aplicación:

  1. Cuando crees tu aplicación, deberás registrarla con Google API Console. Luego, Google proporcionará la información que necesites más tarde, como el ID y un secreto del cliente.
  2. Activa la API de Analytics en la Consola de API de Google. Si no aparece en la consola de API, omite este paso.
  3. Cuando la aplicación necesite acceder a datos del usuario, solicita a Google un alcance de acceso en particular.
  4. Google mostrará una pantalla de consentimiento al usuario, en la que le pedirá que permita a la aplicación solicitar algunos de sus datos.
  5. Si el usuario la aprueba, Google le otorgará a la aplicación un token de acceso de corta duración.
  6. La aplicación solicitará los datos del usuario y adjuntará el token de acceso a la solicitud.
  7. Si Google determina que la solicitud y el token son válidos, mostrará los datos solicitados.

Algunos flujos requieren pasos adicionales, como el uso de tokens de actualización, para adquirir nuevos tokens de acceso. Si deseas obtener información detallada sobre los flujos para varios tipos de aplicaciones, consulta la documentación de OAuth 2.0 de Google.

A continuación, encontrarás información sobre el alcance de OAuth 2.0 para la API de Analytics:

Permiso Significado
https://www.googleapis.com/auth/analytics.readonly Tiene acceso de solo lectura a la API de Analytics.
https://www.googleapis.com/auth/analytics.edit Permite editar 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 Consulta los permisos del usuario de Google Analytics.

Para solicitar acceso con OAuth 2.0, tu aplicación necesita los datos del alcance, además de la información que Google proporciona cuando registras la aplicación (como el ID y el secreto del cliente).

Sugerencia: Las bibliotecas cliente de las API de Google pueden controlar algunos de los procesos de autorización por ti. Están disponibles para una variedad de lenguajes de programación. Si quieres obtener más detalles, consulta la página que incluye bibliotecas y ejemplos.

Flujos comunes de OAuth 2.0

A continuación, se enumeran casos de uso comunes para flujos específicos de OAuth 2.0:

Servidor web

Este flujo es útil para el acceso automático, sin conexión o programado a los datos de Google Analytics de un usuario.

Ejemplo:

  • Actualización automática de los paneles de usuario con los datos más recientes de Google Analytics.

Del lado del cliente

Este flujo es ideal para las aplicaciones cuando los usuarios interactúan directamente con la aplicación para acceder a sus datos de Google Analytics en un navegador. Elimina la necesidad de capacidades del servidor, pero hace que los informes automatizados, sin conexión o programados sean poco prácticos.

Ejemplo:

Aplicaciones instaladas

Este flujo es para aplicaciones que se distribuyen como un paquete y que las instala el usuario. Este flujo requiere que la aplicación o el usuario tengan acceso a un navegador para completar el flujo de autenticación.

Ejemplos:

  • Un widget de escritorio en una PC o Mac.
  • Un complemento para un sistema de administración de contenido. El beneficio de este flujo en comparación con el servidor web o el lado del cliente es que se puede usar un solo proyecto de la Consola de API para tu aplicación. Esto permite contar con informes consolidados y una instalación más simple para los usuarios.

Cuentas de servicio

Las cuentas de servicio son útiles para el acceso automático, sin conexión o programado a los datos de Google Analytics de tu propia cuenta. Por ejemplo, puedes crear un panel en tiempo real con tus datos de Google Analytics y compartirlos con otros usuarios.

Para comenzar a usar la API de Analytics, primero debes utilizar la herramienta de configuración, que te guiará para crear un proyecto en la Consola de API de Google, habilitar la API y crear credenciales.

Para configurar una cuenta de servicio nueva, sigue estos pasos:

  1. Haz clic en Crear credenciales > Clave de cuenta de servicio.
  2. Elige si deseas descargar la clave pública/privada de la cuenta de servicio como un archivo P12 estándar o como un archivo JSON que se puede cargar con una biblioteca cliente de la API de Google.

Ya se generó y descargó el nuevo par de claves pública y privada en tu equipo, que será la única copia. Eres responsable de almacenarlo de forma segura.

Solución de problemas

Tu autorización falla en las siguientes situaciones:

  • Obtendrás un código de estado 401 si tu access_token venció o si usas el alcance incorrecto para la API.

  • Obtendrás un 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 de que este realmente tenga la vista (el perfil) que seleccionaste.

OAuth 2.0 Playground

Esta herramienta te permite pasar por todo el flujo de autorización a través de una interfaz web. La herramienta también muestra todos los encabezados de solicitud HTTP necesarios para realizar una consulta autorizada. Si no puedes obtener autorización para trabajar en tu propia aplicación, debes intentar hacer que funcione a través de OAuth 2.0 Playground. Luego, puedes comparar los encabezados y las solicitudes HTTP de la zona de pruebas con lo que la aplicación envía a Google Analytics. Esta verificación es una manera sencilla de asegurarse de dar el formato adecuado a tus solicitudes.

Otorgamiento no válido

Cuando intentas usar un token de actualización, el siguiente comando muestra un error invalid_grant:

  • El reloj del servidor no está sincronizado con el protocolo NTP.
  • Se superó 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 desea instalar una aplicación en varios equipos y acceder a la misma cuenta de Google Analytics, se requerirá un token diferente para cada máquina. Cuando la cantidad de tokens de actualización supera el límite, los tokens más antiguos dejan de ser válidos. Si la aplicación intenta usar un token de actualización no válido, se muestra una respuesta de error invalid_grant.

El límite para cada par único de cliente de OAuth 2.0 y cuenta de Google Analytics es de 25 tokens de actualización. Si la aplicación continúa solicitando tokens de actualización para el mismo par cliente/cuenta, una vez que se emita el token número 26, el primer token de actualización que se emitió anteriormente dejará de ser válido. El token de actualización solicitado número 27 invalidaría el segundo token emitido con anterioridad y así sucesivamente.