Administración de usuarios

La API de Google Analytics Management permite la administración programática de los permisos del usuario. Esto es particularmente útil para grandes empresas con actualizaciones frecuentes de sus listas de control de acceso (LCA).

Introducción

Existen tres recursos principales que se usan para controlar quién puede acceder a una cuenta, propiedad o vista (perfil):

También se admite el agrupamiento en lotes especial para las operaciones de escritura de permisos de los usuarios.

Permisos de usuario

A un usuario, representado por una Cuenta de Google, se le pueden otorgar los siguientes niveles de acceso a una cuenta, una propiedad o una vista (perfil) de Google Analytics:

  • MANAGE_USERS: Es necesario para realizar solicitudes de escritura a las APIs de permisos de usuario.
  • EDIT: Es necesario para editar los recursos de administración de datos.
  • COLLABORATE
  • READ_AND_ANALYZE

Para obtener detalles adicionales sobre cada nivel de acceso, consulte el artículo del Centro de ayuda Permisos del usuario.

Cómo asignar permisos

La API expone dos tipos de permisos: local y effective. Los permisos locales se aplican a la cuenta, propiedad o vista (perfil) determinados. Cuando asignes permisos con la API, debes usar la propiedad permissions.local. Los permisos Effective representan permisos que se heredan de los recursos superiores.

Permisos heredados

Si a un usuario se le otorga el permiso EDIT en una cuenta, todos los perfiles y las propiedades de esa cuenta heredarán este permiso. Esto se representará mediante la propiedad permissions.effective.

Casos de uso

Los permisos del usuario en la API de Management se pueden usar para resolver los siguientes casos de uso:

Muestra una lista de todos los usuarios de una cuenta

Para mostrar una lista de todos los usuarios de una cuenta, incluidos todos los usuarios que tienen permisos sobre cualquier propiedad o vista (perfil) de la cuenta, ejecuta el método list del recurso accountUserLinks.

Cómo actualizar una gran cantidad de usuarios

Se recomienda usar el procesamiento por lotes para actualizar los permisos de una gran cantidad de usuarios, ya que no solo ahorrará cuota, sino que también será mucho más eficaz. Consulta la sección sobre lotes que aparece a continuación para conocer todos los detalles. Los pasos necesarios para realizar esta acción en una cuenta son los siguientes:

  1. Obtén todos los vínculos de usuario de la cuenta:
    • list por accountUserLinks.
  2. Crea solicitudes de actualización para cada usuario con los permisos adecuados:
    • update cada accountUserLink.
  3. Crea una sola solicitud por lotes para cada 300 usuarios que contenga las solicitudes de actualización anteriores:
    • llama a batch por cada 300 usuarios.

Cómo borrar a un usuario de la jerarquía de la cuenta

Para quitar todos los casos de un usuario de la jerarquía de la cuenta (es decir, cuenta, propiedades y vistas [perfiles]). Estos son los pasos necesarios para hacerlo:

  1. Obtén todos los vínculos de usuario de cada nivel de entidad. Ejecuta 3 solicitudes list para la cuenta:
    • list por accountUserLinks.
    • list todo webpropertyUserLinks estableciendo el parámetro webpropertyId en ~all.
    • list todo profileUserLinks estableciendo los parámetros webpropertyId y profileId en ~all.
  2. Busca y borra usuarios con permisos locales. Para cada respuesta recibida de las 3 operaciones de lista del paso 1, itera en cada entityUserLink:
    • Si las propiedades userRef coinciden con el usuario y si se establecieron los permisos local, entonces ejecuta una delete en el recurso

Consulta la Referencia de la API para obtener detalles sobre el método delete de los recursos de Vínculos de usuarios de cuenta, Vínculos de usuarios de propiedades web y Ver (perfil) de vínculos de usuarios.

Actualizar un solo usuario

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

  1. Obtener todas las vinculaciones de usuarios de cada nivel de la entidad Ejecuta 3 solicitudes list para la cuenta:

    • list por accountUserLinks.
    • list todo webpropertyUserLinks estableciendo el parámetro webpropertyId en ~all.
    • list todo profileUserLinks estableciendo los parámetros webpropertyId y profileId en ~all.

  2. Busca y actualiza usuarios con permisos locales. Para cada respuesta recibida de las 3 operaciones de lista en el paso 1, itera en cada entityUserLink:

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

Consulta la Referencia de la API para obtener detalles sobre el método update de los recursos de Vínculos de usuarios de cuenta, Vínculos de usuarios de propiedades web y Ver (perfil) de vínculos de usuarios.

Agregar un solo usuario

Para agregar un usuario a la jerarquía de la cuenta, por ejemplo, a una vista (perfil), sigue estos pasos:

  1. Utiliza la API de Management o la interfaz web para recuperar los IDs de la cuenta, la propiedad y la vista (perfil).
  2. Para agregar el usuario, ejecuta el método insert del recurso profileUserLinks.

Agrupación en lotes

Hay mejoras de rendimiento y, además, incentivos de cuota cuando se agrupan solicitudes de escritura (borrar, insertar, actualizar) a la API de permisos.

  • Las solicitudes de permisos del usuario en lotes pueden aprovechar las optimizaciones del backend y generar mejoras significativas en el rendimiento.
  • Cada 30 solicitudes a la API de permisos del usuario en lotes cuenta como una sola operación de escritura.
  • Se pueden realizar hasta 300 solicitudes a la API de permisos de usuario en una sola solicitud por lote, lo que permite un aumento de QPS por límite de usuario.

Para aprovechar al máximo estas mejoras en el rendimiento, hay ciertas acciones que debes realizar.

  • Agrupa tu solicitud a la API por usuario.
  • Solo las solicitudes por lotes para una cuenta. Las solicitudes de permisos de usuario en lotes con más de una cuenta de Google Analytics generarán un error con el siguiente mensaje: All batched requests must be under the same account.

Manejo de errores

Todas las llamadas a permisos en una solicitud por lotes se tratan como una sola transacción. Esto significa que, si alguna de las mutaciones es un error, no se realizan cambios. Los motivos por los que los tratamos como una sola llamada son los siguientes:

  • Es posible que se necesiten varias ediciones para ajustar los permisos de un solo usuario. Si una de las ediciones tiene errores de formato, confirmar parte del lote podría provocar que los permisos del usuario terminen en un estado no deseado.
  • Cuando tratamos las ediciones como una sola transacción, optimizamos el tráfico y podemos reducir la cuota necesaria para la llamada.

Ejemplo de procesamiento por lotes: Python

A continuación, se muestra un ejemplo simple en Python de cómo agrupar solicitudes para agregar una lista de usuarios a un conjunto de vistas (perfiles). En el ejemplo, se repiten indefinidamente las cuentas del usuario autorizado y se crea una única solicitud por lote. Dentro de cada solicitud por lotes, se agrupan todos los cambios para un usuario determinado.


"""A simple example of Google Analytics batched user permissions."""
import json
from googleapiclient.errors import HttpError
from googleapiclient.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'])

Próximos pasos

A continuación, analizaremos cómo usar la API de Google Analytics Management para configurar varios recursos de datos.