Nutzerverwaltung

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

Einleitung

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

• Links zu Kontonutzern
• Web-Property-Nutzerlinks
• Profilnutzerlinks

Es gibt auch eine spezielle Batch-Unterstützung für Schreibvorgänge für Nutzerberechtigungen.

Nutzerberechtigungen

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

• MANAGE_USERS: erforderlich, um Schreibanfragen an die APIs für Nutzerberechtigungen zu senden.
• EDIT: Erforderlich, um Ressourcen zur Datenverwaltung zu bearbeiten.
• COLLABORATE
• READ_AND_ANALYZE

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

Berechtigungen werden zugewiesen

Die API bietet zwei Arten von Berechtigungen: local und effective. Lokale Berechtigungen gelten für das jeweilige Konto, die jeweilige Property oder die jeweilige Datenansicht. Beim Zuweisen von Berechtigungen über die API sollten Sie die permissions.local-Property verwenden. 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, übernehmen alle Profile und Properties in diesem Konto diese Berechtigungen. Dies wird durch die Property „permissions.effective“ dargestellt.

Wenn Google Analytics-Konten, Properties oder Datenansichten zu einer Organisation gehören, können die Inhaber dieser Organisation Nutzer in diesen Konten bearbeiten. Die Management API listet jedoch nur explizite Mitglieder der Konten, Properties oder Datenansichten auf, nicht die Organisation oder ihre Inhaber.

Anwendungsfälle

Nutzerberechtigungen in der Management API können für die folgenden Anwendungsfälle verwendet werden:

• Alle Nutzer eines Kontos abrufen
• Viele Nutzer aktualisieren
• Nutzer aus der Kontohierarchie löschen
• Einzelnen Nutzer aktualisieren
• Einzelnen Nutzer hinzufügen

Alle Nutzer eines Kontos abrufen

Wenn Sie eine Liste aller Nutzer eines Kontos aufrufen möchten, einschließlich aller Nutzer mit Berechtigungen für eine Property oder Datenansicht (Profil) im Konto, führen Sie die Methode list der Ressource accountUserLinks aus.

Hinweis: Die Berechtigung local ist für einige Nutzer möglicherweise leer, wenn ihnen Zugriff auf tiefere Ebenen in der Kontohierarchie und nicht direkt auf das Konto gewährt wurde.

Große Anzahl von Nutzern aktualisieren

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

1. Alle Nutzerlinks für das Konto abrufen:
   • list – alle accountUserLinks.
2. Erstelle Updateanfragen für jeden Nutzer mit den entsprechenden Berechtigungen:
   • update pro accountUserLink.
3. Erstelle eine einzelne Batchanfrage pro 300 Nutzer mit den oben genannten Aktualisierungsanfragen:
   • Rufen Sie batch pro 300 Nutzer auf.

Nutzer aus der Kontohierarchie löschen

Alle Vorkommen eines Nutzers aus der Kontohierarchie entfernen, 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 3 list-Anfragen für das Konto aus:
   • list – alle accountUserLinks.
   • 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-Attribute mit dem Nutzer übereinstimmen und wenn die Berechtigungen local festgelegt sind, dann führen Sie delete für die Ressource aus

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

Einzelnen Nutzer aktualisieren

Nutzerberechtigungen können auch über die Management API aktualisiert werden. So ändern Sie beispielsweise die Berechtigungsstufe eines Nutzers von READ_AND_ANALYZE in EDIT, sofern Sie den Namen oder die ID der Datenansicht bzw. des Profils nicht kennen:

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

   • list – alle accountUserLinks.
   • 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 Iterieren Sie für jede Antwort, die von den drei Listenvorgängen in Schritt 1 empfangen wird, jeden entityUserLink:

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

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

Einzelnen Nutzer hinzufügen

Wenn Sie einen Nutzer zur Kontohierarchie hinzufügen möchten, z. B. einer Datenansicht (Profil), sind folgende Schritte erforderlich:

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

Batching

Wenn die Berechtigungs-API-Schreibanfragen (Löschen, Einfügen, Aktualisieren) in Batches erstellt werden, kann das zu Leistungssteigerungen und Kontingentanreizen führen.

• Batchanfragen zu Nutzerberechtigungen können Backend-Optimierungen nutzen und erhebliche Leistungssteigerungen erzielen.
• Jede 30 aufeinanderfolgende API-Anfragen für Nutzerberechtigungen zählt als ein einzelner Schreibvorgang.
• In einer Batchanfrage können bis zu 300 API-Anfragen für Nutzerberechtigungen gestellt werden. Dadurch ist eine höhere maximale Anzahl von Abfragen pro Nutzer pro Nutzer möglich.

Damit Sie den größtmöglichen Nutzen aus diesen Leistungssteigerungen ziehen können, sollten Sie bestimmte Maßnahmen ergreifen.

• Gruppieren Sie Ihre API-Anfrage nach Nutzern.
• Nur Batchanfragen für ein Konto Batchanfragen zu Nutzerberechtigungen für mehrere Google Analytics-Konten führen zu einem Fehler mit der folgenden Meldung: All batched requests must be under the same account.

Fehlerbehandlung

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

• Möglicherweise sind mehrere Änderungen erforderlich, um die Berechtigungen eines einzelnen Nutzers anzupassen. Ist eine der Änderungen fehlerhaft, kann das Übertragen eines Teils des Batches dazu führen, dass die Berechtigungen des Nutzers unerwünscht sind.
• Da die Änderungen als einzelne Transaktion behandelt werden, optimieren wir den Traffic und können das für den Aufruf erforderliche Kontingent reduzieren.

Beispiel für Batchverarbeitung – Python

Im Folgenden finden Sie ein einfaches Beispiel in Python für die Batchanfrage zum Hinzufügen einer Liste von Nutzern zu einer Gruppe von Datenansichten (Profilen). Das Beispiel durchläuft die Konten für den autorisierten Nutzer und erstellt für jedes Konto eine einzelne Batchanfrage. In jeder Batchanfrage 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 = ['[e-mail]', '[e-mail]', '[e-mail]', '[e-mail]']

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

Nächste Schritte

Als Nächstes sehen wir uns an, wie Sie mit der Google Analytics Management API verschiedene Datenressourcen konfigurieren.