Nutzerverwaltung

Die Google Analytics Management API ermöglicht die programmatische Verwaltung von Nutzerberechtigungen. Das ist besonders nützlich für große Unternehmen, die regelmäßig ihre Access Control Lists (ACLs) aktualisieren.

Einführung

Es gibt drei Hauptressourcen, mit denen Sie steuern können, wer auf ein Konto, eine Property oder eine Datenansicht (Profil) zugreifen kann:

Außerdem gibt es eine besondere Batchverarbeitung für Schreibvorgänge beim Schreiben 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 Property oder eine Datenansicht (Profil) gewährt werden:

  • MANAGE_USERS: erforderlich, um Schreibanfragen an die User permissions APIs 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 zuweisen

Die API stellt zwei Berechtigungstypen bereit: local und effective. Lokale Berechtigungen gelten für das angegebene Konto, die angegebene Property oder Datenansicht (Profil). Wenn Sie Berechtigungen mit der API zuweisen, sollten Sie die Property permissions.local verwenden. Effective-Berechtigungen sind Berechtigungen, 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. Diese werden durch die Berechtigung permissions.effective dargestellt.

Anwendungsfälle

Mit den Nutzerberechtigungen in der Management API können die folgenden Anwendungsfälle gelöst werden:

Alle Nutzer eines Kontos auflisten

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

Eine 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. Damit sparen Sie nicht nur das Kontingent, sondern sind auch deutlich leistungsfähiger. Weitere Informationen finden Sie unten im Abschnitt „Batching“. Gehen Sie dazu so vor:

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

Nutzer aus der Kontohierarchie löschen

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

  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 durch Festlegen des Parameters webpropertyId auf ~all.
    • list alle profileUserLinks, indem Sie die Parameter webpropertyId und profileId auf ~all setzen.
  2. Nutzer mit lokalen Berechtigungen suchen und löschen Wiederholen Sie den Vorgang für jede Antwort aus den drei Listenvorgängen in Schritt 1 für jeden entityUserLink:
    • Wenn die userRef-Attribute mit dem Nutzer übereinstimmen und wenn die local-Berechtigungen festgelegt sind, führen Sie eine delete aus.

Weitere Informationen zur Methode delete von Kontonutzerlinks, Web-Property-Nutzerlinks und Datenansichtsprofil-Nutzerlinks 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 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:

    • list alle accountUserLinks.
    • list alle webpropertyUserLinks durch Festlegen des Parameters webpropertyId auf ~all.
    • list alle profileUserLinks, indem Sie die Parameter webpropertyId und profileId auf ~all setzen.

  2. Nutzer mit lokalen Berechtigungen suchen und aktualisieren Wiederholen Sie für jede Antwort, die Sie in Schritt 1 von den drei Listenvorgängen erhalten haben, die einzelnen entityUserLink:

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

Weitere Informationen zur Methode update von Kontonutzerlinks, Web-Property-Nutzerlinks und Datenansichtsprofil-Nutzerlinks finden Sie in der API-Referenz.

Einzelnen Nutzer hinzufügen

Zum Hinzufügen eines Nutzers zur Kontohierarchie, z. B. zu einer Datenansicht (Profil), sind folgende Schritte erforderlich:

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

Batching

Es gibt Leistungssteigerungen und Kontingentanreize, wenn API-Schreibanfragen (Löschen, Einfügen, Aktualisieren) per Batch erstellt werden.

  • Bei Batchanfragen nach Nutzerberechtigungen können Back-End-Optimierungen genutzt werden und die Leistung lässt sich deutlich steigern.
  • Jede 30 Batch-API-Anfragen für Nutzerberechtigungen zählen als ein einzelner Schreibvorgang.
  • Sie können bis zu 300 API-Anfragen mit Nutzerberechtigungen in einer Batchanfrage senden, was zu einem höheren Abfragen pro Nutzer pro Nutzer führt.

Um diese Leistungssteigerungen optimal zu nutzen, sollten Sie bestimmte Maßnahmen ergreifen.

  • Gruppieren Sie Ihre API-Anfrage nach Nutzer.
  • Nur Batchanfragen für ein Konto. Wenn die Anfragen mit mehreren Nutzern mit mehreren Google Analytics-Konten verknüpft sind, wird eine Fehlermeldung mit der folgenden 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. Wir behandeln sie wie folgt:

  • Möglicherweise sind mehrere Änderungen erforderlich, um die Berechtigungen eines einzelnen Nutzers anzupassen. Wenn eine der Änderungen fehlerhaft ist, kann das Commit eines Teils des Batches dazu führen, dass die Berechtigungen des Nutzers in einen unerwünschten Status gebracht werden.
  • Indem wir die Änderungen als eine einzige Transaktion behandeln, optimieren wir den Traffic und können das für den Aufruf erforderliche Kontingent reduzieren.

Beispiel für die Batchverarbeitung – Python

Unten sehen Sie ein einfaches Beispiel in Python, wie Anfragen in Batches zusammengefasst werden, um einer Liste von Datenansichten (Profile) eine Liste von Nutzern hinzuzufügen. In diesem Beispiel werden die Konten für den autorisierten Nutzer durchlaufen und für jedes Konto wird eine einzelne Batchanfrage erstellt. Innerhalb 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 = ['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.