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
}
欄位
dimensions[]

object (Dimension)

選用設定。要求和顯示的維度。

metrics[]

object (Metric)

選用設定。要求和顯示的指標。

dateRanges[]

object (DateRange)

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

dimensionFilter

object (FilterExpression)

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

metricFilter

object (FilterExpression)

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

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 個,因此在只產生 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。

維度

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

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

string

維度的名稱。請參閱 API 維度,瞭解 runReportbatchRunReports 等核心報表方法支援的維度名稱清單。請參閱「即時維度」,瞭解 runRealtimeReport 方法支援的維度名稱清單。請參閱程序維度,瞭解 runFunnelReport 方法支援的維度名稱清單。

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

dimensionFilter」、「orderBys」、「dimensionExpression」和「pivots」中的 name 參照了維度。

dimensionExpression

object (DimensionExpression)

一個維度的成因可能是由多個維度的運算式產生。例如「國家/地區, 城市」維度:串連(國家/地區, ", ", 城市)。

DimensionExpression

用來表示由多個維度公式產生的維度。使用範例:1) lowCase(維度) 2) concatenate(dimension1, characters, 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)

用來將維度值合併至單一維度。例如「國家/地區, 城市」維度:串連(國家/地區, ", ", 城市)。

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

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

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

指標是由 metricFilterorderBysexpression 指標中的 name 參照。

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)

和 Group 中的 FilterExpressions 具有 AND 關係。

orGroup

object (FilterExpressionList)

orGroup 中的 FilterExpressions 具有 OR 關係。

notExpression

object (FilterExpression)

FilterExpression 不是不運算式。

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)
  }
  // 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)

用於兩個值的篩選器。

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_valueone_value 數值必須是下列其中一個值:
int64Value

string (int64 format)

整數值

doubleValue

number

雙重值

BetweenFilter

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

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

object (NumericValue)

以這個數字開頭。

toValue

object (NumericValue)

以這組號碼結尾。

MetricAggregation

代表指標的匯總。

列舉
METRIC_AGGREGATION_UNSPECIFIED 未指定運算子。
TOTAL SUM 運算子。
MINIMUM 最低運算子。
MAXIMUM 運算子上限。
COUNT 數量運算子。

OrderBy

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

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 月第一週招攬到的使用者同類群組,並追蹤接下來六週的同類群組。選取 9 月同類群組第一週開發的使用者可在 cohort 物件中指定。接下來六週之後的同類群組會在 cohortsRange 物件中指定。

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

報告回覆可以顯示每週的時間序列,指出您的應用程式在三週後留存了 60% 的同類群組,並在 6 週後留存 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 中的精細程度和偏移量擴充;同類群組報表會顯示延長報表日期範圍的事件資料。

在同類群組要求中,這個 dateRange 為必要項目,且不得指定 RunReportRequestRunPivotReportRequest 中的 dateRanges

這個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 不支援。

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 狀態的時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式,解析度為奈秒,且最多 9 個小數位數。範例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

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

擷取報表工作的內容。