Method: properties.batchRunReports

批次傳回多份報表。所有報表都必須來自同一個 GA4 資源。

HTTP 要求

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

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

路徑參數

參數
property

string

要追蹤事件的 Google Analytics GA4 資源 ID。指定在網址路徑，而不是內文。詳情請參閱「如何查看資源 ID」一文。必須為批次指定此屬性。RunReportRequest 中的屬性可能未指定或與這個屬性一致。

範例：properties/1234

要求主體

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

JSON 表示法 
{
  "requests": [
    {
      object (RunReportRequest)
    }
  ]
}
欄位
requests[]

object (RunReportRequest)

個別要求。每個請求都有個別的報表回應。每個批次要求最多可包含 5 個要求。

回應主體

包含多份報表的批次回應。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "reports": [
    {
      object (RunReportResponse)
    }
  ],
  "kind": string
}
欄位
reports[]

object (RunReportResponse)

個別回應。每個回應都有個別的報表要求。
kind

string

識別這則訊息的資源類型。此 kind 一律為固定字串「analyticsData#batchRunReports」。有助於區分 JSON 回應類型。

授權範圍

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

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

RunReportRequest

產生報表的要求。

JSON 表示法 
{
  "property": string,
  "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)
    }
  ]
}
欄位
property

string

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

範例：properties/1234
dimensions[]

object (Dimension)

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

object (Metric)

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

object (DateRange)

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

object (FilterExpression)

維度篩選器，在報表中篩選出特定維度值。詳情請參閱「維度篩選器的基本知識」一文。無法在這個篩選器中使用指標。
metricFilter

object (FilterExpression)

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

string (int64 format)

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

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

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

string (int64 format)

要傳回的列數。如未指定，系統會傳回 10,000 列。無論您要求多少列，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 中傳回。
comparisons[]

object (Comparison)

選用設定。要求及顯示的比較設定。這項要求只需要比較欄位，即可在回應中接收比較資料欄。