Google Analytics 中的目標對象可讓您根據自家業務的需求區隔使用者。您可以使用目標對象,根據共用屬性將網站或應用程式的使用者分組。
您可以使用 Data API 匯出目標對象,包括使用者的快照。
如要進一步瞭解目標對象匯出資料的預期內容,請參閱目標對象匯出資料預期內容指南。
總覽
提出下列 Data API 要求,即可建立及查詢目標對象匯出作業:
- 呼叫
audienceExports.create
方法,建立目標對象匯出作業。 - 呼叫
audienceExports.query
方法,用於擷取目標對象中的使用者。
如需更多資訊,您可以呼叫 audienceExports.get
來擷取特定目標對象匯出作業的設定中繼資料,並呼叫 audienceExports.list
來列出特定資源的所有目標對象匯出作業。
選取報表實體
所有 Data API 方法都需要在網址要求路徑中指定 Google Analytics 資源 ID,格式為 properties/GA_PROPERTY_ID
。範例如下:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports
報表會根據指定 Google Analytics 資源中收集到的 Google Analytics 事件資料產生。
如果您使用的是其中一種 Data API 用戶端程式庫,就不需要變更要求網址路徑。大多數 API 用戶端都會提供 property
參數,該參數會預期 properties/GA_PROPERTY_ID
格式的字串。如需用戶端程式庫的使用範例,請參閱快速入門指南。
建立目標對象匯出作業
如要建立目標對象匯出作業,請使用要求中的 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
}