Data Portability API の使用を開始する

このクイックスタートでは、アカウントの OAuth トークンを取得し、Data Portability API エンドポイントに 1 回限りのリクエストを送信します。

このクイックスタートでは、Data Portability API を使用してユーザーデータに 1 回だけアクセスする方法について説明します。ユーザーデータへの継続的なアクセスについては、時間ベースのアクセスを使用するをご覧ください。リクエストに時間フィルタを適用する方法については、時間フィルタを適用するをご覧ください。

学習内容

このクイックスタートでは、次の方法について学習します。

  • 有効な OAuth トークンを指定して、認証されたリクエストを InitiatePortabilityArchive エンドポイントに送信します。レスポンスには有効な job_id が含まれている必要があります。
  • 認証済みリクエストを GetPortabilityArchiveState エンドポイントに送信します。レスポンスには有効なジョブ状態が含まれ、ジョブが完了すると署名付き URL が含まれます。
  • （省略可）同じ認証情報を使用して、有効な OAuth トークンを含む認証済みリクエストを InitiatePortabilityArchive エンドポイントに 2 回送信します。これにより RESOURCE_EXHAUSTED エラーが返され、ResetAuthorization エンドポイントの重要性が強調されます。
  • 認証済みリクエストを ResetAuthorization エンドポイントに送信します。このリクエストにより、ユーザーが付与したすべての OAuth スコープが取り消されます。
  • （省略可）以前に使用した OAuth トークンを使用して、InitiatePortabilityArchive エンドポイントにリクエストを送信します。承認がリセットされると、リクエストは失敗します。

前提条件

このクイックスタートを実行するには、以下が必要です。

  • ユーザーが Data Portability API を利用できることを確認します。サポートされている国と地域の一覧については、[データのコピーをサードパーティと共有する] ページのよくある質問をご覧ください。
  • Data Portability API の設定手順を完了します。
  • 手順に沿って、JavaScript ウェブアプリの OAuth を構成します。本番環境では、通常、ウェブサーバー アプリケーション用の OAuth フローなど、別のフローを使用します。このクイックスタートでは、簡潔にするため JavaScript ウェブアプリのフローを使用します。
    • 認証情報を作成するときに、OAuth 2.0 クライアント ID と承認済みのリダイレクト URI（https://google.com など）をメモします。これらの値は、クイックスタートの後半で必要になります。
    • Data Portability API のスコープを構成する際は、このクイックスタートで myactivity.search リソース グループ（https://www.googleapis.com/auth/dataportability.myactivity.search）が使用されることに注意してください。
    • アクセスを許可する時間を指定すると、このクイックスタートでは1 回限りのアクセスが使用されます。
  • OAuth トークンを取得します。
  • 組織が所有または管理するアカウントへのアクセス権を取得します。このクイックスタートでは、このアカウントの検索アクティビティ データがエクスポートされます。

OAuth トークンを取得する

このクイックスタートでは、認可リクエストを送信して URL を使用して OAuth トークンを取得します。このプロセスでは、JavaScript ウェブアプリのフローを使用します。このフローでは更新トークンは返されません。

本番環境のアプリでは、通常、OAuth フローを使用して更新トークンを取得し、必要に応じてアクセス トークンを生成します。たとえば、サーバーサイド ウェブアプリのフローがこれに該当します。

OAuth トークンを取得するには:

  1. 次のような URL を作成します。

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value

    URL の場合:

    • client_id は OAuth クライアント ID です。
    • redirect_uri は、承認済みリダイレクト URI です（例: https://google.com）。

    このクイックスタートの URL で使用されているスコープは、検索アクティビティ スコープです。YouTube アクティビティ スコープまたは両方のスコープを使用することもできます。

  2. URL をブラウザのアドレスバーに貼り付け、OAuth フローの手順に沿って操作します。このフローでは、このクイックスタートで使用する、組織が所有または管理するアカウントにログインする必要があります。

    これは、OAuth スコープに同意するアカウントです。同意画面は次のようになります（画面上のテキストは、この画像のテキストとは異なる場合があります）。

    ユーザーが検索アクティビティ データへのアクセスを許可することに同意する同意画面

  3. アクセス権を付与するスコープと、アカウントのデータへのアクセス権を共有する期間（1 回、30 日間、180 日間）を選択します。このクイックスタートでは、[1 回のみ] を選択します。

  4. 同意してアクセス期間を選択すると、リダイレクト URI（https://google.com）に転送されます。アドレスバーに生成された URL には、OAuth アクセス トークンが含まれています。

    たとえば、ユーザー アカウントが dataportability.myactivity.search スコープへの OAuth アクセスを許可している場合、生成される URL は次のようになります。

    https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

    URL の your_OAuth_token は、トークンを表す文字列です。

  5. OAuth トークンを検証するには、次の URL をブラウザに貼り付けます。

    https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

    レスポンスは次のようになります。

    {
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}

    リクエストを送信するために azp フィールドや aud フィールドを使用する必要はありません。azp フィールドは、承認済みプレゼンターの client_id を表します。aud フィールドは、このトークンの対象となるオーディエンスを識別します。これは、アプリのクライアント ID のいずれかと同じになります。

  6. OAuth トークンと API キーを取得します。Data Portability API を呼び出すには、これらが必要です。

エンドポイントにリクエストを送信する

このクイックスタートでは、curl コマンドを使用して Data Portability API エンドポイントを呼び出します。これらのコマンドには、前述で取得した OAuth トークンと API キーが必要です。

Data Portability API を呼び出すには:

  1. まず、認証済みリクエストを InitiatePortabilityArchive エンドポイントに送信します。このリクエストにより、アーカイブ ジョブが開始されます。

    次の curl コマンドを実行します。

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    コマンドは次のように変更してください。

    • your_OAuth_token は OAuth トークンです。

    InitiatePortabilityArchive リクエストは job_id と accessType を返します。ジョブ ID はデータ アーカイブの状態を取得するために使用され、アクセスタイプによって、データへの 1 回限りのアクセス権または時間ベースのアクセス権が付与されているかどうかが決まります。このクイックスタートでは、1 回限りのアクセス権が必要です。

    {
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}

    有効な OAuth トークンを指定しなかった場合、次のエラー メッセージが返されます。

    Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.

  2. 次に、認証済みリクエストを GetPortabilityArchiveState エンドポイントに送信して、アーカイブ ジョブのステータスを取得します。

    次の curl コマンドを実行します。

    curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState

    コマンドは次のように変更してください。

    • your_OAuth_token は OAuth トークンです。
    • your_job_id は、InitiatePortabilityArchive リクエストによって返されたジョブ ID です。

    レスポンスは、ジョブの状態に基づいています。ジョブが完了していない場合、レスポンスには現在の状態が示されます。ジョブが完了するまで、このエンドポイントに定期的にリクエストを送信する必要があります。

    {
  "state": "IN_PROGRESS"
}

    ジョブが完了している場合、レスポンスには状態と、データ アーカイブのダウンロードに使用される 1 つ以上の署名付き URL が含まれます。

    {
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}

    署名付き URL をブラウザに貼り付けて、データ アーカイブをダウンロードします。アーカイブの内容を調べて、想定される検索アクティビティ データが含まれていることを確認する必要があります。

  3. （省略可）前のコマンドを繰り返して、認証済みリクエストを InitiatePortabilityArchive エンドポイントに送信します。

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    コマンドは次のように変更してください。

    • your_OAuth_token は OAuth トークンです。

    レスポンスには、このユーザーの myactivity.search リソースに対する 1 回限りの同意が期限切れであることを示す必要があります。

    ...
"error": {
    "code": 429,
    "message": "Requested resources have already been exported. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

  4. 認証済みリクエストを ResetAuthorization エンドポイントに送信します。このリクエストにより、ユーザーが付与したすべての OAuth スコープが取り消され、すでに使用しているリソース グループに対して InitiatePortabilityArchive を呼び出せるようになります。

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset

    コマンドは次のように変更してください。

    • your_OAuth_token は OAuth トークンです。

    このコマンドは空のレスポンスを返します。

  5. （省略可）認可をリセットしたら、InitiatePortabilityArchive エンドポイントに別のリクエストを送信します。前回使用したのと同じ curl コマンドを使用します。

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    コマンドは次のように変更してください。

    • your_OAuth_token は OAuth トークンです。

    指定した OAuth トークンが取り消されているため、レスポンスでエラーが返されます。

    ...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }