Data Portability API verwenden

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

In dieser Kurzanleitung erfahren Sie, wie Sie die Data Portability API für den einmaligen Zugriff auf Nutzerdaten verwenden. Informationen zum dauerhaften Zugriff auf Nutzerdaten finden Sie unter Befristeten Zugriff verwenden. 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.
  • Optional: Senden Sie noch einmal eine authentifizierte Anfrage mit einem gültigen OAuth-Token an den InitiatePortabilityArchive-Endpunkt und verwenden Sie dabei dieselben Anmeldedaten. Dies gibt einen RESOURCE_EXHAUSTED-Fehler zurück und soll die Wichtigkeit des ResetAuthorization-Endpunkts hervorheben.
  • Sende eine authentifizierte Anfrage an den ResetAuthorization-Endpunkt. Mit dieser Anfrage werden alle vom Nutzer gewährten OAuth-Bereiche widerrufen.
  • Optional: Senden Sie eine Anfrage an den InitiatePortabilityArchive-Endpunkt mit demselben OAuth-Token, das Sie zuvor verwendet haben. Die Anfrage sollte nach dem Zurücksetzen der Autorisierung fehlschlagen.

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.
    • In dieser Kurzanleitung wird für die Dauer des Zugriffs ein einmaliger Zugriff verwendet.
  • 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:

  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=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 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 Einwilligungsbildschirm 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 Nur einmal 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 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.

  5. 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.

  6. 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 Endpunkt InitiatePortabilityArchive. 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. Für diese Kurzanleitung sollten Sie einmaligen Zugriff haben.

    {
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}

    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.

  3. Optional: Wiederholen Sie den vorherigen Befehl, um eine authentifizierte Anfrage an den InitiatePortabilityArchive-Endpunkt 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 die einmalige Einwilligung für die myactivity.search-Ressource für diesen Nutzer erschöpft ist.

    ...
"error": {
    "code": 429,
    "message": "Requested resources have already been exported. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

  4. Sende eine authentifizierte Anfrage an den Endpunkt ResetAuthorization. Mit dieser Anfrage werden alle vom Nutzer gewährten OAuth-Umfänge widerrufen und Sie können InitiatePortabilityArchive für eine Ressourcengruppe aufrufen, die Sie bereits verwendet haben.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset

    Nehmen Sie folgende Änderungen am Befehl vor:

    • your_OAuth_token ist das OAuth-Token.

    Dieser Befehl gibt eine leere Antwort zurück.

  5. Optional: Sende nach dem Zurücksetzen der Autorisierung eine weitere Anfrage an den InitiatePortabilityArchive-Endpunkt. Verwenden Sie denselben curl-Befehl wie zuvor.

    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 einen Fehler zurückgeben, da das von dir angegebene OAuth-Token widerrufen wurde.

    ...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }