Data Portability API メソッドを呼び出す

Data Portability API は、次のメソッドで構成されています。

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

portabilityArchive.initiate

portabilityArchive.initiate メソッドを呼び出して、新しいデータ エクスポート ジョブを開始します。

エクスポート ジョブを開始してデータ アーカイブを作成する場合は、適切なリソース グループをリクエストし、そのリソース グループに必要なスコープを持つ OAuth トークンを指定する必要があります。OAuth トークンは、リクエストを承認し、エクスポートするユーザーデータを特定するために使用されます。

特定のサービスでサポートされているすべてのリソース グループのリストについては、そのサービスのスキーマ リファレンス ページをご覧ください。

たとえば、検索アクティビティ データをエクスポートする場合は、InitiatePortabilityArchive(resources = ["myactivity.search"]) を呼び出します。リクエストには、検索 OAuth スコープ https://www.googleapis.com/auth/dataportability.myactivity.search に関連付けられた OAuth トークンが必要です。

1 回の 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) を指定します。initiate リクエストで使用されるリソース グループと一致するスコープの OAuth トークンも指定する必要があります。

状態が COMPLETE の場合、データのダウンロードに使用できる署名付き Cloud Storage URL が返されます。署名付き URL は 6 時間後に期限切れになり、データは 14 日間利用できます。

データの量に応じて、アーカイブ リクエストが完了するまでに数分、数時間、数日かかることがあります。アーカイブの状態は 5 ～ 60 分ごとに確認できます。

resetAuthorization

resetAuthorization メソッドは次の処理を行います。

  • ユーザーが指定したすべての OAuth スコープを取り消します
  • 以前に使用したリソース グループの InitiatePortabilityArchive の呼び出しをアプリケーションに許可します。
  • 以前のデータ アーカイブへのアクセス権が削除されます

resetAuthorization を呼び出すときは、認可をリセットするユーザーに関連付けられた OAuth トークンを指定する必要があります。

archiveJobs.retryPortabilityArchive

archiveJobs.retryPortabilityArchive メソッドは、archiveJobs.getPortabilityArchiveState メソッドがすでに FAILED のstateを返している、失敗したジョブを再試行するために呼び出されます。これは、バックエンドの一時的な障害が原因で発生することがあります。その場合は、ユーザーから新しい OAuth トークンを取得せずにエクスポートを再試行できます。retryPortabilityArchive を呼び出すときに、job_id と有効な OAuth トークンを指定します。エンドポイントは、最初の initiatePortabilityArchive リクエストでリクエストされた同じリソース グループのエクスポートを作成しようとします。成功すると、このエンドポイントは getPortabilityArchiveState の呼び出しで使用できる新しい job_id を返します。失敗したジョブは 3 回まで再試行できます。

次に例を示します。

  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) を呼び出すことができます。