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 スコープ 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 メソッドが呼び出され、データ アーカイブ エクスポート ジョブの現在の状態が取得されます。getPortabilityArchiveState を呼び出すときに、job_id:GetPortabilityArchiveState(job_id) を指定します。また、initiate リクエストで使用されるリソース グループに一致するスコープを持つ OAuth トークンも指定する必要があります。

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

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

resetAuthorization

resetAuthorization メソッドは、次のことを行います。

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

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

archiveJobs.retryPortabilityArchive

archiveJobs.retryPortabilityArchive メソッドは、archiveJobs.getPortabilityArchiveState メソッドがすでに FAILED のステータスを返している失敗したジョブを再試行するために呼び出されます。これは、バックエンドで一時的な障害が発生したために発生することがあります。その場合は、ユーザーから新しい OAuth トークンを取得せずに、書き出しを再試行できます。retryPortabilityArchive を呼び出すときに、有効な OAuth トークンと job_id を指定します。エンドポイントは、最初の 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) への呼び出しを続行できます。

archiveJobs.cancelPortabilityArchive

archiveJobs.cancelPortabilityArchive メソッドは、ユーザーデータに継続的にアクセスしているときに、既存のトークンを取り消さずに個々のジョブをキャンセルするために呼び出されます。これは、ジョブまたはリソースが不要になり、ジョブの割り当てをリセットする必要がある場合に便利です。ジョブが IN_PROGRESS であり、時間ベースのアクセス権で作成されている必要があります。

たとえば、myactivity.youtube と youtube.public_videos の進行中の時間ベースのジョブをキャンセルし、myactivity.youtube の新しいジョブのみを開始できます。

accessType.check

accessType.check メソッドを使用すると、ジョブを開始する前に、OAuth トークンが時間ベースのアクセス権または 1 回限りのアクセス権を承認しているかどうかを確認できます。たとえば、ユーザーが 1 回限りのアクセス権を付与した場合はユーザーの履歴全体を書き出すように設定し、時間ベースのアクセス権を付与した場合は直近の 1 日のみ書き出すように設定できます。

レスポンスには、リクエストで使用された OAuth トークンによって承認された 1 回限りのデータ移植リソース グループ ID と時間ベースのデータ移植リソース グループ ID のリストという 2 つのフィールドが含まれます。ユーザーはトークン付与でアクセスタイプを混在させることはできませんが、今後もその動作を前提とする必要はありません。