傳回 Google Analytics (分析) 事件資料的自訂報表。報表包含由 Google Analytics (分析) 追蹤程式碼收集到的資料衍生的統計資料。API 傳回的資料會以表格形式呈現,所請求維度和指標的欄。指標則是針對資源中的使用者活動所做的個別評估,例如活躍使用者或事件計數。維度會依部分常見條件細分指標,例如國家/地區或事件名稱。
如要瞭解如何建立要求及解讀回應,請參閱建立報表。
HTTP 要求
POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:runReport
這個網址使用 gRPC 轉碼語法。
路徑參數
參數 | |
---|---|
property |
Google Analytics (分析) GA4 資源 ID,其中包含追蹤事件的相關資料。已在網址路徑指定,而非主體。詳情請參閱「查看資源 ID 的方式」一文。在批次要求中,此屬性應未指定,或是與批次層級屬性一致。 範例:properties/1234 |
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "dimensions": [ { object ( |
欄位 | |
---|---|
dimensions[] |
要求及顯示的維度。 |
metrics[] |
要求及顯示的指標, |
dateRanges[] |
要讀取的資料日期範圍。如果要求多個日期範圍,則每個回應列都會包含以 0 為基礎的日期範圍索引。如果兩個日期範圍重疊,這兩個日期範圍的事件資料會納入這兩個日期範圍的回應列中。在同類群組要求中,不得指定這個 |
dimensionFilter |
維度篩選器可讓您在報表中只要求特定維度值。詳情請參閱「維度篩選器基礎知識」一文。這個篩選器無法使用指標。 |
metricFilter |
指標的篩選器子句。與 SQL 有子句類似,在匯總報表資料列後套用。無法在這個篩選器中使用維度。 |
offset |
起始資料列的列數。第一列會計為第 0 列。 進行分頁時,第一個要求不會指定偏移值,或同樣地將偏移值設為 0;第一個要求會傳回資料列的前 如要進一步瞭解這個分頁參數,請參閱分頁。 |
limit |
要傳回的列數。如果未指定,則會傳回 10,000 列。無論您要求的數量為何,API 每個要求最多只能傳回 250,000 個資料列。 如果維度值數量不是 如要進一步瞭解這個分頁參數,請參閱分頁。 |
metricAggregations[] |
指標匯總。匯總指標值會顯示在 DimensionsValue 設為「RESERVED_(MetricAggregation)」的資料列中。 |
orderBys[] |
指定資料列在回應中的排序方式。 |
currencyCode |
採用 ISO4217 格式的貨幣代碼,例如「AED」、「USD」、「JPY」。如果這個欄位空白,報表會使用資源的預設貨幣。 |
cohortSpec |
與這項要求相關聯的同類群組。如果請求中有同類群組群組,就必須顯示「同類群組」維度。 |
keepEmptyRows |
如為 false 或未指定,則不會傳回所有指標等於 0 的每一列。如果設為 true,如果未遭到篩選器單獨移除,系統就會傳回這些資料列。 無論這項 舉例來說,如果資源從未記錄 |
returnPropertyQuota |
切換是否要傳回這項 Analytics (分析) 資源的配額目前的狀態。系統會在 PropertyQuota 中傳回配額。 |
comparisons[] |
選用設定。要求及顯示的比較設定。這項要求只需要比較欄位,就能在回應中接收比較資料欄。 |
回應主體
如果成功,回應主體會包含 RunReportResponse
的執行例項。
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/analytics.readonly
https://www.googleapis.com/auth/analytics