Gestion des utilisateurs

L'API de gestion de Google Analytics permet de gérer les autorisations des utilisateurs de manière programmatique. Cette fonctionnalité est particulièrement utile pour les grandes entreprises qui mettent fréquemment à jour leurs listes de contrôle d'accès (LCA).

Introduction

Trois ressources principales permettent de contrôler l'accès à un compte, une propriété ou une vue (profil):

• Associations d'utilisateurs au compte
• Liens utilisateur de la propriété Web
• Profiler des liens utilisateur

De plus, le traitement par lot est compatible avec les opérations d'écriture des autorisations utilisateur.

Autorisations des utilisateurs

Un utilisateur, représenté par un compte Google, peut se voir accorder les niveaux d'accès suivants à un compte, une propriété ou une vue (profil) Google Analytics :

• MANAGE_USERS : nécessaire pour envoyer des requêtes d'écriture aux API d'autorisations utilisateur.
• EDIT : autorisation requise pour modifier les ressources de gestion des données.
• COLLABORATE
• READ_AND_ANALYZE

Pour en savoir plus sur chaque niveau d'accès, consultez l'article Autorisations de l'utilisateur dans le centre d'aide.

Attribuer des autorisations

L'API expose deux types d'autorisations: local et effective. Les autorisations locales s'appliquent au compte, à la propriété ou à la vue (profil) indiqués. Lorsque vous attribuez des autorisations avec l'API, vous devez utiliser la propriété permissions.local. Les autorisations Effective représentent des autorisations héritées des ressources parentes.

Autorisations héritées

Si un utilisateur dispose de l'autorisation EDIT sur un compte, tous les profils et les propriétés de ce compte héritent de ces autorisations. Ces autorisations sont représentées par la propriété permissions.effective.

Cas d'utilisation

Les autorisations utilisateur dans l'API de gestion permettent de résoudre les cas d'utilisation suivants:

• Lister tous les utilisateurs d'un compte
• Mettre à jour un grand nombre d'utilisateurs
• Supprimer un utilisateur de la hiérarchie des comptes
• Mettre à jour un seul utilisateur
• Ajouter un seul utilisateur

Lister tous les utilisateurs d'un compte

Pour répertorier tous les utilisateurs d'un compte, y compris tous ceux qui disposent d'autorisations sur une propriété ou une vue (profil) du compte, exécutez la méthode list de la ressource accountUserLinks.

Mettre à jour un grand nombre d'utilisateurs

Pour mettre à jour les autorisations d'un grand nombre d'utilisateurs, il est vivement recommandé d'utiliser le traitement par lot. Cela permettra non seulement d'économiser le quota, mais aussi d'améliorer considérablement les performances. Pour plus d'informations, consultez la section relative au traitement par lot ci-dessous. Voici les étapes à suivre pour un compte:

1. Obtenez tous les liens utilisateur du compte :
   • list tous les accountUserLinks.
2. Créez des requêtes de mise à jour pour chaque utilisateur disposant des autorisations appropriées :
   • update chaque fois que accountUserLink.
3. Envoyez une seule requête par lot pour 300 utilisateurs contenant les requêtes de mise à jour ci-dessus :
   • appelez batch tous les 300 utilisateurs.

Supprimer un utilisateur de la hiérarchie du compte

Pour supprimer toutes les occurrences d'un utilisateur dans la hiérarchie du compte (compte, propriétés et vues (profils)). Pour ce faire, procédez comme suit:

1. Obtenez tous les liens utilisateur pour chaque niveau d'entité. Exécutez trois requêtes list pour le compte :
   • list tous les accountUserLinks.
   • list tous les webpropertyUserLinks en définissant le paramètre webpropertyId sur ~all.
   • list tous les profileUserLinks en définissant les paramètres webpropertyId et profileId sur ~all.
2. Recherchez et supprimez les utilisateurs disposant d'autorisations locales. Pour chaque réponse reçue des trois opérations de liste à l'étape 1, itérez chaque entityUserLink :
   • si les propriétés userRef correspondent à l'utilisateur et si les autorisations local sont définies, alors exécute une commande delete sur la ressource.

Consultez la documentation de référence de l'API pour en savoir plus sur la méthode delete des ressources "Liens utilisateur de compte", "Liens utilisateur de propriétés Web" et "Afficher les liens utilisateur (profil)".

Mettre à jour un seul utilisateur

Les autorisations des utilisateurs peuvent également être modifiées à l'aide de l'API Management. Par exemple, pour modifier le niveau d'autorisation d'un utilisateur de READ_AND_ANALYZE à EDIT, en supposant que vous ne connaissez pas le nom ou l'ID de la vue (profil) :

1. Obtenir tous les liens utilisateur pour chaque niveau d'entité Exécutez trois requêtes list pour le compte:

   • list tous les accountUserLinks.
   • list tous les webpropertyUserLinks en définissant le paramètre webpropertyId sur ~all.
   • list tous les profileUserLinks en définissant les paramètres webpropertyId et profileId sur ~all.

2. Recherchez et modifiez les utilisateurs disposant d'autorisations locales. Pour chaque réponse reçue des trois opérations de liste à l'étape 1, itérez chaque entityUserLink:

   • Si les propriétés userRef correspondent à l'utilisateur et s'il dispose des autorisations local avec un accès READ_AND_ANALYZE, puis exécutez une update sur la ressource.

Consultez la documentation de référence de l'API pour en savoir plus sur la méthode update des ressources "Liens utilisateur de compte", "Liens utilisateur de propriétés Web" et "Afficher les liens utilisateur (profil)".

Ajouter un seul utilisateur

Pour ajouter un utilisateur à la hiérarchie du compte, par exemple à une vue (profil), procédez comme suit:

1. Utilisez l'API Management ou l'interface Web pour récupérer les ID du compte, de la propriété et de la vue (profil).
2. Ajoutez l'utilisateur en exécutant la méthode insert de la ressource profileUserLinks.

Traitement par lot

Le traitement par lot des requêtes d'écriture (suppression, insertion, mise à jour) via l'API offre des avantages en termes de performances et de quotas.

• Les demandes d'autorisations utilisateur par lot peuvent tirer parti des optimisations du backend et obtenir des gains de performances significatifs.
• Toutes les 30 requêtes d'autorisation d'utilisateur par lot de l'API comptent comme une seule opération d'écriture.
• Vous pouvez effectuer jusqu'à 300 requêtes d'autorisation d'utilisateur via une API par lot, ce qui permet de définir une limite par utilisateur de RPS plus élevée.

Pour profiter pleinement de ces gains de performances, vous devez prendre certaines mesures.

• Regroupez votre requête API par utilisateur.
• Requêtes par lot pour un seul compte uniquement Les demandes d'autorisations utilisateur groupées pour plusieurs comptes Google Analytics entraîneront une erreur avec le message suivant: All batched requests must be under the same account.

Gestion des erreurs

Tous les appels d'autorisation dans une requête par lot sont traités comme une transaction unique. Cela signifie que si l'une des mutations est erronée, aucune modification n'est apportée. Les raisons pour lesquelles nous les traitons comme un appel unique sont les suivantes:

• Plusieurs modifications peuvent être nécessaires pour ajuster les autorisations d'un seul utilisateur. Si le format de l'une des modifications est incorrect, la validation d'une partie du lot peut entraîner la perte d'autorisations des autorisations de l'utilisateur.
• En traitant les modifications comme une transaction unique, nous optimisons le trafic et pouvons réduire le quota requis pour l'appel.

Exemple de traitement par lot – Python

Vous trouverez ci-dessous un exemple simple en Python illustrant comment envoyer des requêtes par lot pour ajouter une liste d'utilisateurs à un ensemble de vues (profils). L'exemple parcourt les comptes de l'utilisateur autorisé et crée une seule requête par lot pour chaque compte. Dans chaque lot, elle regroupe toutes les modifications apportées à un utilisateur donné.

"""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'])

Étapes suivantes

Nous allons maintenant apprendre à utiliser l'API de gestion de Google Analytics pour configurer diverses ressources de données.