時間ベースのアクセスを使用する

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

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

学習内容

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

  • 有効な OAuth トークンを指定して、認証されたリクエストを InitiatePortabilityArchive エンドポイントに送信します。レスポンスには有効な job_id が含まれている必要があります。
  • 認証済みリクエストを GetPortabilityArchiveState エンドポイントに送信します。レスポンスには有効なジョブ状態が含まれ、ジョブが完了している場合は署名付き URL が含まれます。
  • 同じ認証情報を使用して、有効な OAuth トークンを含む認証済みリクエストを InitiatePortabilityArchive エンドポイントに 2 回送信します。最初のリクエストから 24 時間以内にリクエストが行われた場合は、FAILED_PRECONDITION エラーが返されます。

前提条件

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

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

OAuth トークンを取得する

このクイックスタートでは、認可リクエストを送信して URL を使用して OAuth トークンを取得します。このプロセスでは、サーバーサイド ウェブアプリのフローを使用します。このフローでは、後続のエクスポートに使用できる更新トークンが生成されます。

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

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

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
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 日間）を選択します。このクイックスタートでは、[30 日] を選択します。

  4. 同意してアクセス期間を決定すると、リダイレクト URI（https://google.com）に転送されます。アドレスバーに生成された URL には、次の手順で OAuth トークンと交換する認証コードが含まれています。

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

    https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

  5. 認可コードをアクセス トークンと交換するには、次の引数を指定して oauth トークン エンドポイントを呼び出します。

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'

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

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}

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

    refresh_token_expires_in フィールドは秒単位で、ユーザーが 30 日間（2592000 秒）または 180 日間（15552000 秒）のアクセスを選択したかどうかを反映します。アプリの公開ステータスが [テスト] の場合、ユーザーの選択に関係なく、7 日間（604, 800 秒）アクセスできます。

  6. 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 のいずれかに等しくなります。

  7. 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 回限りのアクセス権または時間ベースのアクセス権が付与されているかどうかが決まります。時間ベースのアクセスの場合、次の情報が表示されます。

    {
  "archiveJobId": "<your_job_id>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

    有効な 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 をブラウザに貼り付けて、データ アーカイブをダウンロードします。アーカイブの内容を調べて、想定される検索アクティビティ データが含まれていることを確認する必要があります。

    レスポンスで FAILED ステータスが返された場合は、RetryPortabilityArchive メソッドを使用してエクスポートを再試行できます。

  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 リソースがすでにエクスポートされていること、および再試行できるタイムスタンプが表示されます。

    ...
  "error": {
    "code": 429,
    "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...

  4. 24 時間経過すると、新しいエクスポートをリクエストできますが、まず更新トークンを新しいアクセス トークンと交換する必要があります。

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'

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

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}

    ユーザーがアクセス権を更新すると、新しい有効期限が refresh_token_expires_in フィールドに反映されます。

    新しいアクセス トークンを使用して、InitiatePortabilityArchive と GetPortabilityArchiveState の手順を繰り返すことができます。