呼叫 Data Portability API 方法

Data Portability API 包含下列方法：

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive

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 方法以擷取資料封存匯出工作目前的state。當您呼叫 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 的state。這可能是因為後端暫時故障所導致。在此情況下，您可以在不取得使用者新的 OAuth 憑證的情況下重新嘗試匯出。呼叫 retryPortabilityArchive 時，您必須提供 job_id 並附上有效的 OAuth 權杖。然後，該端點會嘗試針對在初始 initiatePortabilityArchive 要求中要求的相同資源群組建立匯出作業。如果成功，這個端點會傳回「新的」job_id，可用於呼叫 getPortabilityArchiveState。失敗的工作最多可重試三次。

例如：

  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)。