Management API – Autorisierung

In diesem Leitfaden wird beschrieben, wie eine Anwendung Anfragen an die Management API autorisiert.

Anfragen autorisieren

Bevor Nutzer ihre Kontoinformationen auf der Google Analytics-Website anzeigen können, müssen sie sich in ihrem Google-Konto anmelden. Ebenso müssen Nutzer, die zum ersten Mal auf Ihre Anwendung zugreifen, den Zugriff auf ihre Daten autorisieren.

Jede Anfrage, die Ihre Anwendung an die Analytics API sendet, muss ein Autorisierungstoken enthalten. Anhand dieses Tokens wird deine Anwendung Google gegenüber identifiziert.

Autorisierungsprotokolle

Ihre Anwendung muss zur Autorisierung von Anfragen OAuth 2.0 verwenden. Andere Autorisierungsprotokolle werden nicht unterstützt. Wenn deine Anwendung Über Google anmelden verwendet, werden einige Schritte der Autorisierung automatisch ausgeführt.

Anfragen mit OAuth 2.0 autorisieren

Alle Anfragen an die Analytics API müssen von einem authentifizierten Nutzer autorisiert werden.

Die Details dieses Autorisierungsablaufs für OAuth 2.0 hängen davon ab, welche Art von Anwendung du schreibst. Die folgende allgemeine Vorgehensweise gilt für alle Arten von Anwendungen:

  1. Wenn Sie Ihre Anwendung erstellen, registrieren Sie diese über die Google API Console. Google stellt Ihnen dann die Informationen bereit, die du später benötigst, z. B. eine Client-ID und einen Clientschlüssel.
  2. Aktivieren Sie die Analytics API in der Google API Console. Überspringe diesen Schritt, falls die API nicht in der API Console aufgeführt ist.
  3. Wenn deine Anwendung Zugriff auf Nutzerdaten benötigt, bittet sie Google um einen bestimmten Zugriffsbereich.
  4. Dem Nutzer wird von Google ein Zustimmungsbildschirm angezeigt, auf dem er gebeten wird, deine Anwendung dazu zu autorisieren, einige seiner Daten abzufragen.
  5. Wenn der Nutzer zustimmt, erhält deine Anwendung von Google ein kurzlebiges Zugriffstoken.
  6. Die Anwendung fordert Nutzerdaten an, wobei das Zugriffstoken an die Anfrage angehängt wird.
  7. Stellt Google fest, dass Ihre Anfrage und das Token gültig sind, werden die angeforderten Daten zurückgegeben.

Einige Abläufe enthalten zusätzliche Schritte, beispielsweise die Verwendung von Aktualisierungstoken zum Erhalt neuer Zugriffstoken. Weitere Informationen über die Abläufe für die unterschiedlichen Anwendungstypen findest du in der OAuth 2.0-Dokumentation.

Hier finden Sie Informationen zum Umfang von OAuth 2.0 für die Analytics API:

Umfang Bedeutung
https://www.googleapis.com/auth/analytics.readonly Lesezugriff auf die Analytics API.
https://www.googleapis.com/auth/analytics.edit Google Analytics-Verwaltungseinheiten bearbeiten.
https://www.googleapis.com/auth/analytics.manage.users Nutzerberechtigungen für Analytics-Konten aufrufen und verwalten.
https://www.googleapis.com/auth/analytics.manage.users.readonly Google Analytics-Nutzerberechtigungen abrufen.

Zur Anforderung eines Zugriffs mit OAuth 2.0 benötigt Ihre Anwendung die Informationen zum Umfang sowie die Informationen, die Google bei der Registrierung Ihrer Anwendung bereitstellt, z. B. die Client-ID und den Clientschlüssel.

Tipp: Die Google APIs-Clientbibliotheken können einige Schritte des Autorisierungsvorgangs für Sie übernehmen. Sie sind für verschiedene Programmiersprachen verfügbar. Weitere Informationen erhältst du auf der Seite Bibliotheken und Beispiele.

Gängige OAuth 2.0-Abläufe

Im Folgenden finden Sie häufige Anwendungsfälle für bestimmte OAuth 2.0-Abläufe:

Webserver

Dieser Ablauf eignet sich für den automatisierten, Offline- oder geplanten Zugriff auf die Google Analytics-Daten eines Nutzers.

Beispiel:

  • Nutzer-Dashboards werden automatisch mit den neuesten Google Analytics-Daten aktualisiert.

Clientseitig

Dieser Ablauf ist ideal für Anwendungen, bei denen Nutzer direkt mit der Anwendung interagieren, um in einem Browser auf ihre Google Analytics-Daten zuzugreifen. Es sind keine serverseitigen Funktionen erforderlich. Automatisierte, Offline- oder geplante Berichte sind jedoch nicht praktikabel.

Beispiel:

Installierte Anwendungen

Dieser Ablauf gilt für Anwendungen, die als Paket bereitgestellt und vom Nutzer installiert werden. Für diesen Ablauf muss die Anwendung oder der Nutzer Zugriff auf einen Browser haben, um den Authentifizierungsvorgang abzuschließen.

Beispiele:

  • Ein Desktop-Widget auf einem PC oder Mac.
  • Plug-in für ein Content-Management-System: Der Vorteil dieses Ablaufs im Vergleich zum Webserver oder auf Clientseite besteht darin, dass ein einzelnes API-Konsolenprojekt für Ihre Anwendung verwendet werden kann. Dies ermöglicht konsolidierte Berichte und eine einfachere Installation für die Nutzer.

Dienstkonten

Dienstkonten eignen sich für den automatisierten, Offline- oder geplanten Zugriff auf Google Analytics-Daten für Ihr eigenes Konto. So können Sie beispielsweise ein Live-Dashboard mit Ihren eigenen Google Analytics-Daten erstellen und mit anderen Nutzern teilen.

Bevor Sie die Analytics API verwenden können, müssen Sie zuerst das Einrichtungstool verwenden. Dieses Tool führt Sie durch die Erstellung eines Projekts in der Google API Console, die Aktivierung der API und die Erstellung von Anmeldedaten.

So richten Sie ein neues Dienstkonto ein:

  1. Klicken Sie auf Anmeldedaten erstellen > Dienstkontoschlüssel.
  2. Wählen Sie aus, ob der öffentliche/private Schlüssel des Dienstkontos als Standard-P12-Datei oder als JSON-Datei heruntergeladen werden soll, die von einer Google API-Clientbibliothek geladen werden kann.

Ihr neues öffentliches/privates Schlüsselpaar wird generiert und auf Ihren Computer heruntergeladen. Dies ist die einzige Kopie dieses Schlüssels. Es liegt in Ihrer Verantwortung, ihn sicher aufzubewahren.

Fehlerbehebung

Die Autorisierung schlägt in folgenden Situationen fehl:

  • Sie erhalten den Statuscode 401, wenn Ihre access_token abgelaufen ist oder wenn Sie den falschen Bereich für die API verwenden.

  • Wenn der autorisierte Nutzer keinen Zugriff auf die Datenansicht (Profil) hat, wird der Statuscode 403 angezeigt. Stellen Sie sicher, dass Sie vom richtigen Nutzer autorisiert wurden und dass dieser tatsächlich die von Ihnen ausgewählte Datenansicht (Profil) hat.

OAuth 2.0 Playground

Mit diesem Tool können Sie den gesamten Autorisierungsvorgang über eine Weboberfläche durchlaufen. Das Tool zeigt außerdem alle HTTP-Anfrageheader an, die für die Erstellung einer autorisierten Abfrage erforderlich sind. Wenn Sie keine Autorisierung für die Ausführung in Ihrer eigenen Anwendung erhalten, sollten Sie versuchen, sie über den OAuth 2.0 Playground auszuführen. Anschließend können Sie die HTTP-Header und die Anfrage vom Playground mit den Daten vergleichen, die Ihre Anwendung an Google Analytics sendet. Diese Prüfung ist eine einfache Möglichkeit, um sicherzustellen, dass Ihre Anfragen richtig formatiert sind.

Ungültige Erteilung

Wenn Sie versuchen, ein Aktualisierungstoken zu verwenden, wird der Fehler invalid_grant zurückgegeben:

  • Die Uhr Ihres Servers ist nicht mit dem Netzwerkzeitprotokoll (NTP) synchron.
  • Die maximale Anzahl von Aktualisierungstokens wurde überschritten.

Anwendungen können mehrere Aktualisierungstokens für den Zugriff auf ein einzelnes Google Analytics-Konto anfordern.

Wenn ein Nutzer beispielsweise eine Anwendung auf mehreren Computern installieren und auf dasselbe Google Analytics-Konto zugreifen möchte, ist für jeden Computer ein separates Token erforderlich. Wenn die Anzahl der Aktualisierungstokens das Limit überschreitet, werden ältere Tokens ungültig. Wenn die Anwendung versucht, ein ungültiges Aktualisierungstoken zu verwenden, wird die Fehlerantwort invalid_grant zurückgegeben.

Für jedes eindeutige Paar aus OAuth 2.0-Client und Google Analytics-Konto sind 25 Aktualisierungstokens zulässig. Fordert die Anwendung weiterhin Aktualisierungstokens für dasselbe Client/Konto-Paar an, wird nach der Ausgabe des 26. Tokens das erste zuvor ausgestellte Aktualisierungstoken ungültig. Das 27. angeforderte Aktualisierungstoken würde das zweite zuvor ausgestellte Token ungültig machen und so weiter.