Nutzerverwaltung

Mit der Google Analytics Management API lassen sich Nutzerberechtigungen programmatisch verwalten. Dies ist besonders nützlich für große Unternehmen, deren Access Control Lists (ACLs) häufig aktualisiert werden.

Einführung

Es gibt drei Hauptressourcen, mit denen gesteuert wird, wer auf ein Konto, eine Property oder eine Datenansicht (Profil) zugreifen kann:

Außerdem gibt es spezielle Batch-Unterstützung für Schreibvorgänge von Nutzerberechtigungen.

Nutzerberechtigungen

Einem Nutzer, der durch ein Google-Konto repräsentiert wird, können die folgenden Zugriffsebenen für ein Google Analytics-Konto, eine Google Analytics-Property oder eine Google Analytics-Datenansicht (Profil) gewährt werden:

  • MANAGE_USERS: erforderlich, um Schreibanfragen an die Nutzerberechtigungs-APIs zu senden.
  • EDIT: erforderlich, um Datenverwaltungsressourcen zu bearbeiten
  • COLLABORATE
  • READ_AND_ANALYZE

Weitere Informationen zu den einzelnen Zugriffsebenen finden Sie im Hilfeartikel Nutzerberechtigungen.

Berechtigungen zuweisen

Die API stellt zwei Arten von Berechtigungen bereit: local und effective. Lokale Berechtigungen gelten für das jeweilige Konto, die jeweilige Property oder die jeweilige Datenansicht. Verwenden Sie beim Zuweisen von Berechtigungen über die API das Attribut permissions.local. Effective-Berechtigungen stellen Berechtigungen dar, die von übergeordneten Ressourcen übernommen werden.

Übernommene Berechtigungen

Wenn einem Nutzer die Berechtigung EDIT für ein Konto gewährt wird, werden diese Berechtigungen für alle Profile und Properties in diesem Konto übernommen. Dies wird durch die Property „permissions.effective“ repräsentiert.

Anwendungsfälle

Mit Nutzerberechtigungen in der Management API lassen sich folgende Anwendungsfälle lösen:

Alle Nutzer für ein Konto auflisten

Führen Sie die Methode list der Ressource accountUserLinks aus, um alle Nutzer eines Kontos einschließlich aller Nutzer mit Berechtigungen für eine Property oder Datenansicht (Profil) im Konto aufzulisten.

Große Anzahl von Nutzern aktualisieren

Wenn Sie Berechtigungen für eine große Anzahl von Nutzern aktualisieren möchten, empfehlen wir Ihnen dringend, die Batchverarbeitung zu verwenden. Dadurch sparen Sie nicht nur das Kontingent, sondern erzielen auch eine bessere Leistung. Ausführliche Informationen hierzu finden Sie unten im Abschnitt zur Stapelverarbeitung. Dazu sind folgende Schritte erforderlich:

  1. Alle Nutzerlinks für das Konto abrufen:
    • listaccountUserLinks.
  2. Erstellen Sie Updateanfragen für jeden Nutzer mit den entsprechenden Berechtigungen:
  3. Erstellen Sie eine einzelne Batchanfrage pro 300 Nutzer, die die oben genannten Aktualisierungsanfragen enthält:
    • batch pro 300 Nutzer aufrufen.

Nutzer aus der Kontohierarchie löschen

Entfernen aller Vorkommen eines Nutzers aus der Kontohierarchie, d. h. Konto, Properties und Datenansichten (Profile) Dazu sind folgende Schritte erforderlich:

  1. Rufen Sie alle Nutzerlinks für jede Entitätsebene ab. Führen Sie drei list-Anfragen für das Konto aus:
    • listaccountUserLinks.
    • list alle webpropertyUserLinks, indem Sie den Parameter webpropertyId auf ~all setzen.
    • list alle profileUserLinks, indem Sie die Parameter webpropertyId und profileId auf ~all setzen.
  2. Nutzer mit lokalen Berechtigungen suchen und löschen Iterieren Sie für jede Antwort, die von den drei Listenvorgängen in Schritt 1 empfangen wird, jeden entityUserLink:
    • Wenn die userRef-Properties mit dem Nutzer übereinstimmen und wenn die local-Berechtigungen festgelegt sind, dann wird delete für die Ressource ausgeführt

Weitere Informationen zur delete-Methode von Nutzerlinks für Konten, Web-Property-Nutzerlinks und Nutzerlinks (Profil) für Datenansichten finden Sie in der API-Referenz.

Einzelnen Nutzer aktualisieren

Nutzerberechtigungen können auch mithilfe der Management API aktualisiert werden. So ändern Sie beispielsweise die Berechtigungsstufe eines Nutzers von READ_AND_ANALYZE zu EDIT, wenn Sie den Namen oder die ID der Datenansicht (Profil) nicht kennen:

  1. Alle Nutzerlinks für jede Entitätsebene abrufen: Führen Sie drei list-Anfragen für das Konto aus:

    • listaccountUserLinks.
    • list alle webpropertyUserLinks, indem Sie den Parameter webpropertyId auf ~all setzen.
    • list alle profileUserLinks, indem Sie die Parameter webpropertyId und profileId auf ~all setzen.
  2. Nutzer mit lokalen Berechtigungen finden und aktualisieren Durchlaufen Sie für jede Antwort, die von den drei Listenvorgängen in Schritt 1 erhalten wird, jeden entityUserLink:

    • Wenn die userRef-Properties mit dem Nutzer übereinstimmen und wenn der Nutzer local-Berechtigungen mit READ_AND_ANALYZE-Zugriff hat, dann führen Sie einen update für die Ressource aus.

Weitere Informationen zur update-Methode von Nutzerlinks für Konten, Web-Property-Nutzerlinks und Nutzerlinks (Profil) für Datenansichten finden Sie in der API-Referenz.

Einzelnen Nutzer hinzufügen

So fügen Sie einen Nutzer der Kontohierarchie hinzu, z. B. einer Datenansicht (Profil):

  1. Verwenden Sie die Verwaltungs-API oder die Weboberfläche, um IDs für das Konto, die Property und die Datenansicht (Profil) abzurufen.
  2. Fügen Sie den Nutzer hinzu, indem Sie die Methode insert der Ressource profileUserLinks ausführen.

Batching

Es gibt Leistungssteigerungen und Kontingentanreize, wenn die Berechtigungs-API-Schreibanfragen (Löschen, Einfügen, Aktualisieren) in Stapelverarbeitung verarbeitet wird.

  • Batchanfragen von Nutzerberechtigungen können Back-End-Optimierungen nutzen und erhebliche Leistungssteigerungen verzeichnen.
  • Jede 30 aufeinanderfolgende API-Anfragen für Nutzerberechtigungen zählt nur als ein einzelner Schreibvorgang.
  • In einer Batchanfrage können bis zu 300 API-Anfragen für Nutzerberechtigungen gestellt werden, was eine höhere Beschränkung pro Nutzer ermöglicht.

Um diese Leistungssteigerung optimal zu nutzen, sollten Sie einige Maßnahmen ergreifen.

  • Gruppieren Sie Ihre API-Anfrage nach Nutzern.
  • Nur Batchanfragen für ein Konto. Wenn Sie Anfragen zu Nutzerberechtigungen für mehrere Google Analytics-Konten gleichzeitig stellen, wird ein Fehler mit folgender Meldung angezeigt: All batched requests must be under the same account.

Fehlerbehandlung

Alle Berechtigungsaufrufe in einer Batchanfrage werden als einzelne Transaktion behandelt. Wenn also eine der Mutationen fehlerhaft ist, werden keine Änderungen vorgenommen. Aus folgenden Gründen behandeln wir sie wie einen einzigen Aufruf:

  • Möglicherweise sind mehrere Änderungen erforderlich, um die Berechtigungen eines einzelnen Nutzers anzupassen. Wenn eine der Änderungen fehlerhaft ist, kann es sein, dass ein Teil des Batches per Commit für die Berechtigungen des Nutzers unerwünscht ist.
  • Da die Bearbeitungen als eine einzige Transaktion behandelt werden, können wir den Traffic optimieren und das für den Anruf erforderliche Kontingent reduzieren.

Beispiel für Batchverarbeitung – Python

Im Folgenden finden Sie ein einfaches Beispiel in Python für das Hinzufügen einer Liste von Nutzern zu einer Gruppe von Datenansichten (Profilen) stapelweise. Im Beispiel werden die Konten für den autorisierten Nutzer in einer Schleife durchlaufen und für jedes Konto wird eine einzelne Batchanfrage erstellt. In jeder Batch-Anfrage werden alle Änderungen für einen bestimmten Nutzer gruppiert.


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

Nächste Schritte

Als Nächstes erfahren Sie, wie Sie mit der Google Analytics Management API verschiedene Datenressourcen konfigurieren.