REST Resource: properties.reportTasks

資源:ReportTask

特定報表工作設定。

JSON 表示法
{
  "name": string,
  "reportDefinition": {
    object (ReportDefinition)
  },
  "reportMetadata": {
    object (ReportMetadata)
  }
}
欄位
name

string

僅供輸出。ID。建立時指派的報表工作資源名稱。格式:「properties/{property}/reportTasks/{reportTask}」

reportDefinition

object (ReportDefinition)

(選用步驟) 用於擷取報表資料的報表定義,說明報表結構。通常包括報表要納入的欄位,以及用於篩選資料的條件。

reportMetadata

object (ReportMetadata)

僅供輸出。特定報表工作的報表中繼資料,提供報表相關資訊。通常包括下列資訊:報表的資源名稱、報表狀態、報表建立時間戳記等。

ReportDefinition

報表的執行方式定義。

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,
  "samplingLevel": enum (SamplingLevel)
}
欄位
dimensions[]

object (Dimension)

(選用步驟) 要求和顯示的維度。

metrics[]

object (Metric)

(選用步驟) 要求和顯示的指標。

dateRanges[]

object (DateRange)

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

dimensionFilter

object (FilterExpression)

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

metricFilter

object (FilterExpression)

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

offset

string (int64 format)

(選用步驟) Google Analytics 儲存空間中起始列的列數。第一列會計為第 0 列。

建立報表工作時,offsetlimit 參數會定義要納入所產生報表的 Google Analytics 儲存空間資料列子集。舉例來說,如果 Google Analytics 儲存空間共有 300,000 列,初始報表工作可能會有前 10,000 列,限制為 10,000 列,偏移量為 0。隨後,另一項報表工作可能會涵蓋接下來的 10,000 個資料列,限制為 10,000 個,偏移量為 10,000。

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 的資料列。

samplingLevel

enum (SamplingLevel)

(選用步驟) 報表的取樣層級。

維度

維度是資料的屬性。舉例來說,「城市」維度會指出事件的來源城市。報表回應中的維度值是字串,例如城市可以是「巴黎」或「紐約」。

JSON 表示法
{
  "name": string,
  "dimensionExpression": {
    object (DimensionExpression)
  }
}
欄位
name

string

維度的名稱。如需核心報表方法 (例如 runReportbatchRunReports) 支援的維度名稱清單,請參閱 API 維度。如需 runRealtimeReport 方法支援的維度名稱清單,請參閱「即時維度」。如需 runFunnelReport 方法支援的維度名稱清單,請參閱「漏斗維度」。

如果指定 dimensionExpressionname 可以是允許字元集內的任何字串。舉例來說,如果 dimensionExpression 會串連 countrycity,您可以將該維度命名為 countryAndCity。您選擇的維度名稱必須符合規則運算式 ^[a-zA-Z0-9_]$

維度會由 name 中的 dimensionFilterorderBysdimensionExpressionpivots 參照。

dimensionExpression

object (DimensionExpression)

一個維度可能是多個維度的運算式結果。舉例來說,維度「國家/地區、城市」:concatenate(country, ", ", city)。

DimensionExpression

用於表示多個維度公式的結果維度。使用範例:1) lowerCase(dimension) 2) concatenate(dimension1, symbol, dimension2)。

JSON 表示法
{

  // Union field one_expression can be only one of the following:
  "lowerCase": {
    object (CaseExpression)
  },
  "upperCase": {
    object (CaseExpression)
  },
  "concatenate": {
    object (ConcatenateExpression)
  }
  // End of list of possible types for union field one_expression.
}
欄位
聯集欄位 one_expression。為 DimensionExpression 指定一種維度運算式。one_expression 只能是下列其中一項:
lowerCase

object (CaseExpression)

用於將維度值轉換為小寫。

upperCase

object (CaseExpression)

將維度值轉換為大寫。

concatenate

object (ConcatenateExpression)

用於將維度值合併為單一維度。舉例來說,維度「國家/地區、城市」:concatenate(country, ", ", city)。

CaseExpression

用於將維度值轉換為單一大小寫。

JSON 表示法
{
  "dimensionName": string
}
欄位
dimensionName

string

維度名稱。名稱必須參照要求維度欄位中的名稱。

ConcatenateExpression

用於將維度值合併為單一維度。

JSON 表示法
{
  "dimensionNames": [
    string
  ],
  "delimiter": string
}
欄位
dimensionNames[]

string

維度名稱。名稱必須參照要求維度欄位中的名稱。

delimiter

string

維度名稱之間的分隔符號。

分隔符號通常是單一字元,例如「|」或「,」,但也可以是較長的字串。如果維度值包含分隔符號,回應中會同時顯示這兩者,且不會區分。舉例來說,如果維度 1 的值為「US,FR」,維度 2 的值為「JP」,且分隔符為「,」,則回應會包含「US,FR,JP」。

指標

報表的量化評估方式。舉例來說,「事件數」指標 eventCount 代表事件總數,要求最多可包含 10 項指標。

JSON 表示法
{
  "name": string,
  "expression": string,
  "invisible": boolean
}
欄位
name

string

指標名稱。如需核心報表方法 (例如 runReportbatchRunReports) 支援的指標名稱清單,請參閱「API 指標」。如需 runRealtimeReport 方法支援的指標名稱清單,請參閱「即時指標」。如需 runFunnelReport 方法支援的指標名稱清單,請參閱「漏斗指標」。

如果指定 expressionname 可以是允許字元集內的任何字串。舉例來說,如果 expressionscreenPageViews/sessions,您可以將該指標的名稱設為 viewsPerSession。您選擇的指標名稱必須符合規則運算式 ^[a-zA-Z0-9_]$

指標會由 name 參照 metricFilterorderBys 和指標 expression

expression

string

衍生指標的數學運算式。舉例來說,「每位使用者的事件計數」指標為 eventCount/totalUsers

invisible

boolean

指出指標是否在報表回應中隱藏。如果指標不可見,回應中不會產生資料欄,但可在 metricFilterorderBys 或指標 expression 中使用。

DateRange

連續的天數:startDatestartDate + 1、...、endDate。最多可要求 4 個日期範圍。

JSON 表示法
{
  "startDate": string,
  "endDate": string,
  "name": string
}
欄位
startDate

string

查詢的開始日期 (含此日期),格式為 YYYY-MM-DD。不得晚於 endDate。系統也接受 NdaysAgoyesterdaytoday 格式,在這種情況下,系統會根據資源的報表時區推斷日期。

endDate

string

查詢的結束日期 (含此日期),格式為 YYYY-MM-DD。不得早於 startDate。系統也接受 NdaysAgoyesterdaytoday 格式,在這種情況下,系統會根據資源的報表時區推斷日期。

name

string

為這個日期範圍指派名稱。報表回應中的維度 dateRange 會以這個名稱表示。如果設定,開頭不得為 date_range_RESERVED_。如未設定,系統會根據要求中的以零為基準的索引命名日期範圍:date_range_0date_range_1 等。

FilterExpression

用來表示維度或指標篩選條件。相同 FilterExpression 中的欄位必須全為維度或全為指標。

JSON 表示法
{

  // Union field expr can be only one of the following:
  "andGroup": {
    object (FilterExpressionList)
  },
  "orGroup": {
    object (FilterExpressionList)
  },
  "notExpression": {
    object (FilterExpression)
  },
  "filter": {
    object (Filter)
  }
  // End of list of possible types for union field expr.
}
欄位
聯集欄位 expr。為 FilterExpression 指定一種篩選運算式。expr 只能是下列其中一項:
andGroup

object (FilterExpressionList)

andGroup 中的 FilterExpressions 具有 AND 關係。

orGroup

object (FilterExpressionList)

orGroup 中的 FilterExpression 具有 OR 關係。

notExpression

object (FilterExpression)

FilterExpression 不是 notExpression。

filter

object (Filter)

原始篩選器。在同一個 FilterExpression 中,篩選器的所有欄位名稱都必須是維度或指標。

FilterExpressionList

篩選運算式清單。

JSON 表示法
{
  "expressions": [
    {
      object (FilterExpression)
    }
  ]
}
欄位
expressions[]

object (FilterExpression)

篩選運算式清單。

篩選器

用來篩選維度或指標值的運算式。

JSON 表示法
{
  "fieldName": string,

  // Union field one_filter can be only one of the following:
  "stringFilter": {
    object (StringFilter)
  },
  "inListFilter": {
    object (InListFilter)
  },
  "numericFilter": {
    object (NumericFilter)
  },
  "betweenFilter": {
    object (BetweenFilter)
  },
  "emptyFilter": {
    object (EmptyFilter)
  }
  // End of list of possible types for union field one_filter.
}
欄位
fieldName

string

維度名稱或指標名稱。必須是維度或指標中定義的名稱。

聯集欄位 one_filter。為 Filter 指定一種篩選條件類型。one_filter 只能是下列其中一項:
stringFilter

object (StringFilter)

與字串相關的篩選器。

inListFilter

object (InListFilter)

用於篩選清單中值的篩選器。

numericFilter

object (NumericFilter)

數字或日期值的篩選條件。

betweenFilter

object (BetweenFilter)

篩選介於兩個值之間的值。

emptyFilter

object (EmptyFilter)

篩選空白值,例如「(not set)」和「」值。

StringFilter

字串的篩選器

JSON 表示法
{
  "matchType": enum (MatchType),
  "value": string,
  "caseSensitive": boolean
}
欄位
matchType

enum (MatchType)

這個篩選器的比對類型。

value

string

用於比對的字串值。

caseSensitive

boolean

如為 true,字串值會區分大小寫。

MatchType

字串篩選器的比對類型

列舉
MATCH_TYPE_UNSPECIFIED 未指定
EXACT 字串值完全相符。
BEGINS_WITH 以字串值開頭。
ENDS_WITH 結尾為字串值。
CONTAINS 包含字串值。
FULL_REGEXP 字串值與規則運算式完全相符。
PARTIAL_REGEXP 字串值與規則運算式部分相符。

InListFilter

結果必須是字串值清單。

JSON 表示法
{
  "values": [
    string
  ],
  "caseSensitive": boolean
}
欄位
values[]

string

字串值清單。不得為空白。

caseSensitive

boolean

如為 true,字串值會區分大小寫。

NumericFilter

篩選數值或日期值。

JSON 表示法
{
  "operation": enum (Operation),
  "value": {
    object (NumericValue)
  }
}
欄位
operation

enum (Operation)

這個篩選器的操作類型。

value

object (NumericValue)

數值或日期值。

作業

套用至數字篩選器的運算

列舉
OPERATION_UNSPECIFIED 未指明
EQUAL 等於
LESS_THAN 小於
LESS_THAN_OR_EQUAL 小於或等於
GREATER_THAN 大於
GREATER_THAN_OR_EQUAL 大於或等於

NumericValue

代表數字。

JSON 表示法
{

  // Union field one_value can be only one of the following:
  "int64Value": string,
  "doubleValue": number
  // End of list of possible types for union field one_value.
}
欄位
聯集欄位 one_value。數值 one_value 只能是下列其中一項:
int64Value

string (int64 format)

整數值

doubleValue

number

雙重值

BetweenFilter

表示結果必須介於兩個數字之間 (含首尾)。

JSON 表示法
{
  "fromValue": {
    object (NumericValue)
  },
  "toValue": {
    object (NumericValue)
  }
}
欄位
fromValue

object (NumericValue)

開頭為這個數字。

toValue

object (NumericValue)

結尾為這個數字。

EmptyFilter

這個類型沒有任何欄位。

篩選空白值。

MetricAggregation

代表指標匯總。

列舉
METRIC_AGGREGATION_UNSPECIFIED 未指定運算子。
TOTAL SUM 運算子。
MINIMUM 最低運算子。
MAXIMUM 最大運算子。
COUNT Count 運算子。

排序依據

排序依據會定義回應中的資料列排序方式。舉例來說,依事件計數遞減排序資料列是一種排序方式,依事件名稱字串排序資料列則是另一種排序方式。

JSON 表示法
{
  "desc": boolean,

  // Union field one_order_by can be only one of the following:
  "metric": {
    object (MetricOrderBy)
  },
  "dimension": {
    object (DimensionOrderBy)
  }
  // End of list of possible types for union field one_order_by.
}
欄位
desc

boolean

如為 true,則依遞減順序排序。

聯集欄位 one_order_by。請為 OrderBy 指定一種排序依據。one_order_by 只能是下列其中一項:
metric

object (MetricOrderBy)

依指標值排序結果。

dimension

object (DimensionOrderBy)

依維度值排序結果。

MetricOrderBy

依指標值排序。

JSON 表示法
{
  "metricName": string
}
欄位
metricName

string

要求中用於排序的指標名稱。

DimensionOrderBy

依維度值排序。

JSON 表示法
{
  "dimensionName": string,
  "orderType": enum (OrderType)
}
欄位
dimensionName

string

要求中用於排序的維度名稱。

orderType

enum (OrderType)

控管維度值排序規則。

OrderType

用來排序字串維度值的規則。

列舉
ORDER_TYPE_UNSPECIFIED 未指明
ALPHANUMERIC 英數字元排序依據為 Unicode 碼點。例如:「2」<「A」<「X」<「b」<「z」。
CASE_INSENSITIVE_ALPHANUMERIC 不區分大小寫的英數字元排序,依小寫 Unicode 碼點排序。例如:「2」<「A」<「b」<「X」<「z」。
NUMERIC 維度值會先轉換為數字,再進行排序。舉例來說,在 NUMERIC 排序中,「25」<「100」,而在 ALPHANUMERIC 排序中,「100」<「25」。所有非數值維度值的排序值都相等,且低於所有數值。

CohortSpec

同類群組報表的同類群組規格。

同類群組報表會建立同類群組的使用者留存率時間序列。舉例來說,您可以選取 9 月第一週獲得的使用者同類群組,並在接下來六週追蹤該同類群組。在 cohort 物件中,選取 9 月第一週招攬到的同類群組使用者。cohortsRange 物件會指定接下來六週的同類群組。

如需範例,請參閱「同類群組報表範例」。

報表回應可能會顯示每週的時間序列,例如您的應用程式在三週後留住了 60% 的同類群組,六週後則留住了 25% 的同類群組。這兩個百分比可透過指標 cohortActiveUsers/cohortTotalUsers 計算得出,並會顯示在報表中的不同資料列。

JSON 表示法
{
  "cohorts": [
    {
      object (Cohort)
    }
  ],
  "cohortsRange": {
    object (CohortsRange)
  },
  "cohortReportSettings": {
    object (CohortReportSettings)
  }
}
欄位
cohorts[]

object (Cohort)

定義將使用者分組為同類群組的選取條件。

大多數同類群組報表只會定義單一同類群組。如果指定多個同類群組,報表會顯示每個同類群組的名稱。

cohortsRange

object (CohortsRange)

同類群組報表會追蹤同類群組在較長報表日期範圍內的行為。這個範圍會指定要追蹤同類群組的偏移時間長度。

cohortReportSettings

object (CohortReportSettings)

同類群組報表的選用設定。

同類群組

定義同類群組選取條件。同類群組是指具有共同特徵的使用者。舉例來說,具有相同firstSessionDate的使用者會歸為同一個同類群組。

JSON 表示法
{
  "name": string,
  "dimension": string,
  "dateRange": {
    object (DateRange)
  }
}
欄位
name

string

為這個同類群組指派名稱。報表回應中的維度 cohort 會以這個名稱表示。如果設定,開頭不得為 cohort_RESERVED_。如未設定,同類群組會依據以零為基準的索引命名,例如 cohort_0cohort_1 等。

dimension

string

同類群組使用的維度。這是必要欄位,且僅支援 firstSessionDate

dateRange

object (DateRange)

同類群組會選取初次接觸日期介於 dateRange 中定義的開始日期和結束日期之間的使用者。這項 dateRange 不會指定同類群組報表中的事件資料完整日期範圍。在同類群組報表中,這個 dateRange 會根據 cohortsRange 中的精細度和偏移量延長;同類群組報表會顯示延長後報表日期範圍內的事件資料。

在同類群組要求中,這是必要欄位,且 RunReportRequestRunPivotReportRequest 中的 dateRanges 必須未指定。dateRange

這項 dateRange 一般應與同類群組的精細程度一致。如果 CohortsRange 使用每日精細程度,則 dateRange 可以是單日。如果 CohortsRange 使用每週精細度,則這個 dateRange 可以對齊週界,從星期日開始,星期六結束。如果 CohortsRange 使用每月精細度,則此 dateRange 可與月份對齊,從當月第一天開始,到當月最後一天結束。

CohortsRange

設定同類群組報表的延長報表日期範圍。指定要追蹤同類群組的偏移時間長度。

JSON 表示法
{
  "granularity": enum (Granularity),
  "startOffset": integer,
  "endOffset": integer
}
欄位
granularity

enum (Granularity)

必填。用於解讀同類群組報表擴展報表日期範圍的 startOffsetendOffset 細微程度。

startOffset

integer

startOffset 指定同類群組報表延伸報表日期範圍的開始日期。startOffset 通常會設為 0,這樣報表就會包含從同類群組獲取時間開始的資料。

如果 granularityDAILY,則延長報表日期範圍的 startDate 為同類群組的 startDate 加上 startOffset 天。

如果 granularityWEEKLY,則延長報表日期範圍的 startDate 為同類群組的 startDate 加上 startOffset * 7 天。

如果 granularityMONTHLY,則延長報表日期範圍的 startDate 為同類群組的 startDate 加上 startOffset * 30 天。

endOffset

integer

必填。endOffset:指定同類群組報表延長報表日期範圍的結束日期。endOffset 可以是任何正整數,但通常會設為 5 到 10,這樣報表就會包含接下來幾個細微時間範圍的同類群組資料。

如果 granularityDAILY,則延長報表日期範圍的 endDate 為同類群組的 endDate 加上 endOffset 天。

如果 granularityWEEKLY,則延長報表日期範圍的 endDate 為同類群組的 endDate 加上 endOffset * 7 天。

如果 granularityMONTHLY,則延長報表日期範圍的 endDate 為同類群組的 endDate 加上 endOffset * 30 天。

精細程度

用於解讀同類群組報表擴展報表日期範圍的 startOffsetendOffset 細微程度。

列舉
GRANULARITY_UNSPECIFIED 一律不應指定。
DAILY 以天為單位。如果同類群組的 dateRange 為單日,且要求包含 cohortNthDay,則通常會使用這項功能。
WEEKLY 每週精細程度。如果同類群組的 dateRange 為期一週 (從週日開始,週六結束),且要求包含 cohortNthWeek,則通常會使用這個值。
MONTHLY 以月為單位。如果同類群組的 dateRange 持續時間為一個月,且要求包含 cohortNthMonth,則通常會使用這項功能。

CohortReportSettings

同類群組報表的選用設定。

JSON 表示法
{
  "accumulate": boolean
}
欄位
accumulate

boolean

如果為 true,則會累計從首次接觸日到結束日之間的結果。不支援使用以下發布途徑:RunReportRequest

SamplingLevel

要求的取樣層級類別。

列舉
SAMPLING_LEVEL_UNSPECIFIED 未指定類型。
LOW 對標準資源套用 1,000 萬的取樣層級,對 Google Analytics 360 資源套用 1 億的取樣層級。
MEDIUM 僅適用於取樣層級為 10 億的 Google Analytics 360 資源。
UNSAMPLED 僅適用於 Google Analytics 360 資源。未取樣探索結果更準確,還能發掘標準探索中看不到的洞察資料。詳情請參閱 https://support.google.com/analytics/answer/10896953

ReportMetadata

特定報表工作的報表中繼資料。

JSON 表示法
{
  "creationQuotaTokensCharged": integer,
  "state": enum (State),
  "beginCreatingTime": string,
  "taskRowCount": integer,
  "errorMessage": string,
  "totalRowCount": integer
}
欄位
creationQuotaTokensCharged

integer

僅供輸出。建立報表時收取的配額權杖總數。由於這項權杖數是根據 CREATING 狀態的活動計算,因此報表工作進入 ACTIVEFAILED 狀態後,權杖費用就會固定。

state

enum (State)

僅供輸出。這項報表工作的目前狀態。

beginCreatingTime

string (Timestamp format)

僅供輸出。呼叫 reportTasks.create 的時間,以及報表開始 CREATING 狀態的時間。

使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z""2014-10-02T15:01:23+05:30"

taskRowCount

integer

僅供輸出。報表結果中的資料列總數。如果狀態為有效,系統會填入這個欄位。您可以在現有報表的範圍內,使用 taskRowCount 進行分頁。

errorMessage

string

僅供輸出。如果報表工作在建立期間失敗,系統會填入錯誤訊息。

totalRowCount

integer

僅供輸出。Google Analytics 儲存空間中的資料列總數。如要查詢目前報表以外的資料列,可以根據 totalRowCount啟動新的報表工作。

taskRowCount 代表與目前報表相關的資料列數,而 totalRowCount 則包含從 Google Analytics 儲存空間擷取的所有資料列總數。

舉例來說,假設目前報表的 taskRowCount 為 20,則會顯示前 20 列的資料。同時,totalRowCount 為 30,表示所有 30 列都有資料。taskRowCount 可用於分頁瀏覽前 20 列。如要展開報表並納入所有 30 個資料列的資料,可以使用 totalRowCount 建立新的報表工作,存取完整 30 個資料列的資料。

處理狀態。

列舉
STATE_UNSPECIFIED 系統絕不會使用未指定狀態。
CREATING 報表目前正在建立中,日後即可使用。建立作業會在呼叫 CreateReport 後立即執行。
ACTIVE 報表已完全建立,隨時可供查詢。
FAILED 無法建立報表。

方法

create

啟動報表工作建立程序。

get

取得特定報表工作的報表中繼資料。

list

列出資源的所有報表工作。

query

擷取報表工作的內容。