Data Portability API の使用を開始する

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

学習内容

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

  • 有効な 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）を使用します。
  • 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&
include_granted_scopes=true&
state=developer-specified-value

    URL で次のようにします。

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

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

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

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

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

  3. 同意すると、リダイレクト 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> はトークンを表す文字列です。

  4. 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"
}

  5. 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 トークンです。

    注: resources パラメータには、アクセス権が付与された OAuth スコープのみを含める必要があります。この例では、myactivity.search のみが付与されています。追加のリソース グループを含めると、エラーが返されます。

    InitiatePortabilityArchive リクエストは job_id を返します。このジョブ ID は、データ アーカイブの状態を取得するために使用されます。

    {
  "archiveJobId": "<your_job_id>"
}

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

    {
  "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": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

  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"
  }