繰り返しオーディエンス リスト

このドキュメントでは、Google アナリティクス Data API v1 の高度な機能である、定期的なオーディエンス リストについて説明します。オーディエンス リストのエクスポート機能の概要については、オーディエンス エクスポートの基本ガイドをご覧ください。

定期的なオーディエンス リストでは、オーディエンス メンバーシップが変更されるたびに毎日オーディエンス リストが生成されるため、最新のデータを使用できます。

通常（非定期）のオーディエンス リストは、リストの生成時にオーディエンスに含まれていたユーザーの静的リストです。

新しいオーディエンス リストを毎日作成する

1 日分のオーディエンス データの処理とメンバーシップの更新には、時間がかかります。ユーザーリストのデータが 24 時間以内に更新されるという保証はありません。

たとえば、毎日同じ時間にオーディエンス リストをリクエストしても、前日と同じオーディエンス リストが返される日もあれば、前日と異なるオーディエンス リストが返される日もあります。後者の場合、メンバーシップが 1 日分変更されていることがわかります。

新しいオーディエンス リストを毎日作成する

オーディエンス リストは、最新のメンバーシップ変更の 1 日前のイベントデータに基づいています。メンバーシップが毎日更新される前にオーディエンス リストを作成した場合、2 日前のデータが使用されます。メンバーシップの日次更新後にオーディエンス リストを作成した場合、昨日のデータが使用されます。

定期的なオーディエンス リストを定期的にポーリングする

定期的なオーディエンス リストは、追加の 1 日分のデータを利用できる場合にのみ生成されます。これにより、新しいオーディエンス リストを作成するタイミングを推測する必要がなくなります。代わりに、1 日を通して定期的なオーディエンス リストを低コストでポーリングして、追加のデータを入手できるかどうかを確認できます。

1 日を通して定期的に繰り返し発生するオーディエンス リストをポーリングする

定期的なオーディエンス リストを作成する

定期的なオーディエンス リストを作成するには、リクエストで RecurringAudienceList オブジェクトを使用して recurringAudienceLists.create メソッドを呼び出します。次のパラメータを指定します。

  • audience フィールドの有効なオーディエンス名（properties/{propertyId}/audiences/{audienceId} 形式）。この値を取得するには、Google Analytics Admin API v1 の audiences.list メソッドを使用します。audiences.list レスポンスの Audience.name フィールドには、オーディエンス名が含まれます。
  • dimensions フィールドの有効なディメンションのリスト。このメソッドでサポートされているディメンションのリストについては、オーディエンス エクスポート スキーマのドキュメントをご覧ください。オーディエンス リストには、このフィールドに記載されているディメンションのデータのみが含まれます。

定期的なオーディエンス リストの作成リクエストの例を次に示します。

HTTP リクエスト

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

recurringAudienceLists.create メソッドのレスポンスには、name フィールドに名前（properties/1234567/recurringAudienceLists/123 など）が含まれます。この名前は、後続のクエリでこの定期的なオーディエンス リストの構成メタデータを取得するために使用できます。また、構成メタデータには、この定期的なオーディエンス リスト用に作成されたオーディエンス リスト インスタンスのリソース名も含まれます。

HTTP レスポンス

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

ポーリング構成メタデータ

recurringAudienceLists.get メソッドを使用して、特定の定期的なオーディエンス リストに関する構成メタデータを取得します。構成メタデータには、この定期的なオーディエンス リスト用に作成されたオーディエンス リスト インスタンスのリソース名が含まれています。

次の例をご覧ください。

HTTP リクエスト

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

レスポンスで RecurringAudienceList のインスタンスが返されます。このファイルには、この定期的なオーディエンス リスト用に作成されたオーディエンス リスト インスタンスのリソース名などの構成メタデータが含まれています。

HTTP レスポンス

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

recurringAudienceLists.list を使用すると、プロパティのすべての定期的なオーディエンス リストを一覧表示できます。

Webhook を使用して、新しいオーディエンス リストに関する非同期通知を受信する

recurringAudienceLists.get メソッドを使用して特定の定期的なオーディエンス リストに関する構成メタデータを定期的にポーリングする代わりに、オーディエンス リストが利用可能になったときに非同期で Webhook 通知を受け取ることができます。

Webhook 通知を構成するには、新しい定期的なオーディエンス リストを作成するときに webhookNotification フィールドを指定します。

Google アナリティクス Data API v1 で Webhook を使用する方法については、Async audience lists with webhooks ガイドをご覧ください。

オーディエンス エクスポート内のユーザーを取得する

オーディエンス エクスポート内のユーザーを取得するには、audienceExports.query メソッドを呼び出し、recurringAudienceLists.get または recurringAudienceLists.list から提供された構成メタデータから取得したオーディエンス エクスポート名を指定します。

HTTP リクエスト

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

オーディエンス エクスポートの準備が整うと、オーディエンス内のユーザーのリストを含むレスポンスが返されます。

HTTP レスポンス

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}