Method: properties.runReport

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

HTTP 要求

POST https://analyticsdata.googleapis.com/v1alpha/{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)
    }
  ],
  "conversionSpec": {
    object (ConversionSpec)
  }
}
欄位
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)

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

object (ConversionSpec)

(選用步驟) 控管轉換報表。這是選填欄位。如果設定這個欄位或要求任何轉換指標，報表就會是轉換報表。

回應主體

與要求對應的回覆報表表格。

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

JSON 表示法 
{
  "dimensionHeaders": [
    {
      object (DimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (MetricHeader)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totals": [
    {
      object (Row)
    }
  ],
  "maximums": [
    {
      object (Row)
    }
  ],
  "minimums": [
    {
      object (Row)
    }
  ],
  "rowCount": integer,
  "metadata": {
    object (ResponseMetaData)
  },
  "propertyQuota": {
    object (PropertyQuota)
  },
  "kind": string,
  "nextPageToken": string
}
欄位
dimensionHeaders[]

object (DimensionHeader)

說明維度資料欄。DimensionHeaders 的數量和順序與資料列中的維度相符。
metricHeaders[]

object (MetricHeader)

說明指標資料欄。MetricHeaders 的數量和順序與資料列中的指標相符。
rows[]

object (Row)

報表中的維度值組合和指標值列。
totals[]

object (Row)

指標的總值 (如有要求)。
maximums[]

object (Row)

如果要求，指標的最大值。
minimums[]

object (Row)

如果要求，則為指標的最小值。
rowCount

integer

查詢結果中的資料列總數，無論回應中傳回的資料列數為何。舉例來說，如果查詢傳回 175 列，且 API 要求中包含 limit = 50，則回應會包含 rowCount = 175，但只有 50 列。

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

object (ResponseMetaData)

報表的中繼資料。
propertyQuota

object (PropertyQuota)

這項 Analytics 資源的配額狀態，包括這項要求。
kind

string

表示這則訊息的資源種類。這個 kind 一律是固定字串「analyticsData#runReport」。有助於區分 JSON 中的回應類型。
nextPageToken

string

可做為 pageToken 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。

授權範圍

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

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

比較

定義個別比較項目。大多數要求都會包含多項比較，因此報表會比較這些比較結果。

JSON 表示法 
{
  "name": string,

  // Union field one_comparison can be only one of the following:
  "dimensionFilter": {
    object (FilterExpression)
  },
  "comparison": string
  // End of list of possible types for union field one_comparison.
}
欄位
name

string

每個比較項目都會在回應中產生不同的資料列。在回應中，系統會透過這個名稱識別這項比較。如未指定名稱，系統會使用已儲存的比較項目顯示名稱。

聯集欄位 one_comparison。

one_comparison 只能是下列其中一項：
dimensionFilter

object (FilterExpression)

基本比較。
comparison

string

以比較項目的資源名稱識別已儲存的比較項目。例如「comparisons/1234」。

ConversionSpec

控管轉換報表。

JSON 表示法 
{
  "conversionActions": [
    string
  ],
  "attributionModel": enum (AttributionModel)
}
欄位
conversionActions[]

string

要納入報表的轉換動作 ID。如果留空，系統會納入所有轉換。您可以透過 properties.getMetadata 方法的回應，從 conversions 清單中的 conversionAction 欄位擷取有效的轉換動作 ID。例如「conversionActions/1234」。
attributionModel

enum (AttributionModel)

要在轉換報表中使用的歸因模式。如未指定，則會使用 DATA_DRIVEN。

AttributionModel

轉換報表使用的歸因模式

列舉
ATTRIBUTION_MODEL_UNSPECIFIED 未指定歸因模式。
DATA_DRIVEN 歸因是根據付費和自然隨機資料驅動模式
LAST_CLICK 歸因依據為「付費和自然最終點擊」模式