您可以使用報表工作，啟動長時間執行的非同步要求，建立 Google Analytics 事件資料的自訂報表。
凡是對 Google Analytics 資源具備讀取權限的使用者，都能使用這項要求產生的報表任務資源，存取自訂報表。
自訂報表會在準備就緒後保留 72 小時。超過這個期限後，系統會自動刪除對應的報表工作資源和內容。
建立報表工作
Google Analytics Data API v1 採用非同步方式建立報表工作。首先，您必須向 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"
}
}
後續步驟
- 試用互動式非同步報表工作 Colab 筆記本，使用 Python 用戶端程式庫建立、監控及查詢非同步報表工作。
- 查看
properties.reportTasksREST API 參考資料。 - 進一步瞭解 Data API 配額和限制。