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:
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.
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.
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:
- Alle Nutzerlinks für das Konto abrufen:
list
– alleaccountUserLinks
.
- Erstelle Updateanfragen für jeden Nutzer mit den entsprechenden Berechtigungen:
update
proaccountUserLink
.
- Erstelle eine einzelne Batchanfrage pro 300 Nutzer mit den oben genannten Aktualisierungsanfragen:
- Rufen Sie
batch
pro 300 Nutzer auf.
- Rufen Sie
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:
- Rufen Sie alle Nutzerlinks für jede Entitätsebene ab. Führen Sie 3
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
-Attribute mit dem Nutzer übereinstimmen und wenn die Berechtigungenlocal
festgelegt sind, dann führen Siedelete
für die Ressource aus
- Wenn die
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:
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 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 Nutzerlocal
-Berechtigungen mitREAD_AND_ANALYZE
-Zugriff hat, dann führen Sieupdate
für die Ressource aus.
- Wenn die
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:
- Verwenden Sie zum Abrufen der IDs für das Konto, die Property und die Datenansicht (Profil) die Management API oder die Weboberfläche.
- Fügen Sie den Nutzer hinzu, indem Sie die Methode
insert
der RessourceprofileUserLinks
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 = ['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 sehen wir uns an, wie Sie mit der Google Analytics Management API verschiedene Datenressourcen konfigurieren.