呼叫 Data Portability API 方法

Data Portability API 包含下列方法：

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

portabilityArchive.initiate

您可以呼叫 portabilityArchive.initiate 方法來啟動新的資料匯出工作。

啟動匯出工作來建立資料封存檔時，您必須要求適當的資源群組，並提供 OAuth 權杖，其中包含該資源群組的必要範圍。OAuth 權杖用於授權要求，並決定要匯出哪些使用者資料。

如需特定服務支援的所有資源群組清單，請參閱該服務的結構定義參考資料頁面。

舉例來說，如果您要匯出搜尋活動資料，請呼叫 InitiatePortabilityArchive(resources = ["myactivity.search"])。要求必須附上 OAuth 權杖，並附上搜尋 OAuth 範圍：https://www.googleapis.com/auth/dataportability.myactivity.search。

雖然您可以在單一 InitiatePortabilityArchive 呼叫中加入多個資源群組，但我們不建議這麼做。您可以為每個資源群組提出個別的 InitiatePortabilityArchive 要求，加快處理速度。請注意，如果您要求多個資源群組，則附加的 OAuth 權杖必須附加所有適當的範圍。

舉例來說，請不要呼叫 InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) 來為搜尋和 YouTube 活動建立資料封存檔，而是請分別呼叫 InitiatePortabilityArchive(resources = ["myactivity.search"]) 和 InitiatePortabilityArchive(resources = ["myactivity.youtube"])。

InitiatePortabilityArchive 要求會傳回 job_id。這個工作 ID 可用來擷取資料封存的狀態。

archiveJobs.getPortabilityArchiveState

系統會呼叫 archiveJobs.getPortabilityArchiveState 方法，擷取資料封存匯出作業目前的狀態。呼叫 getPortabilityArchiveState 時，您會提供 job_id：GetPortabilityArchiveState(job_id)。您也必須提供 OAuth 權杖，其範圍必須與 initiate 要求中使用的資源群組相符。

如果狀態為 COMPLETE，系統會傳回已簽署的 Cloud Storage 網址，您可以使用這些網址下載資料。已簽署的網址會在六小時後失效，且資料可供使用 14 天。

封存要求可能需要數分鐘、數小時，甚至數天才能完成，具體取決於資料量。您可以每隔 5 到 60 分鐘查看封存項目的狀態。

resetAuthorization

resetAuthorization 方法會執行以下操作：

  • 撤銷所有使用者授予的 OAuth 範圍
  • 允許應用程式針對先前使用的資源群組呼叫 InitiatePortabilityArchive
  • 移除先前封存檔的存取權

呼叫 resetAuthorization 時，您必須為要重設授權的使用者提供附加的 OAuth 權杖。

archiveJobs.retryPortabilityArchive

系統會呼叫 archiveJobs.retryPortabilityArchive 方法，重新嘗試失敗的工作，因為 archiveJobs.getPortabilityArchiveState 方法已傳回 FAILED 的狀態。這可能是因為後端發生暫時性錯誤。在這種情況下，您可以重試匯出作業，而無須向使用者取得新 OAuth 權杖。呼叫 retryPortabilityArchive 時，您會提供 job_id 和有效的 OAuth 權杖。接著，端點會嘗試為初始 initiatePortabilityArchive 要求的相同資源群組建立匯出作業。如果成功，這個端點會傳回可用於呼叫 getPortabilityArchiveState 的新 job_id。失敗的工作最多可重試三次。

例如：

  1. 您呼叫 InitiatePortabilityArchive(resources = ["myactivity.search"])，並收到 job_id: 0。

  2. 呼叫 GetPortabilityArchiveState(0) 後，您會收到 JobSate: FAILED。

  3. 接著，您可以呼叫 RetryPortabilityArchive(0) 來接收 resources = ["myactivity.search"] 的 job_id: 1。

  4. 接著，您可以繼續撥打電話給 GetPortabilityArchiveState(1)。

archiveJobs.cancelPortabilityArchive

當您持續存取使用者資料時，系統會呼叫 archiveJobs.cancelPortabilityArchive 方法來取消個別工作，但不會撤銷現有的權杖。當您不再需要工作或資源，且想重設工作配額時，這項功能就非常實用。工作必須是 IN_PROGRESS，且已使用時間存取權建立，才能取消。

舉例來說，您可以取消 myactivity.youtube 和 youtube.public_videos 中途的時間限制工作，然後只為 myactivity.youtube 啟動新工作。

accessType.check

accessType.check 方法可讓您在開始工作前，檢查 OAuth 權杖是否授予時間性或一次性存取權。舉例來說，如果使用者授予一次性存取權，您可能會匯出使用者的完整記錄；如果使用者授予時間限制存取權，則只會匯出最近一天的記錄。

回應包含兩個欄位：一次性和時間性資料可移植性資源群組 ID 清單，這些 ID 是由要求中使用的 OAuth 權杖授權。使用者無法在憑證授予中混用存取類型，但您不應假設日後會發生這種行為。