Zeitbasierten Zugriff verwenden

In dieser Kurzanleitung rufen Sie ein OAuth-Token für Ihr Konto ab und senden wiederkehrende Anfragen an die Endpunkte der Data Portability API.

In dieser Kurzanleitung erfahren Sie, wie Sie die Data Portability API für den zeitbasierten Zugriff auf Nutzerdaten verwenden. Informationen zum einmaligen Zugriff auf Nutzerdaten finden Sie unter Einführung in die Data Portability API. Weitere Informationen zum Anwenden von Zeitfiltern auf Ihre Anfrage

Lerninhalte

In dieser Kurzanleitung erfahren Sie Folgendes:

  • Sende eine authentifizierte Anfrage an den InitiatePortabilityArchive-Endpunkt, indem du ein gültiges OAuth-Token angibst. Die Antwort sollte ein gültiges job_id enthalten.
  • Sende eine authentifizierte Anfrage an den GetPortabilityArchiveState-Endpunkt. Die Antwort sollte einen gültigen Jobstatus und, wenn der Job abgeschlossen ist, eine signierte URL enthalten.
  • Senden Sie noch einmal mit denselben Anmeldedaten eine authentifizierte Anfrage mit einem gültigen OAuth-Token an den InitiatePortabilityArchive-Endpunkt. In diesem Fall wird der Fehler FAILED_PRECONDITION zurückgegeben, wenn die Anfrage innerhalb von 24 Stunden nach der ursprünglichen Anfrage erfolgt.

Vorbereitung

Für diese Kurzanleitung benötigen Sie Folgendes:

  • Prüfen Sie, ob die Data Portability API für Nutzer an Ihrem Standort verfügbar ist. Eine Liste der unterstützten Länder und Regionen finden Sie unter Häufig gestellte Fragen auf der Seite „Eine Kopie Ihrer Daten für Dritte freigeben“.
  • Führen Sie die Einrichtungsschritte für die Data Portability API aus.
  • Folgen Sie der Anleitung zum Konfigurieren von OAuth für serverseitige Webanwendungen.
    • Notieren Sie sich beim Erstellen Ihrer Autorisierungsanmeldedaten Ihre OAuth 2.0-Client-ID, Ihr Clientsecret und Ihre autorisierte Weiterleitungs-URI (z. B. https://google.com). Sie benötigen sie später in dieser Kurzanleitung.
    • Beachten Sie beim Konfigurieren von Bereichen für die Data Portability API, dass in dieser Kurzanleitung die myactivity.search-Ressourcengruppe verwendet wird: https://www.googleapis.com/auth/dataportability.myactivity.search.
    • Wenn Sie festlegen, wie lange der Zugriff erlaubt sein soll, sollten Sie 30 Tage auswählen, um den zeitbasierten Zugriff zu testen.
  • Rufen Sie ein OAuth-Token ab.
  • Sie benötigen Zugriff auf ein Konto, das Ihrer Organisation gehört oder von ihr verwaltet wird. In dieser Kurzanleitung werden die Suchaktivitäten dieses Kontos exportiert.

OAuth-Token abrufen

In dieser Kurzanleitung senden Sie eine Autorisierungsanfrage, um ein OAuth-Token über eine URL abzurufen. Bei diesem Prozess wird der Ablauf für serverseitige Webanwendungen verwendet. Dabei wird ein Aktualisierungstoken generiert, das Sie für nachfolgende Exporte verwenden können.

So rufen Sie ein OAuth-Token ab:

  1. Erstellen Sie eine URL wie die folgende.

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value

    In der URL:

    • client_id ist deine OAuth-Client-ID.
    • redirect_uri ist Ihr autorisierter Weiterleitungs-URI, z. B. https://google.com.

    Beachten Sie, dass in der URL für diese Kurzanleitung der Umfang „Suchaktivitäten“ verwendet wird. Sie können auch den Umfang „YouTube-Aktivitäten“ oder beide Bereiche verwenden.

  2. Fügen Sie die URL in die Adressleiste Ihres Browsers ein und folgen Sie der OAuth-Anleitung. Für diesen Ablauf müssen Sie sich in dem Konto anmelden, das Ihrer Organisation gehört oder von ihr verwaltet wird und das Sie für diesen Schnellstart verwenden.

    Das ist das Konto, das den OAuth-Bereichen zustimmt. Der Bildschirm mit der Einwilligung sollte so aussehen (der Text auf Ihrem Bildschirm kann vom Text in diesem Bild abweichen):

    Der Einwilligungsbildschirm, auf dem der Nutzer zustimmt, dass Daten zu Suchaktivitäten abgerufen werden dürfen

  3. Wählen Sie die Zugriffsbereiche aus, für die Sie Zugriff gewähren möchten, und die Dauer, für die der Zugriff auf die Daten des Kontos gewährt werden soll (einmal, 30 Tage oder 180 Tage). Wählen Sie für diese Kurzanleitung 30 Tage aus.

  4. Nachdem Sie Ihre Einwilligung erteilt und die Dauer des Zugriffs festgelegt haben, sollten Sie zur Weiterleitungs-URI https://google.com weitergeleitet werden. Die in der Adressleiste generierte URL enthält einen Autorisierungscode, den Sie im nächsten Schritt gegen ein OAuth-Token eintauschen.

    Wenn das Nutzerkonto beispielsweise OAuth-Zugriff auf den Bereich dataportability.myactivity.search gewährt, sieht die generierte URL so aus:

    https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

  5. Wenn du einen Autorisierungscode gegen ein Zugriffstoken austauschen möchtest, ruf den OAuth-Token-Endpunkt mit folgendem Code auf:

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'

    Die Antwort sollte in etwa so aussehen:

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}

    In der URL ist your_OAuth_token ein String, der das Token darstellt.

    Das Feld refresh_token_expires_in gibt in Sekunden an, ob der Nutzer 30 Tage (2.592.000 Sekunden) oder 180 Tage (15.552.000 Sekunden) Zugriff ausgewählt hat. Wenn Ihre App den Veröffentlichungsstatus Test hat, haben Sie unabhängig von der Auswahl des Nutzers 7 Tage (60.4800 Sekunden) lang Zugriff.

  6. Fügen Sie zum Validieren des OAuth-Tokens diese URL in Ihren Browser ein:

    https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

    Die Antwort sollte in etwa so aussehen:

    {
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}

    Für Anfragen sind die Felder azp oder aud nicht erforderlich. Das Feld azp entspricht der client_id des autorisierten Ausstellers und das Feld aud identifiziert die Zielgruppe, für die dieses Token bestimmt ist. Sie entspricht einer der Client-IDs für Ihre Anwendung.

  7. Rufen Sie Ihr OAuth-Token und Ihren API-Schlüssel ab. Sie benötigen diese, um die Data Portability API aufzurufen.

Anfragen an die Endpunkte senden

In dieser Kurzanleitung verwenden Sie curl-Befehle, um die Endpunkte der Data Portability API aufzurufen. Für diese Befehle sind das OAuth-Token und der API-Schlüssel erforderlich, die Sie zuvor erfasst haben.

So rufen Sie die Data Portability API auf:

  1. Zuerst senden Sie eine authentifizierte Anfrage an den InitiatePortabilityArchive-Endpunkt. Mit dieser Anfrage wird ein Archivierungsjob gestartet.

    Führen Sie den folgenden curl-Befehl aus:

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    Nehmen Sie folgende Änderungen am Befehl vor:

    • your_OAuth_token ist das OAuth-Token.

    Die InitiatePortabilityArchive-Anfrage gibt eine job_id und eine accessType zurück. Anhand der Job-ID wird der Status des Datenarchivs abgerufen. Der Zugriffstyp gibt an, ob Ihnen ein einmaliger oder zeitbasierter Zugriff auf die Daten gewährt wurde. Bei einem zeitbasierten Zugriff sehen Sie Folgendes:

    {
  "archiveJobId": "<your_job_id>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

    Wenn Sie kein gültiges OAuth-Token angeben, wird folgende Fehlermeldung zurückgegeben: 

    Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.

  2. Als Nächstes senden Sie eine authentifizierte Anfrage an den Endpunkt GetPortabilityArchiveState, um den Status des Archivierungsjobs abzurufen.

    Führen Sie den folgenden curl-Befehl aus:

    curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState

    Nehmen Sie folgende Änderungen am Befehl vor:

    • your_OAuth_token ist das OAuth-Token.
    • your_job_id ist die Job-ID, die von der InitiatePortabilityArchive-Anfrage zurückgegeben wird.

    Die Antwort basiert auf dem Status der Aufgabe. Wenn der Job noch nicht abgeschlossen ist, enthält die Antwort den aktuellen Status. Sie sollten regelmäßig Anfragen an diesen Endpunkt senden, bis der Job abgeschlossen ist.

    {
  "state": "IN_PROGRESS"
}

    Wenn der Job abgeschlossen ist, enthält die Antwort den Status und eine oder mehrere signierte URLs, die zum Herunterladen des Datenarchivs verwendet werden.

    {
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}

    Fügen Sie die signierte URL in Ihren Browser ein, um das Datenarchiv herunterzuladen. Prüfen Sie den Inhalt des Archivs, um sicherzustellen, dass es die erwarteten Daten zu Suchaktivitäten enthält.

    Wenn Sie in der Antwort den Status FAILED erhalten, können Sie den Export mit der Methode RetryPortabilityArchive noch einmal versuchen.

  3. Wiederholen Sie den vorherigen Befehl, um eine authentifizierte Anfrage an den Endpunkt InitiatePortabilityArchive zu senden.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    Nehmen Sie folgende Änderungen am Befehl vor:

    • your_OAuth_token ist das OAuth-Token.

    Die Antwort sollte angeben, dass Sie die myactivity.search-Ressource bereits exportiert haben, und einen Zeitstempel, wann Sie es noch einmal versuchen können.

    ...
  "error": {
    "code": 429,
    "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...

  4. Nach 24 Stunden können Sie einen neuen Export anfordern. Sie müssen jedoch zuerst Ihr Aktualisierungstoken gegen ein neues Zugriffstoken austauschen.

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'

    Die Antwort sollte in etwa so aussehen:

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}

    Wenn der Nutzer den Zugriff verlängert, wird die neue Ablaufzeit im Feld refresh_token_expires_in angezeigt.

    Mit dem neuen Zugriffstoken kannst du die Schritte InitiatePortabilityArchive und GetPortabilityArchiveState wiederholen.