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 bearbeitenCOLLABORATE
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
- Eine große Anzahl von Nutzern aktualisieren
- Nutzer aus der Kontohierarchie löschen
- Einzelnen Nutzer aktualisieren
- Einzelnen Nutzer hinzufügen
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:
- Alle Nutzerlinks für das Konto abrufen:
list
–accountUserLinks
.
- Erstellen Sie Updateanfragen für jeden Nutzer mit den entsprechenden Berechtigungen:
update
proaccountUserLink
- 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:
- Rufen Sie alle Nutzerlinks für jede Entitätsebene ab. Führen Sie drei
list
-Anfragen für das Konto aus: - 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 dielocal
-Berechtigungen festgelegt sind, dann wirddelete
für die Ressource ausgeführt
- Wenn die
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:
Alle Nutzerlinks für jede Entitätsebene abrufen: Führen Sie drei
list
-Anfragen für das Konto aus: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 Nutzerlocal
-Berechtigungen mitREAD_AND_ANALYZE
-Zugriff hat, dann führen Sie einenupdate
für die Ressource aus.
- Wenn die
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):
- Verwenden Sie die Verwaltungs-API oder die Weboberfläche, um IDs für das Konto, die Property und die Datenansicht (Profil) abzurufen.
- Fügen Sie den Nutzer hinzu, indem Sie die Methode
insert
der RessourceprofileUserLinks
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.