Gestión de usuarios

La API de administración de Google Analytics permite la gestión programática de los permisos de usuario. Esto es especialmente útil para las grandes empresas que necesitan actualizar con frecuencia sus listas de control de acceso (ACL).

Introducción

Hay tres recursos principales que permiten controlar quién puede acceder a una cuenta, propiedad o vista (perfil):

Además, es posible realizar operaciones de escritura de los permisos de usuario por lotes.

Permisos de usuario

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

  • MANAGE_USERS: necesario para enviar solicitudes de escritura a las API de permisos de usuario.
  • EDIT: necesario para cambiar los recursos de gestión de datos.
  • COLLABORATE
  • READ_AND_ANALYZE

Para obtener más información sobre cada nivel de acceso, consulta el artículo Permisos de usuario del Centro de Ayuda.

Asignar permisos

La API ofrece dos tipos de permisos: local y effective. Los permisos locales se aplican a la cuenta, propiedad o vista (perfil) correspondiente. Al asignar permisos con la API debes utilizar la propiedad permissions.local. Los permisos de tipo effective representan los permisos que se heredan de los recursos principales.

Permisos heredados

Si a un usuario se le concede el permiso EDIT en una cuenta, todos los perfiles y propiedades bajo esa cuenta heredarán dicho permiso. Esto lo representa la propiedad permissions.effective.

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, ejecuta el método list del recurso accountUserLinks.

Actualizar a un gran número de usuarios

Para actualizar los permisos de un gran número de usuarios es muy recomendable que utilices el procesamiento por lotes. Esto te permitirá ahorrar cuota y, además, será mucho más eficaz (para obtener más información al respecto, consulta a continuación la sección Procesamiento por lotes). Para realizar esta operación, debes:

  1. Obtener todos los enlaces de usuario de la cuenta:
    • Enumera (list) todos los objetos accountUserLinks.
  2. Crear solicitudes de actualización para cada usuario con los permisos correspondientes:
    • Actualiza (update) todos los objetos accountUserLink.
  3. Crear una única solicitud por lotes por cada 300 usuarios que contenga las solicitudes de actualización anteriores:
    • Ejecuta un lote (batch) por cada 300 usuarios.

Suprimir a un usuario de la jerarquía de cuentas

Para eliminar todas las veces que aparece un usuario en la jerarquía de cuentas (es decir, cuenta, propiedades y vistas [perfiles]), debes:

  1. Obtener todos los enlaces de usuario de cada nivel de entidad. Ejecuta tres solicitudes list en la cuenta:
    • Enumera (list) todos los objetos accountUserLinks.
    • Enumera (list) todos los objetos webpropertyUserLinks asignando al parámetro webpropertyId el valor ~all.
    • Enumera (list) todos los objetos profileUserLinks asignando a los parámetros webpropertyId y profileId el valor ~all.
  2. Encontrar y eliminar a los usuarios que tienen permisos locales. En cada respuesta recibida de las tres operaciones list del paso 1, ensaya con cada una el objeto entityUserLink:
    • Si las propiedades userRef coinciden con el usuario y los permisos local están establecidos, ejecuta un método delete en el recurso.

Consulta la guía de referencia de la API para obtener información sobre el método delete de los recursos de enlaces de usuarios de cuentas, propiedades web y vistas (perfiles).

Actualizar a un solo usuario

Los permisos de usuario también se pueden actualizar con la API de administración. Por ejemplo, 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), debes:

  1. Obtener todos los enlaces de cada nivel de entidad. Ejecuta tres solicitudes list para la cuenta:

    • Enumera (list) todos los objetos accountUserLinks.
    • Enumera (list) todos los objetos webpropertyUserLinks asignando al parámetro webpropertyId el valor ~all.
    • Enumera (list) todos los objetos profileUserLinks asignando a los parámetros webpropertyId y profileId el valor ~all.
  2. Encontrar y actualizar a los usuarios que tienen permisos locales. En cada respuesta recibida de las tres operaciones list del paso 1, ensaya con cada una el objeto entityUserLink:

    • Si las propiedades userRef coinciden con el usuario y si este tiene permisos de tipo local con el acceso READ_AND_ANALYZE, ejecuta un método update en el recurso.

Consulta la guía de referencia de la API para obtener información sobre el método update de los recursos de enlaces de usuarios de cuentas, propiedades web y vistas (perfiles).

Agregar a un solo usuario

Para agregar a un usuario a la jerarquía de cuentas, por ejemplo, a una vista (perfil), debes:

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

Procesamiento por lotes

Realizar solicitudes de escritura (eliminació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.
  • 30 solicitudes de la API de permisos de usuario por lotes 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, debes:

  • Agrupar la solicitud de API por usuario.
  • Incluir 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.

Gestión de errores

Todas las llamadas de permisos en una solicitud por lotes se tratan como una única transacción. Esto significa que si alguna de las transformaciones genera un error, los cambios no se realizarán. Todas las llamadas se tratan como una sola ya que:

  • Se pueden necesitar varios cambios para ajustar los permisos de un único usuario. Si uno de los cambios no tiene el formato correcto, la parte correspondiente del lote podría provocar efectos no deseados en los permisos de usuario.
  • El tráfico se optimiza y la cuota requerida para la llamada puede reducirse.

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.

"""A simple example of Google Analytics batched user permissions."""
import json
from apiclient.errors import HttpError
from apiclient.http import BatchHttpRequest

def call_back(request_id, response, exception):
  """Handle batched request responses."""
  print request_id
  if exception is not None:
    if isinstance(exception, HttpError):
      message = json.loads(exception.content)['error']['message']
      print ('Request %s returned API error : %s : %s ' %
             (request_id, exception.resp.status, message))
  else:
    print response

def add_users(users, permissions):
  """Adds users to every view (profile) with the given permissions.

  Args:
    users: A list of user email addresses.
    permissions: A list of user permissions.
  Note: this code assumes you have MANAGE_USERS level permissions
  to each profile and an authorized Google Analytics service object.
  """

  # Get the a full set of account summaries.
  account_summaries = analytics.management().accountSummaries().list().execute()

  # Loop through each account.
  for account in account_summaries.get('items', []):
    account_id = account.get('id')

    # Loop through each user.
    for user in users:
      # Create the BatchHttpRequest object.
      batch = BatchHttpRequest(callback=call_back)

      # Loop through each property.
      for property_summary in account.get('webProperties', []):
        property_id = property_summary.get('id')

        # Loop through each view (profile).
        for view in property_summary.get('profiles', []):
          view_id = view.get('id')

          # Construct the Profile User Link.
          link = analytics.management().profileUserLinks().insert(
              accountId=account_id,
              webPropertyId=property_id,
              profileId=view_id,
              body={
                  'permissions': {
                      'local': permissions
                  },
                  'userRef': {
                      'email': user
                  }
              }
          )
          batch.add(link)

      # Execute the batch request for each user.
      batch.execute()

if __name__ == '__main__':

  # Construct a list of users.
  emails = ['ona@gmail.com', 'emi@gmail.com', 'sue@gmail.com', 'liz@gmail.com']

  # call the add_users function with the list of desired permissions.
  add_users(emails, ['READ_AND_ANALYZE'])

Pasos siguientes

A continuación, explicaremos cómo se usa la API de administración de Google Analytics para configurar diversos recursos de datos.