Wywoływanie metod interfejsu Data Portability API

Interfejs Data Portability API składa się z tych metod:

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

portabilityArchive.initiate

Aby rozpocząć nowe zadanie eksportu danych, wywołaj metodę portabilityArchive.initiate.

Gdy uruchamiasz zadanie eksportowania w celu utworzenia archiwum danych, musisz poprosić o odpowiednią grupę zasobów i podać token OAuth z wymaganymi uprawnieniami dla tej grupy. Token OAuth służy do autoryzacji żądania i określania, które dane użytkownika mają być eksportowane.

Listę wszystkich grup zasobów obsługiwanych przez daną usługę znajdziesz na stronie referencyjnej schematu tej usługi.

Jeśli na przykład eksportujesz dane o aktywności związanej z wyszukiwaniem, wywołujesz funkcję InitiatePortabilityArchive(resources = ["myactivity.search"]). Prośba musi zawierać token OAuth z zakresem OAuth wyszukiwania: https://www.googleapis.com/auth/dataportability.myactivity.search.

Chociaż można uwzględnić w jednym wywołaniu InitiatePortabilityArchive kilka grup zasobów, nie jest to zalecane. Aby przyspieszyć przetwarzanie, możesz wysłać oddzielne InitiatePortabilityArchive dla każdej grupy zasobów. Pamiętaj, że jeśli żądasz dostępu do wielu grup zasobów, dołączony token OAuth musi mieć wszystkie odpowiednie zakresy.

Na przykład zamiast wywołać funkcję InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) w celu utworzenia archiwum danych dla wyszukiwania i aktywności w YouTube, wykonaj te 2 oddzielne wywołania: InitiatePortabilityArchive(resources = ["myactivity.search"]) i InitiatePortabilityArchive(resources = ["myactivity.youtube"]).

Zapytanie InitiatePortabilityArchive zwraca job_id. Ten identyfikator zadania służy do pobrania stanu archiwum danych.

archiveJobs.getPortabilityArchiveState

Metoda archiveJobs.getPortabilityArchiveState jest wywoływana w celu pobrania bieżącego stanu zadania eksportu archiwum danych. Gdy dzwonisz do getPortabilityArchiveState, podajesz job_id: GetPortabilityArchiveState(job_id). Musisz też podać token OAuth z zakresami, które pasują do grup zasobów użytych w żądaniu initiate.

Jeśli stan to COMPLETE, zwracane są podpisane adresy URL Cloud Storage, których możesz użyć do pobrania danych. Podpisane adresy URL wygasają po 6 godzinach, a dane są dostępne przez 14 dni.

W zależności od ilości danych przetworzenie prośby o archiwizację może potrwać kilka minut, godzin lub nawet dni. Stan archiwum możesz sprawdzać co 5–60 minut.

resetAuthorization

Metoda resetAuthorization:

  • Unieważnia wszystkie zakresy protokołu OAuth przyznane przez użytkownika.
  • Zezwala aplikacji na wywołanie funkcji InitiatePortabilityArchive w przypadku grupy zasobów, której używasz wcześniej
  • Usuwanie dostępu do wcześniejszych archiwów danych

Podczas wywołania funkcji resetAuthorization musisz podać dołączony token OAuth użytkownika, którego autoryzację chcesz zresetować.

archiveJobs.retryPortabilityArchive

Metoda archiveJobs.retryPortabilityArchive jest wywoływana w celu ponownego wykonania zadań, które się nie powiodły, gdy metoda archiveJobs.getPortabilityArchiveState zwróciła już stan FAILED. Może to być spowodowane chwilowym awarią na zapleczu. W takim przypadku możesz ponownie wyeksportować dane bez konieczności uzyskiwania od użytkownika nowego tokena OAuth. Gdy wywołujesz funkcję retryPortabilityArchive, podajesz job_id wraz z prawidłowym tokenem OAuth. Następnie punkt końcowy próbuje utworzyć eksport tych samych grup zasobów, które zostały zażądane w pierwotnym initiatePortabilityArchiveżądaniu. Jeśli operacja się powiedzie, ten punkt końcowy zwróci nowy identyfikator job_id, którego można używać w wywołaniach funkcji getPortabilityArchiveState. Nieudane zadanie można ponownie uruchomić maksymalnie 3 razy.

Na przykład:

  1. Dzwonisz na numer InitiatePortabilityArchive(resources = ["myactivity.search"]) i odbierasz job_id: 0.

  2. Po wybraniu numeru GetPortabilityArchiveState(0) otrzymasz numer JobSate: FAILED.

  3. Następnie możesz zadzwonić pod numer RetryPortabilityArchive(0), aby otrzymać job_id: 1 dla resources = ["myactivity.search"].

  4. Następnie możesz nadal dzwonić pod numer GetPortabilityArchiveState(1).

archiveJobs.cancelPortabilityArchive

Metoda archiveJobs.cancelPortabilityArchive jest wywoływana w celu anulowania pojedynczego zadania bez odwoływania istniejących tokenów, gdy masz stały dostęp do danych użytkownika. Jest to przydatne, gdy zadanie lub zasób nie są już potrzebne i chcesz zresetować limit zadań. Zadanie musi być IN_PROGRESS i musi mieć ograniczony czasowo dostęp, który ma zostać anulowany.

Możesz na przykład anulować w trakcie wykonywania zadanie oparte na czasie dotyczące zadań myactivity.youtube i youtube.public_videos, a potem uruchomić nowe zadanie dotyczące tylko zadania myactivity.youtube.

accessType.check

Metoda accessType.check umożliwia sprawdzenie, czy token OAuth autoryzuje dostęp czasowy czy jednorazowy przed rozpoczęciem zadania. Możesz na przykład eksportować całą historię użytkownika, jeśli przyzna on dostęp jednorazowy, lub tylko ostatni dzień, jeśli przyzna dostęp ograniczony czasowo.

Odpowiedź zawiera 2 pola: listy identyfikatorów grup zasobów danych dotyczących przenoszenia danych (jednorazowych i określonych czasowo) autoryzowanych przez token OAuth użyty w żądaniu. Użytkownicy nie mogą łączyć typów dostępu w ramach przyznawania tokena, ale nie musisz zakładać, że w przyszłości będzie to możliwe.