Neue Data Portability API-Funktionen werden jetzt eingeführt und sind ab dem 20. Februar 2025 für alle verfügbar.

Diese Seite wurde von der Cloud Translation API übersetzt.

Zeitfilter auf Anfragen anwenden

In dieser Kurzanleitung rufen Sie ein OAuth-Token für Ihr Konto ab und senden Anfragen an die Endpunkte der Data Portability API, wobei Sie Zeitstempel verwenden, um die exportierten Daten zu filtern.

In dieser Kurzanleitung erfahren Sie, wie Sie die Data Portability API mit zeitbasiertem Zugriff verwenden und Zeitfilter auf unterstützte Ressourcen anwenden. Weitere Informationen zum zeitbasierten Zugriff auf Nutzerdaten finden Sie unter Zeitbasierten Zugriff verwenden.

Lerninhalte

In dieser Kurzanleitung erfahren Sie Folgendes:

Senden Sie wiederkehrende authentifizierte Anfragen an den InitiatePortabilityArchive-Endpunkt, um nur neue Daten seit dem letzten Export zu exportieren.
Senden Sie eine authentifizierte Anfrage an den InitiatePortabilityArchive-Endpunkt, um nur Daten aus den letzten 6 Monaten zu exportieren.
Senden Sie eine authentifizierte Anfrage an den InitiatePortabilityArchive-Endpunkt, um nur Daten aus einem bestimmten Zeitraum zu exportieren.

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 JavaScript-Web-Apps. In der Produktion wird normalerweise ein anderer Ablauf verwendet, z. B. der OAuth-Ablauf für Webserveranwendungen. Zur Vereinfachung wird in dieser Kurzanleitung der Ablauf für JavaScript-Webanwendungen verwendet.
- Notieren Sie sich beim Erstellen Ihrer Autorisierungsanmeldedaten Ihre OAuth 2.0-Client-ID und Ihren autorisierten 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 werden soll, sollten Sie 30 Tage auswählen, um die Zeitfilterung mit befristetem Zugriff zu testen. Zeitfilter funktionieren auch bei einmaligem Zugriff.
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 Vorgang wird der Ablauf für JavaScript-Webanwendungen verwendet. Bei diesem Ablauf wird kein Aktualisierungstoken zurückgegeben.

Bei einer Produktions-App verwenden Sie in der Regel einen OAuth-Ablauf, um ein Aktualisierungstoken zu erhalten, mit dem bei Bedarf Zugriffstokens generiert werden können. Ein Beispiel hierfür wäre der Ablauf für serverseitige Web-Apps.

So rufen Sie ein OAuth-Token ab:

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=token&
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 alle Bereiche verwenden, die Zeitfilter unterstützen.

Warnung :Mischen Sie keine Data Portability API-Bereiche mit anderen Arten von Bereichen, verwenden Sie nicht zu viele Bereiche gleichzeitig und schließen Sie keine zuvor gewährten Bereiche ein, da dies zu Fehlern führt. Weitere Informationen finden Sie unter Einschränkungen des Geltungsbereichs.
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):
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. Zeitfilter funktionieren auch bei einmaligem Zugriff.
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 das OAuth-Zugriffstoken.

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&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
In der URL ist your_OAuth_token ein String, der das Token darstellt.

Wichtig :Ihr OAuth-Zugriffstoken läuft nach einer Stunde ab. Wenn Sie ein neues Token generieren müssen, folgen Sie den vorherigen Schritten.
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.

Hinweis :Du kannst das Token auch mit einer HTTP-GET-Anfrage überprüfen.
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 mit Zeitstempeln aufzurufen und die exportierten Daten zu filtern.Für diese Befehle benötigen Sie das OAuth-Token und den API-Schlüssel, die Sie zuvor abgerufen haben.

Daten aus dem letzten Export

Sie können Zeitfilter mit befristetem Zugriff verwenden, um die neuen Daten seit Ihrem letzten Export zu exportieren. Betrachten Sie beispielsweise den Bereich https://www.googleapis.com/auth/dataportability.myactivity.search.

Zuerst senden Sie eine authentifizierte Anfrage an den Endpunkt InitiatePortabilityArchive. Mit dieser Anfrage wird ein Archivierungsjob für den gesamten Datenkorpus 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.
Warnung: Der Parameter resources darf nur die OAuth-Bereiche enthalten, für die Zugriff gewährt wurde und die Zeitfilter unterstützen. In diesem Beispiel wurde nur myactivity.search gewährt. Wenn Sie zusätzliche oder nicht unterstützte Ressourcengruppen angeben, wird ein Fehler zurückgegeben. Weitere Informationen finden Sie unter Einschränkungen des Geltungsbereichs.

Die InitiatePortabilityArchive-Anfrage gibt eine archiveJobId 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_1>"
  "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.
```
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_1/portabilityArchiveState
```
Nehmen Sie folgende Änderungen am Befehl vor:
- your_OAuth_token ist das OAuth-Token.
- your_job_id_1 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. Außerdem gibt es ein Feld export_time, das den Zeitstempel des ersten Aufrufs von InitiatePortabilityArchive enthält.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
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.

Hinweis :Die Zeit, die für die Archivierung benötigt wird, hängt von der Größe des Archivs ab. Die maximale Dauer beträgt sieben Tage.

Wenn Sie in der Antwort den Status FAILED erhalten, können Sie den Export mit der Methode RetryPortabilityArchive noch einmal versuchen.
Warten Sie mindestens 24 Stunden und senden Sie dann eine weitere Anfrage an InitiatePortabilityArchive. Verwenden Sie dazu denselben Befehl wie in Schritt 1, aber diesmal export_time als start_time.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Hinweis :Sie können start_time so anpassen, dass es sich leicht mit export_time überschneidet, damit alle zwischen den Anfragen generierten Daten in den Export aufgenommen werden.

Bei einem zeitbasierten Zugriff wird Folgendes zurückgegeben:
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Wiederholen Sie Schritt 2, um eine authentifizierte Anfrage an den Endpunkt GetPortabilityArchiveState zu senden und den Status des Archivierungsjobs abzurufen (mit <your_job_id_2>).

Wenn der Job abgeschlossen ist, enthält die Antwort Folgendes:

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

Prüfen Sie, ob die Daten im zweiten Export nur neue Daten enthalten, die nach dem ersten Export generiert wurden.

Daten der letzten 6 Monate

Mit Zeitfiltern können Sie auch nur die neuesten Daten statt des gesamten Korpus exportieren.

Angenommen, heute ist der 2024-10-01. und Sie möchten die Daten der letzten 6 Monate exportieren. Zuerst senden Sie eine authentifizierte Anfrage an den Endpunkt InitiatePortabilityArchive mit einem start_time von „2024-04-01T00:00:00Z“.

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"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Bei einem zeitbasierten Zugriff wird Folgendes zurückgegeben:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Stellen Sie eine 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/job_id_1/portabilityArchiveState
```
Wenn der Job abgeschlossen ist, enthält die Antwort Folgendes:
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}
```
Hinweis: start_time ist der in Schritt 1 angegebene Wert für start_time und export_time ist der Zeitstempel, zu dem in Schritt 1 der Aufruf von InitiatePortabilityArchive erfolgt ist.
Prüfen Sie, ob der Export nur Daten der letzten sechs Monate enthält.

Daten aus einem bestimmten Zeitraum

Mit Zeitfiltern können Sie Daten aus einem bestimmten Zeitraum exportieren, z. B. nur Daten aus dem Jahr 2023.

Zuerst senden Sie eine authentifizierte Anfrage an den Endpunkt InitiatePortabilityArchive mit einem start_time von „2023-01-01T00:00:00Z“ und einem end_time von „2023-12-31T23:59:59Z“.

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"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Bei einem zeitbasierten Zugriff wird Folgendes zurückgegeben:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Stellen Sie eine 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/job_id_1/portabilityArchiveState

Wenn der Job abgeschlossen ist, enthält die Antwort Folgendes:

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

Beachten Sie, dass start_time mit start_time in Schritt 1 übereinstimmt und export_time mit end_time in Schritt 1.

Prüfen Sie, ob der Export nur Daten aus dem Jahr 2023 enthält.

Unterstützte Bereiche

Die folgenden Bereiche unterstützen Zeitfilter:

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

Achtung:Zeitlich gefilterte Anfragen, die unterstützte und nicht unterstützte Bereiche enthalten, führen zu einem INVALID_ARGUMENT-Fehler mit der Meldung The requested resources do not support time filters.