Method: properties.runReport

傳回 Google Analytics (分析) 事件資料的自訂報表。報表包含 Google Analytics (分析) 追蹤程式碼收集的資料。API 傳回的資料會以表格形式顯示要求的維度和指標。指標是資源中使用者活動的個別評估,例如活躍使用者或事件計數。維度會根據部分常見條件 (例如國家/地區或事件名稱) 細分指標。

如需建立要求與解讀回應的指南,請參閱製作報表

HTTP 要求

POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:runReport

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
property

string

追蹤事件的 Google Analytics (分析) GA4 資源 ID。會在網址路徑 (而非內文) 中指定。詳情請參閱「如何查看資源 ID」一文。在批次要求中,這個屬性應未指定或與批次層級屬性一致。

範例:Properties/1234

要求主體

要求主體的資料會採用以下結構:

JSON 表示法
{
  "dimensions": [
    {
      object (Dimension)
    }
  ],
  "metrics": [
    {
      object (Metric)
    }
  ],
  "dateRanges": [
    {
      object (DateRange)
    }
  ],
  "dimensionFilter": {
    object (FilterExpression)
  },
  "metricFilter": {
    object (FilterExpression)
  },
  "offset": string,
  "limit": string,
  "metricAggregations": [
    enum (MetricAggregation)
  ],
  "orderBys": [
    {
      object (OrderBy)
    }
  ],
  "currencyCode": string,
  "cohortSpec": {
    object (CohortSpec)
  },
  "keepEmptyRows": boolean,
  "returnPropertyQuota": boolean
}
欄位
dimensions[]

object (Dimension)

要求及顯示的維度。

metrics[]

object (Metric)

要求及顯示的指標。

dateRanges[]

object (DateRange)

要讀取的資料日期範圍。如果要求多個日期範圍,每個回應列都會包含以零為基準的日期範圍索引。如果兩個日期範圍重疊,兩個日期範圍的回應資料列中都會包含重疊天數的事件資料。在同類群組要求中,您必須未指定這個 dateRanges

dimensionFilter

object (FilterExpression)

您可以利用維度篩選器,要求報表中只列出特定維度值。詳情請參閱「維度篩選器基礎知識」一文中的範例。指標無法用於這個篩選器。

metricFilter

object (FilterExpression)

指標的篩選器子句。在匯總報表資料列後套用,與 SQL 包含子句類似。無法在這個篩選器中使用維度。

offset

string (int64 format)

起始資料列的列數。第一個資料列會計為第 0 列。

進行分頁時,第一個要求不會指定 offset;或是同樣地,將 offset 設為 0;第一個要求會傳回資料列的前 limit。第二個要求會將偏移量設為第一個要求的 limit,第二個要求則傳回資料列的第二個 limit

如要進一步瞭解這個分頁參數,請參閱分頁

limit

string (int64 format)

要傳回的列數。如未指定,系統會傳回 10,000 個資料列。無論您請求多少個 API,API 最多只能傳回 250,000 列資料。limit 必須為正數。

如果維度值少於 limit,API 傳回的列數也可以少於要求的 limit。舉例來說,維度「country」的可能值少於 300 個,因此如果只針對「country」製作報表,即使您將 limit 設為較高的值,也無法取得超過 300 列。

如要進一步瞭解這個分頁參數,請參閱分頁

metricAggregations[]

enum (MetricAggregation)

指標匯總。系統會將匯總指標值顯示在 dimensionValues 設為「RESERVED_(MetricAggregation)」的列中。

orderBys[]

object (OrderBy)

指定回應中的資料列排序方式。

currencyCode

string

採用 ISO4217 格式的貨幣代碼,例如「AED」、「USD」、「JPY」。如果這個欄位空白,報表會使用資源的預設貨幣。

cohortSpec

object (CohortSpec)

與這項要求相關聯的同類群組。如果要求中有同類群組群組,則必須顯示「同類群組」維度。

keepEmptyRows

boolean

如果設為 false 或未指定,系統不會傳回所有指標均等於 0 的資料列。如果設為 true,只要篩選器未個別移除這些資料列,系統就會傳回這些資料列。

無論這項 keepEmptyRows 設定為何,報表都只會顯示 Google Analytics (分析) (GA4) 資源記錄的資料。

舉例來說,如果資源從未記錄 purchase 事件,則 eventName 維度和 eventCount 指標的查詢就不會出現資料列 eventName:「purchase」且 eventCount:0。

returnPropertyQuota

boolean

切換是否要傳回這項 Analytics (分析) 資源配額的目前狀態。配額會在 PropertyQuota 中傳回。

回應主體

如果成功,回應主體會包含 RunReportResponse 的執行例項。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics