您可以使用報表工作,啟動長時間執行的非同步要求,建立 Google Analytics 事件資料的自訂報表。
透過這項要求產生的報表工作資源,可供所有具備 Google Analytics 資源讀取權的使用者存取自訂報表。
自訂報表完成後,您可以 72 小時內下載。超過這個期限後,系統會自動刪除對應的報表工作資源及其內容。
建立報表工作
Google Analytics Data API 第 1 版會使用非同步方法建立報表工作。首先,您必須向 reportTasks.create
方法提出要求,才能建立報表工作。接著,系統會使用 reportTasks.query
方法擷取產生的自訂報表。
此外,您可以使用 reportTasks.get
擷取特定報表工作項的設定中繼資料,並使用 reportTasks.list
列出資源的所有報表工作項。
選取報表實體
Data API v1 的所有方法都需要在網址要求路徑中以 properties/GA_PROPERTY_ID
的格式指定 Google Analytics 資源 ID,例如:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks
報表會根據指定 Google Analytics 資源中收集到的 Google Analytics 事件資料產生。
如果您使用的是 Data API 用戶端程式庫,就不需要手動操作要求網址路徑。大多數 API 用戶端都會提供 property
參數,該參數預期會收到 properties/GA_PROPERTY_ID
格式的字串。如需用戶端程式庫的使用範例,請參閱快速入門指南。
要求建立報表工作
如要建立報表工作,請使用要求中的 ReportTask
物件呼叫 reportTasks.create
方法。以下是必要參數:
reportDefinition
欄位,用於說明自訂報表的定義。這個參數的結構類似於 核心報表方法所使用的報表定義。
報表工作建立要求範例:
HTTP 要求
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
reportTasks.create
方法的回應會在 name
欄位 (例如 properties/1234567/reportTasks/123
) 中包含報表工作名稱,可用於後續查詢,取得報表工作的狀態並擷取結果報表。
HTTP 回應
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
取得報表工作就緒狀態
reportTasks.create
呼叫後,系統可能需要幾分鐘才能產生報告。您可以呼叫 reportTasks.get
方法,取得報表工作項的準備就緒狀態。
使用您從 reportTasks.create
回應收到的報表工作名稱 (例如 properties/1234567/reportTasks/123
),指定報表工作。
範例:
HTTP 要求
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
報表工作項的準備就緒狀態會傳回至回應的 state
欄位。報表產生作業完成後,報表工作狀態會從 CREATING
變更為 ACTIVE
。
reportMetadata
欄位包含產生報表的高階資訊,例如列數和收取配額符記的金額。
HTTP 回應
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
您可以呼叫 reportTasks.list
方法,取得所有報表工作狀態。
擷取產生的報表
使用 reportTasks.create
方法產生報表工作後,請呼叫 reportTasks.query
方法,並指定報表工作名稱 (例如 properties/1234567/reportTasks/123
)。
HTTP 要求
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
如果報表工作已就緒,系統會傳回包含產生報表的回應:
HTTP 回應
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}