Google Analytics (分析) 4 目標對象可讓您根據自家業務的需求區隔使用者。目標對像功能可讓您根據共用屬性,將網站或應用程式的使用者分組。
您可以使用 Data API 匯出目標對象 (包括使用者數據匯報)。
如要瞭解目標對象匯出功能中的資料相關重要資訊,請參閱「目標對象匯出資料預期」指南。
總覽
提出下列 Data API 要求,以建立及查詢目標對象匯出作業:
- 呼叫
audienceExports.create
方法來建立目標對象匯出項目。 - 呼叫
audienceExports.query
方法可用來擷取目標對像中的使用者。
如需詳細資訊,您可以呼叫 audienceExports.get
來擷取特定目標對象匯出作業的設定中繼資料,並呼叫 audienceExports.list
列出特定資源的所有目標對象匯出作業。
選取報表實體
所有 Data API 方法都需要以 properties/GA4_PROPERTY_ID
格式在網址要求路徑中指定 Google Analytics (分析) 4 資源 ID。範例如下:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/audienceExports
系統會根據指定 Google Analytics (分析) 4 資源中收集到的 Google Analytics (分析) 事件資料產生報表。
如果您使用其中一個 Data API 用戶端程式庫,就不必變更要求網址路徑。大多數的 API 用戶端都會提供 property
參數,該參數預期使用 properties/GA4_PROPERTY_ID
形式的字串。如需用戶端程式庫的使用範例,請參閱快速入門指南。
建立目標對象匯出作業
如要建立目標對象匯出作業,請使用要求中的 AudienceExport
物件呼叫 audienceExports.create
方法。以下是必要參數:
- 在
audience
欄位中的有效目標對象名稱,格式為properties/{propertyId}/audiences/{audienceId}
。您可以使用 Google Analytics Admin API 第 1 版的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
}