Permisos de usuario: guía para programadores

En este documento se explican conceptos importantes sobre el uso de la API de administración para ver y administrar los permisos de usuario de las cuentas, las propiedades y las vistas (perfiles) de Google Analytics.

Introducción

Los permisos de usuario de la API de administración permiten enumerar, crear, editar y suprimir usuarios de tu cuenta de Google Analytics. Esto resulta útil si quieres automatizar la incorporación de nuevos usuarios a Google Analytics, o bien quieres quitar a un conjunto de usuarios.

Antes de empezar

A todas las API de Google Analytics se accede de un modo similar. Antes de empezar a usar la API de administración, debes realizar las siguientes acciones:

  • Consultar la página de bibliotecas de cliente para obtener una lista completa de las bibliotecas de cliente específicas del lenguaje de programación que funcionan con la API.
  • Consultar la Guía de referencia para obtener información sobre la interfaz de la API y el acceso a los datos sin una biblioteca de cliente.

Cada biblioteca de cliente proporciona un solo objeto de servicio Analytics para acceder a todos los datos de la API de administración. Por lo general, para crear el objeto de servicio tienes que realizar los pasos siguientes:

  1. Registrar la aplicación en Google Developers Console.
  2. Autorizar el acceso a los datos de Google Analytics.
  3. Crear un objeto de servicio Analytics.

Si no has completado estos pasos, no sigas y lee el tutorial de presentación de la API de Google Analytics. Con este tutorial recorrerás los pasos iniciales de la creación de una aplicación de la API de Google Analytics. Una vez completado, sabrás cómo acceder a las API de Google Analytics para realizar tareas del mundo real.

Conceptos

Jerarquía de cuentas

Google Analytics tiene una jerarquía de cuentas en la que un usuario autorizado puede tener varias cuentas, cada una de las cuales puede tener varias propiedades y cada propiedad puede tener varias vistas (perfiles).

Una jerarquía con una cuenta en el nivel principal, dos propiedades web en el segundo nivel y conectadas con la cuenta.En el tercer nivel un solo perfil está conectado con la propiedad web situada más a la izquierda y dos perfiles están conectados con la propiedad web situada más a la derecha.Usuarios y permisos de cada uno de los tres niveles.
Figura 1: Jerarquía de cuentas

Niveles de permiso

A un usuario, representado por una cuenta de Google, se le pueden conceder varios niveles de acceso a una cuenta, propiedad o vista (perfil) de Google Analytics.

Los niveles de acceso son:

  • MANAGE_USERS
  • EDIT
  • COLLABORATE
  • READ_AND_ANALYZE

Para obtener más información sobre cada nivel de acceso, consulta Permisos de usuario.

Permisos heredados

Si a un usuario se le concede el permiso EDIT en una cuenta, todos los perfiles y las propiedades de la cuenta heredarán este permiso. Del mismo modo, si a un usuario se le concede el permiso COLLABORATE en una propiedad, todos los perfiles de la propiedad heredarán este permiso.

Trabajar con permisos

Las API exponen dos tipos de permisos: local y effective. Los permisos locales se aplican a la cuenta, a la propiedad o a la vista (perfil) real. Solo se pueden configurar los permisos de tipo local permissions can be configured. Los permisos de tipo effective representan los permisos que se heredan de los recursos principales.

Recuperar permisos del usuario autorizado

Puedes recuperar la información de los permisos del usuario autorizado actualmente con una operación list o get en un recurso Cuentas, Propiedades web o Vistas (perfiles).

Para realizar estas operaciones, el usuario debe autorizar cualquiera de los alcances siguientes:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

Administrar los permisos de usuario

Los siguientes recursos están disponibles para ver y administrar los permisos de usuario de las cuentas, las propiedades y las vistas (perfiles) de Google Analytics:

Estas operaciones solo las pueden realizar los usuarios que tengan el nivel de permiso MANAGE_USERS y hayan autorizado el siguiente ámbito:

  • Ámbito https://www.googleapis.com/auth/analytics.manage.users.

Límites de enlaces de usuario de cuenta

Hay un límite superior de 100 cuentas por usuario en la API.

  • Los intentos de llamar al método insert con un usuario que ya tiene 100 o más cuentas devolverán un error.
  • Consulta Límites y cuotas para obtener información acerca de los límites generales.

Casos prácticos

Los permisos de usuario en la API de administración se pueden usar para los siguientes casos prácticos:

Enumerar a todos los usuarios de una cuenta

Para enumerar a todos los usuarios de una cuenta, incluidos los que tienen permiso en cualquier propiedad o vista (perfil) de la cuenta, solo tienes que ejecutar el método list del recurso accountUserLinks.

Suprimir a un usuario de la jerarquía de cuentas

Suprime todas las veces que aparece un usuario en la jerarquía de cuentas (es decir, cuenta, propiedades y vistas [perfiles]) Los pasos necesarios para realizar esta operación son:

  1. Obtener todos los enlaces de usuario de cada nivel de entidad.
    Ejecuta tres solicitudes list en la cuenta:
    1. Enumerar ( list) todos los objetos accountUserLinks.
    2. Enumerar ( list) todos los objetos webpropertyUserLinks configurando el parámetro webpropertyId como ~all.
    3. Enumerar ( list) todos los objetos profileUserLinks configurando los parámetros webpropertyId y profileId como ~all.
  2. Encontrar y suprimir a los usuarios con permisos locales.
    En cada respuesta recibida de las tres operaciones list del paso 1, itera por cada objeto entityUserLink:
    • Si las propiedades userRef coinciden con el usuario y si están configurados los permisos de tipo local, entonces ejecuta una operación delete en el recurso.

Consulta la referencia de la API para obtener información sobre el método delete de los recursos Enlaces de usuario de cuenta, Enlaces de usuario de propiedad web y Enlaces de usuario vista (perfil).

Actualizar a un solo usuario

Los permisos de usuario también se pueden actualizar con la API de administración. Por ejemplo, los pasos para cambiar el nivel de permisos de usuario de READ_AND_ANALYZE a EDIT, suponiendo que no se sabe el nombre o el ID de vista (perfil), son:

  1. Obtener todos los enlaces de usuario de cada nivel de entidad.
    Ejecuta tres solicitudes list en la cuenta:
    1. Enumerar ( list) todos los objetos accountUserLinks.
    2. Enumerar ( list) todos los objetos webpropertyUserLinks configurando el parámetro webpropertyId como ~all.
    3. Enumerar ( list) todos los objetos profileUserLinks configurando los parámetros webpropertyId y profileId como ~all.
  2. Encontrar y actualizar a los usuarios con permisos locales.
    En cada respuesta recibida de las tres operaciones list del paso 1, itera por cada objeto entityUserLink:
    • Si las propiedades userRef coinciden con el usuario y si el usuario tiene permisos de tipo local con el acceso READ_AND_ANALYZE, entonces ejecuta un método update en el recurso.

Consulta la referencia de la API para obtener información sobre el método update de los recursos Enlaces de usuario de cuenta, Enlaces de usuario de propiedad web y Enlaces de usuario vista (perfil).

Agregar a un solo usuario

Para agregar a un usuario a la jerarquía de cuentas, por ejemplo, a una vista (perfil), es necesario realizar los pasos siguientes:

  1. Utiliza la API de administración o la interfaz web para recuperar los ID de propiedad, cuenta y vista (perfil).
  2. Agrega al usuario ejecutando el método insert del recurso profileUserLinks.

Consulta la referencia de la API para obtener información sobre el método insert de los recursos Enlaces de usuario de cuenta, Enlaces de usuario de propiedad web y Enlaces de usuario vista (perfil).

Procesamiento por lotes

Realizar solicitudes de escritura (supresión, inserción y actualización) de la API de permisos de usuario por lotes ofrece ganancias de rendimiento e incentivos de cuota.

  • Las solicitudes de permisos de usuario por lotes pueden aprovechar las optimizaciones de backend y obtener ganancias de rendimiento considerables.
  • Cada 30 solicitudes de la API de permisos de usuario cuentan como una sola operación de escritura.
  • Se pueden efectuar hasta 300 solicitudes de la API de permisos de usuario en una sola solicitud por lotes, lo que permite más consultas por segundo por límite de usuario.

Para obtener el máximo provecho de estas ganancias de rendimiento, hay una serie de acciones que debes realizar:

  • Agrupa la solicitud de API por usuario.
  • Incluye en el lote las solicitudes de una sola cuenta. Las solicitudes de permisos de usuario por lotes con varias cuentas de Google Analytics genera el siguiente mensaje de error: Todas las solicitudes por lotes deben estar en la misma cuenta.

Ejemplo de operación por lotes: Python

A continuación se ofrece un ejemplo sencillo en Python de cómo agrupar por lotes las solicitudes para agregar una lista de usuarios a un conjunto de vistas (perfiles). El ejemplo recorre las cuentas del usuario autorizado y en cada una crea una única solicitud por lotes. En cada solicitud por lotes agrupa todos los cambios para un determinado usuario.