Method: properties.runReport

傳回 Google Analytics 事件資料的自訂報表。報表中的統計資料是根據 Google Analytics 追蹤程式碼收集的資料計算得出。API 傳回的資料會以表格形式呈現，其中包含所要求維度和指標的資料欄。指標是評估資源中使用者活動的個別測量結果，例如活躍使用者或事件計數。維度會依據國家/地區或事件名稱等常見條件，細分指標。

如需建構要求和解讀回應的指南，請參閱「建立報表」。

HTTP 要求

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

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

路徑參數

參數
property

string

要追蹤事件的 Google Analytics 資源 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,
  "comparisons": [
    {
      object (Comparison)
    }
  ]
}
欄位
dimensions[]

object (Dimension)

要求和顯示的維度。
metrics[]

object (Metric)

要求和顯示的指標。
dateRanges[]

object (DateRange)

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

object (FilterExpression)

維度篩選器可讓您只要求報表中的特定維度值。如需更多範例，請參閱「維度篩選器基本概念」。這個篩選條件無法使用指標。
metricFilter

object (FilterExpression)

指標的篩選子句。在匯總報表資料列後套用，類似於 SQL 的 having 子句。這個篩選器無法使用維度。
offset

string (int64 format)

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

分頁時，第一個要求不會指定偏移量，或等同於將偏移量設為 0；第一個要求會傳回前 limit 列。第二個要求會將偏移量設為第一個要求的 limit，並傳回第二個 limit 的資料列。

如要進一步瞭解這個分頁參數，請參閱「分頁」。
limit

string (int64 format)

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

如果維度值的數量少於要求的 limit，API 也可能會傳回少於 limit 的資料列。舉例來說，維度 country 的可能值少於 300 個，因此即使將 limit 設為較高的值，只針對 country 產生報表時，最多也只會顯示 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 資源記錄的資料。

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

boolean

切換是否要傳回這個 Google Analytics 資源的配額目前狀態。配額會以 PropertyQuota 形式傳回。
comparisons[]

object (Comparison)

(選用步驟) 要求和顯示的比較設定。要求只需要比較欄位，即可在回應中收到比較欄。

回應主體

如果成功，回應主體會包含 RunReportResponse 的執行個體。

授權範圍

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

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