このドキュメントでは、Google Analytics Data API v1 の上級者向け機能である、繰り返しオーディエンス リストについて説明します。オーディエンス リストのエクスポート機能の概要については、オーディエンスのエクスポートの基本ガイドをご覧ください。
繰り返しオーディエンス リストは、オーディエンス メンバーシップが変更されると、オーディエンス リストを毎日生成し、最新のデータを操作できるようにします。
通常の(繰り返しなしの)オーディエンス リストは、リストの生成時にオーディエンスに属しているユーザーの静的なリストです。
新しいオーディエンス リストを毎日作成する
1 日分のオーディエンス データを処理してメンバーシップを更新するのにかかる時間は、状況によって異なります。オーディエンス リストのデータが 24 時間以内に更新されるとは限りません。
たとえば、毎日同じ時間にオーディエンス リストをリクエストしても、オーディエンス リストが前日と同じ日もあれば、オーディエンス リストが異なり、メンバーシップの変更が 1 日分追加されている日もあります。

オーディエンス リストは、最新のメンバーシップ変更の 1 日前のイベントデータに基づいています。1 日のメンバーシップ更新が行われる前にオーディエンス リストを作成すると、2 日前のデータが使用されます。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 Analytics 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
}