このドキュメントでは、Google Analytics Data API v1 の高度な機能である、繰り返しオーディエンス リストについて説明します。オーディエンス リストのエクスポート機能については、オーディエンスのエクスポートの基礎に関するガイドをご覧ください。
繰り返しオーディエンス リストでは、オーディエンス メンバーシップが変更されるたびにオーディエンス リストを毎日生成し、最新のデータを使用できるようにします。
通常の(繰り返しない)オーディエンス リストは、リストが生成された時点でオーディエンスに含まれていたユーザーの静的なリストです。
新しいオーディエンス リストを毎日作成する
1 日のオーディエンス データを処理してメンバーシップを更新するまでにかかる時間は一定ではありません。オーディエンス リストのデータが 24 時間以内に更新されるようにする方法はありません。
たとえば、毎日同じ時間にオーディエンス リストをリクエストしても、オーディエンス リストが前日と同じになる日もあれば、オーディエンス リストが異なり、1 日分のメンバーシップ変更が含まれる日もあります。
オーディエンス リストは、メンバーシップが変更される 1 日前のイベントデータに基づいています。メンバーシップの日次更新が行われる前にオーディエンス リストを作成すると、過去 2 日間のデータが使用されます。メンバーシップが毎日更新されてからオーディエンス リストを作成すると、前日のデータが使用されます。
繰り返しオーディエンス リストに対して定期的にアンケートを実施する
繰り返しオーディエンス リストでは、追加の日付データが利用可能である場合にのみ、オーディエンス リストが生成されます。これにより、新しいオーディエンス リストをいつ作成するかについて推測に頼る必要がなくなります。その代わりに、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 を使用する方法については、WebhookNotification
のドキュメントをご覧ください。
オーディエンスのエクスポートでユーザーを取得する
オーディエンス エクスポートでユーザーを取得するには、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
}