Google アナリティクス 4 のオーディエンスを使用すると、ビジネスの目的に合わせてユーザーをセグメント化できます。オーディエンスを使用すると、共有属性に基づいてサイトやアプリケーションのユーザーをグループ化できます。
Data API を使用すると、ユーザーのスナップショットを含むオーディエンスをエクスポートできます。
オーディエンスのエクスポートに表示されるデータに関する重要な情報については、オーディエンスのエクスポート データの要件に関するガイドをご覧ください。
概要
オーディエンスのエクスポートを作成してクエリするには、次の Data API リクエストを行います。
audienceExports.create
メソッドを呼び出して、オーディエンスのエクスポートを作成します。audienceExports.query
メソッドを呼び出して、オーディエンス内のユーザーを取得します。
詳細については、audienceExports.get
を呼び出すと、特定のオーディエンスのエクスポートに関する構成メタデータを取得できます。また、audienceExports.list
を呼び出して、特定のプロパティのすべてのオーディエンスのエクスポートを一覧表示できます。
レポート エンティティを選択
すべての Data API メソッドで、Google アナリティクス 4 プロパティ識別子を URL リクエストパス内に properties/GA4_PROPERTY_ID
の形式で指定する必要があります。次の例をご覧ください。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/audienceExports
レポートは、指定された Google アナリティクス 4 プロパティで収集された Google アナリティクスのイベントデータに基づいて生成されます。
Data API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを変更する必要はありません。ほとんどの API クライアントには、properties/GA4_PROPERTY_ID
形式の文字列が必要な property
パラメータがあります。クライアント ライブラリの使用例については、クイック スタートガイドをご覧ください。
オーディエンスのエクスポートを作成する
オーディエンスのエクスポートを作成するには、リクエストの AudienceExport
オブジェクトを使用して audienceExports.create
メソッドを呼び出します。次のパラメータを指定します。
audience
フィールドの有効なオーディエンス名(properties/{propertyId}/audiences/{audienceId}
形式)。この値は、Google Analytics Admin API v1 のaudiences.list
メソッドを使用して取得できます。audiences.list
レスポンスのAudience.name
フィールドには、オーディエンス名が含まれます。dimensions
フィールドの有効なディメンションのリスト。このメソッドでサポートされているディメンションの一覧については、オーディエンスのエクスポート スキーマのドキュメントをご覧ください。オーディエンスのエクスポートには、このフィールドで指定されたディメンションのデータのみが含まれます。
オーディエンスのエクスポートを作成するリクエストの例を次に示します。
HTTP リクエスト
POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
"audience": "properties/1234567/audiences/12345",
"dimensions": [
{
"dimensionName": "deviceId"
}
]
}
audienceExports.create
メソッドのレスポンスでは、name
フィールドにオーディエンス エクスポートの名前が含まれます(例: properties/1234567/audienceExports/123
)。レスポンスの例を次に示します。
HTTP レスポンス
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
"name": "properties/1234567/audienceExports/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"state": "CREATING",
"beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}
}
name
を使用すると、オーディエンスのエクスポートからユーザーをクエリできます。
オーディエンスのエクスポートの準備状況をクエリする
audienceExports.create
呼び出し後、オーディエンスのエクスポートが生成されるまでに数分かかることがあります。
オーディエンスのエクスポートの準備状況を確認するには、audienceExports.get
メソッドを呼び出します。
audienceExports.create
レスポンスのオーディエンス エクスポート名を使用して、リクエストでオーディエンス エクスポートを指定します。
リクエストの例を次に示します。
HTTP リクエスト
GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123
オーディエンスのエクスポートの準備状況は、レスポンスの state
フィールドに返されます。オーディエンスのエクスポートの生成が完了すると、状態は CREATING
から ACTIVE
に変わります。
レスポンスの例を次に示します。
HTTP レスポンス
{
"name": "properties/1234567/audienceExports/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"state": "CREATING",
"beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}
すべてのオーディエンス エクスポートの状態を取得するには、audienceExports.list
メソッドを呼び出します。
オーディエンスのエクスポートからユーザーを取得する
オーディエンスのエクスポートが生成されたら、audienceExports.query
メソッドを呼び出し、リクエストでオーディエンスのエクスポートの name
を指定します。
リクエストの例を次に示します。
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
}