リクエストに時間フィルタを適用する

このクイックスタートでは、アカウントの OAuth トークンを取得し、タイムスタンプを使用して Data Portability API エンドポイントにリクエストを送信して、エクスポートされたデータをフィルタします。

このクイックスタートでは、時間ベースのアクセスで Data Portability API を使用し、サポートされているリソースに時間フィルタを適用する方法について説明します。ユーザーデータへの時間ベースのアクセスの詳細については、時間ベースのアクセスを使用するをご覧ください。

学習内容

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

  • InitiatePortabilityArchive エンドポイントに認証済みのリクエストを定期的に送信して、前回のエクスポート以降の新しいデータのみをエクスポートします。
  • InitiatePortabilityArchive エンドポイントに認証済みリクエストを送信して、過去 6 か月間のデータのみをエクスポートします。
  • 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）が使用されることに注意してください。
    • アクセスを許可する時間を選択する場合は、時間ベースのアクセスで時間フィルタリングをテストするために [30 日間] を選択する必要があります。（時間フィルタは 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 で使用されているスコープは、検索アクティビティ スコープです。TimeFilter をサポートする任意のスコープを使用できます。

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

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

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

  3. アクセス権を付与するスコープと、アカウントのデータへのアクセス権を共有する期間（1 回、30 日間、180 日間）を選択します。このクイックスタートでは、[30 日] を選択します。（期間のフィルタは 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 キーが必要です。

前回のエクスポートのデータ

時間ベースのアクセスで時間フィルタを使用すると、前回エクスポートしたとき以降の新しいデータをエクスポートできます。たとえば、スコープ https://www.googleapis.com/auth/dataportability.myactivity.search について考えてみましょう。

  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 リクエストは archiveJobId と accessType を返します。ジョブ ID はデータ アーカイブの状態を取得するために使用され、アクセスタイプによって、データへの 1 回限りのアクセス権または時間ベースのアクセス権が付与されているかどうかが決まります。時間ベースのアクセスの場合、次の情報が表示されます。

    {
  "archiveJobId": "<your_job_id_1>"
  "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_1/portabilityArchiveState

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

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

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

    {
  "state": "IN_PROGRESS"
}

    ジョブが完了している場合、レスポンスには状態と、データ アーカイブのダウンロードに使用される 1 つ以上の署名付き URL が含まれます。また、InitiatePortabilityArchive が最初に呼び出されたときのタイムスタンプを示す export_time フィールドもあります。

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

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

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

  3. 24 時間以上待ってから、手順 1 と同じコマンドを使用して InitiatePortabilityArchive に再度リクエストを送信します。ただし、今回は start_time として export_time を使用します。

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

    時間ベースのアクセスの場合、次が返されます。

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

  4. 手順 2 を繰り返して、認証済みリクエストを GetPortabilityArchiveState エンドポイントに送信し、アーカイブ ジョブのステータスを取得します（<your_job_id_2> を使用）。

  5. ジョブが完了すると、レスポンスは次のようになります。

      {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

  6. 2 回目のエクスポートのデータに、1 回目のエクスポート後に生成された新しいデータのみが含まれていることを確認します。

過去 6 か月間のデータ

時間フィルタを使用して、コーパス全体ではなく最新のデータのみをエクスポートすることもできます。

  1. 今日の日付が 2024-10-01 で、過去 6 か月間のデータをエクスポートするとします。まず、start_time が「2024-04-01T00:00:00Z」の認証済みリクエストを InitiatePortabilityArchive エンドポイントに送信します。

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

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

    時間ベースのアクセスの場合、次が返されます。

    {
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

  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/job_id_1/portabilityArchiveState

    ジョブが完了すると、レスポンスは次のようになります。

    {
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}

    start_time は手順 1 で指定した start_time であり、export_time は手順 1 で InitiatePortabilityArchive が呼び出されたときのタイムスタンプです。

  3. エクスポートに過去 6 か月間のデータのみが含まれていることを確認します。

特定の期間のデータ

期間フィルタを使用すると、2023 年のデータのみなど、特定の期間のデータのみをエクスポートできます。

  1. まず、start_time が「2023-01-01T00:00:00Z」、end_time が「2023-12-31T23:59:59Z」の認証済みリクエストを InitiatePortabilityArchive エンドポイントに送信します。

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

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

    時間ベースのアクセスの場合、次が返されます。

    {
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

  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/job_id_1/portabilityArchiveState

    ジョブが完了すると、レスポンスは次のようになります。

    {
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

    start_time はステップ 1 で指定した start_time であり、export_time はステップ 1 で指定した end_time と同じであることに注意してください。

  3. エクスポートに 2023 年のデータのみが含まれていることを確認します。

サポートされているスコープ

次のスコープでは時間フィルタがサポートされています。

  • https://www.googleapis.com/auth/dataportability.myactivity.youtube
  • https://www.googleapis.com/auth/dataportability.myactivity.maps
  • https://www.googleapis.com/auth/dataportability.myactivity.search
  • https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
  • https://www.googleapis.com/auth/dataportability.myactivity.shopping
  • https://www.googleapis.com/auth/dataportability.myactivity.play
  • https://www.googleapis.com/auth/dataportability.chrome.history

注意: サポートされているスコープとサポートされていないスコープが混在する時間フィルタリング リクエストは、The requested resources do not support time filters を示す INVALID_ARGUMENT エラーになります。