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 für ein Konto auflisten
- Viele Nutzer aktualisieren
- Nutzer aus der Kontohierarchie löschen
- Einzelnen Nutzer aktualisieren
- Einzelnen Nutzer hinzufügen
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:
- Alle Nutzerlinks für das Konto abrufen:
list
alleaccountUserLinks
.
- Erstelle Aktualisierungsanfragen für jeden Nutzer mit den entsprechenden Berechtigungen:
update
proaccountUserLink
.
- Erstellen Sie eine Batchanfrage pro 300 Nutzer mit den oben genannten Aktualisierungsanfragen:
- Rufen Sie
batch
pro 300 Nutzer auf.
- Rufen Sie
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:
- Alle Nutzerlinks für jede Entitätsebene abrufen. Führen Sie drei
list
-Anfragen für das Konto aus: - 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 dielocal
-Berechtigungen festgelegt sind, führen Sie einedelete
aus.
- Wenn die
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:
Alle Nutzerlinks für jede Entitätsebene abrufen: Führen Sie drei
list
-Anfragen für das Konto aus: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 Nutzerlocal
-Berechtigungen mitREAD_AND_ANALYZE
-Zugriff hat, führe dann einenupdate
für die Ressource aus.
- Wenn die
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:
- Mit der Management API oder Weboberfläche können Sie IDs für das Konto, die Property und die Datenansicht (Profil) abrufen.
- Fügen Sie den Nutzer hinzu, indem Sie die Methode
insert
der RessourceprofileUserLinks
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.