Data Portability API-Methoden aufrufen

Die Data Portability API umfasst die folgenden Methoden:

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive
  • archiveJobs.cancelPortabilityArchive
  • accessType.check

portabilityArchive.initiate

Sie rufen die Methode portabilityArchive.initiate auf, um einen neuen Datenexportjob zu starten.

Wenn Sie einen Exportjob starten, um ein Datenarchiv zu erstellen, müssen Sie die entsprechende Ressourcengruppe anfordern und ein OAuth-Token mit den erforderlichen Bereichen für diese Ressourcengruppe angeben. Das OAuth-Token wird verwendet, um die Anfrage zu autorisieren und zu bestimmen, welche Nutzerdaten exportiert werden.

Eine Liste aller von einem bestimmten Dienst unterstützten Ressourcengruppen finden Sie auf der Referenzseite für das Schema für diesen Dienst.

Wenn Sie beispielsweise Daten zu Suchaktivitäten exportieren, rufen Sie InitiatePortabilityArchive(resources = ["myactivity.search"]) auf. Die Anfrage muss ein OAuth-Token mit dem OAuth-Bereich „Suche“ enthalten: https://www.googleapis.com/auth/dataportability.myactivity.search.

Es ist zwar möglich, mehrere Ressourcengruppen in einem einzigen InitiatePortabilityArchive-Aufruf anzugeben, dies wird jedoch nicht empfohlen. Sie können die Verarbeitung beschleunigen, indem Sie für jede Ressourcengruppe separate InitiatePortabilityArchive-Anfragen stellen. Wenn Sie mehrere Ressourcengruppen anfordern, müssen dem angehängten OAuth-Token alle entsprechenden Bereiche zugewiesen sein.

Anstatt beispielsweise InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) aufzurufen, um ein Datenarchiv für Such- und YouTube-Aktivitäten zu erstellen, sollten Sie die folgenden separaten Aufrufe ausführen: InitiatePortabilityArchive(resources = ["myactivity.search"]) und InitiatePortabilityArchive(resources = ["myactivity.youtube"]).

Die InitiatePortabilityArchive-Anfrage gibt eine job_id zurück. Anhand dieser Job-ID wird der Status des Datenarchivs abgerufen.

archiveJobs.getPortabilityArchiveState

Die Methode archiveJobs.getPortabilityArchiveState wird aufgerufen, um den aktuellen Status des Datenarchiv-Exportjobs abzurufen. Wenn Sie getPortabilityArchiveState aufrufen, geben Sie job_id an: GetPortabilityArchiveState(job_id). Außerdem müssen Sie ein OAuth-Token mit Bereichen angeben, die den in der initiate-Anfrage verwendeten Ressourcengruppen entsprechen.

Wenn der Status COMPLETE ist, werden signierte Cloud Storage-URLs zurückgegeben, mit denen Sie die Daten herunterladen können. Die signierten URLs laufen nach sechs Stunden ab und die Daten sind 14 Tage lang verfügbar.

Je nach Datenmenge kann die Archivierung einige Minuten, mehrere Stunden oder sogar mehrere Tage dauern. Sie können den Status des Archivs alle fünf bis 60 Minuten prüfen.

resetAuthorization

Die Methode resetAuthorization führt Folgendes aus:

  • Widerruft alle vom Nutzer gewährten OAuth-Bereiche
  • Ermöglicht es Ihrer Anwendung, InitiatePortabilityArchive für eine zuvor verwendete Ressourcengruppe aufzurufen
  • Zugriff auf frühere Datenarchive wird entfernt

Wenn du resetAuthorization aufrufst, musst du ein angehängtes OAuth-Token für den Nutzer angeben, dessen Autorisierung du zurücksetzt.

archiveJobs.retryPortabilityArchive

Die Methode archiveJobs.retryPortabilityArchive wird aufgerufen, um fehlgeschlagene Jobs noch einmal auszuführen, für die die Methode archiveJobs.getPortabilityArchiveState bereits den Status FAILED zurückgegeben hat. Das kann an einem vorübergehenden Fehler im Backend liegen. In diesem Fall können Sie den Export noch einmal versuchen, ohne ein neues OAuth-Token vom Nutzer abzurufen. Wenn Sie retryPortabilityArchive aufrufen, geben Sie job_id zusammen mit einem gültigen OAuth-Token an. Der Endpunkt versucht dann, einen Export für dieselben Ressourcengruppen zu erstellen, die in der ursprünglichen initiatePortabilityArchive-Anfrage angefordert wurden. Bei Erfolg gibt dieser Endpunkt eine neue job_id zurück, die du in Aufrufen von getPortabilityArchiveState verwenden kannst. Ein fehlgeschlagener Job kann bis zu dreimal wiederholt werden.

Beispiel:

  1. Sie rufen InitiatePortabilityArchive(resources = ["myactivity.search"]) an und erhalten job_id: 0.

  2. Nachdem Sie GetPortabilityArchiveState(0) angerufen haben, erhalten Sie JobSate: FAILED.

  3. Sie können dann RetryPortabilityArchive(0) anrufen, um job_id: 1 für resources = ["myactivity.search"] zu erhalten.

  4. Anschließend können Sie weiterhin GetPortabilityArchiveState(1) anrufen.

archiveJobs.cancelPortabilityArchive

Die Methode archiveJobs.cancelPortabilityArchive wird aufgerufen, um einen einzelnen Job abzubrechen, ohne vorhandene Tokens zu widerrufen, wenn Sie weiterhin Zugriff auf Nutzerdaten haben. Das ist nützlich, wenn ein Job oder eine Ressource nicht mehr benötigt wird und Sie Ihr Jobkontingent zurücksetzen möchten. Der Job muss IN_PROGRESS sein und mit zeitlich begrenztem Zugriff erstellt worden sein, damit er abgebrochen werden kann.

Sie können beispielsweise einen laufenden, zeitbasierten Job für myactivity.youtube abbrechen und dann einen neuen Job nur für myactivity.youtube starten.youtube.public_videos

accessType.check

Mit der Methode accessType.check können Sie vor dem Starten eines Jobs prüfen, ob ein OAuth-Token einen zeitbasierten oder einmaligen Zugriff autorisiert. Beispielsweise können Sie den gesamten Verlauf eines Nutzers exportieren, wenn er einmaligen Zugriff gewährt, oder nur den Verlauf des letzten Tages, wenn er zeitbasierten Zugriff gewährt.

Die Antwort enthält zwei Felder: Listen mit einmaligen und zeitbasierten Ressourcengruppen-IDs für die Datenübertragbarkeit, die durch das in der Anfrage verwendete OAuth-Token autorisiert wurden. Nutzer können in einer Token-Berechtigung keine Zugriffstypen mischen. Sie sollten jedoch nicht unbedingt davon ausgehen, dass dies in Zukunft nicht der Fall sein wird.