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)

選用設定。要讀取的資料日期範圍。如果要求多個日期範圍，則每個回應列都會包含以 0 為基礎的日期範圍索引。如果兩個日期範圍重疊，這兩個日期範圍的事件資料會納入這兩個日期範圍的回應列中。在同類群組要求中，不得指定這個 dateRanges。
dimensionFilter

object (FilterExpression)

選用設定。維度篩選器可讓您在報表中只要求特定維度值。詳情請參閱「維度篩選器基礎知識」一文。這個篩選器無法使用指標。
metricFilter

object (FilterExpression)

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

string (int64 format)

選用設定。Google Analytics (分析) 儲存空間中起始資料列的計數。第一列會計為第 0 列。

建立報表工作時，offset 和 limit 參數會定義要在產生的報表中納入 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)

選用設定。指標匯總。匯總指標值會顯示在 DimensionsValue 設為「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

維度的名稱。如需 runReport 和 batchRunReports 等核心報表方法支援的維度名稱清單，請參閱 API 維度。如需 runRealtimeReport 方法支援的維度名稱清單，請參閱「即時維度」。如需 runFunnelReport 方法支援的維度名稱清單，請參閱「漏斗維度」。

如果指定 dimensionExpression，name 可以是允許字元集內的任何字串。舉例來說，如果 dimensionExpression 串連 country 和 city，您可以呼叫該維度 countryAndCity。您選擇的維度名稱必須與規則運算式 ^[a-zA-Z0-9_]$ 相符。

dimensionFilter、orderBys、dimensionExpression 和 pivots 中 name 會參照維度。
dimensionExpression

object (DimensionExpression)

多個維度可能是多個維度的運算式結果。例如，維度「country, city」： concatenate(country, ", ", city)。

DimensionExpression

用來表示維度，這是多個維度公式的結果。使用範例：1) 以下版本(維度) 2) concatenate(dimension1, 符號, 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)

用來將維度值合併為單一維度。例如，維度「country, city」： 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

指標的名稱。如需 runReport 和 batchRunReports 等核心報表方法支援的指標名稱清單，請參閱 API 指標。如需 runRealtimeReport 方法支援的指標名稱清單，請參閱「即時指標」。如需 runFunnelReport 方法支援的指標名稱清單，請參閱「漏斗指標」。

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

name 會在 metricFilter、orderBys 和指標 expression 中參照指標。
expression

string

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

boolean

指出指標是否未顯示在報表回應中。如果指標未顯示，則指標不會在回應中產生資料欄，但可用於 metricFilter、orderBys 或指標 expression。

DateRange

連續天數：startDate、startDate + 1、...、endDate。最多可以要求 4 個日期範圍。

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

string

查詢中包含的開始日期，格式為 YYYY-MM-DD。不得晚於 endDate。系統也接受 NdaysAgo、yesterday 或 today 格式，在這種情況下，系統會根據資源的報表時區推測日期。
endDate

string

查詢中包含的結束日期，格式為 YYYY-MM-DD。不得早於 startDate。系統也接受 NdaysAgo、yesterday 或 today 格式，在這種情況下，系統會根據資源的報表時區推測日期。
name

string

為這個日期範圍指定名稱。報表回應中的維度 dateRange 為這個名稱。設定後不得以 date_range_ 或 RESERVED_ 開頭。如未設定，系統會按照要求中的索引來命名日期範圍：date_range_0、date_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 並非「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)
  }
  // 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_value。其中一個數值 one_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 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_0 和 cohort_1 等以零為準命名。
dimension

string

同類群組使用的維度。必要，且僅支援 firstSessionDate。
dateRange

object (DateRange)

同類群組會選取開始日期落在 dateRange 中定義的開始日期和結束日期之間的使用者。這個dateRange不會指定同類群組報表中呈現的事件資料完整日期範圍。在同類群組報表中，這個 dateRange 會延伸 cohortsRange 中呈現的精細程度和偏移量，而整個報表日期範圍的事件資料會顯示在同類群組報表中。

在同類群組要求中，這個 dateRange 為必要值，且不得指定 RunReportRequest 或 RunPivotReportRequest 中的 dateRanges。

這個 dateRange 通常應與同類群組的精細程度保持一致。如果 CohortsRange 採用每日精細程度，這個 dateRange 可以是一天。如果 CohortsRange 使用每週精細程度，這個 dateRange 就能與週邊界對齊，從週日到週六結束。如果 CohortsRange 使用每月精細程度，則這個 dateRange 可以對齊月份，從第一天到最後一天為止。

CohortsRange

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

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

enum (Granularity)

必要欄位。這個精細程度可用於解讀同類群組報表中延伸報表日期範圍的 startOffset 和 endOffset。
startOffset

integer

startOffset 用於指定同類群組報表的延長報表日期範圍開始日期。startOffset 通常設為 0，因此報表會包含同類群組日後的取得資料。

如果 granularity 為 DAILY，延長報表日期範圍的 startDate 就是同類群組的 startDate 加上 startOffset 天。

如果 granularity 為 WEEKLY，延長報表日期範圍的 startDate 就是同類群組的 startDate 加上 startOffset * 7 天。

如果 granularity 為 MONTHLY，延長報表日期範圍的 startDate 就是同類群組的 startDate 加上 startOffset * 30 天。
endOffset

integer

必要欄位。endOffset 用於指定同類群組報表的延長報表日期範圍結束日期。endOffset 可以是任何正整數，但通常會設為 5 到 10，以讓報表包含下一個精細時間範圍內的同類群組資料。

如果 granularity 為 DAILY，延長報表日期範圍的 endDate 就是同類群組的 endDate 加上 endOffset 天。

如果 granularity 為 WEEKLY，延長報表日期範圍的 endDate 就是同類群組的 endDate 加上 endOffset * 7 天。

如果 granularity 為 MONTHLY，延長報表日期範圍的 endDate 就是同類群組的 endDate 加上 endOffset * 30 天。

精細程度

這個精細程度可用於解讀同類群組報表中延伸報表日期範圍的 startOffset 和 endOffset。

列舉
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 狀態的活動計算，因此報表工作進入 ACTIVE 或 FAILED 狀態後，系統就會固定收取這筆權杖費用。
state

enum (State)

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

string (Timestamp format)

僅供輸出。呼叫 reportTasks.create 並開始 CREATING 狀態的時間。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："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

 擷取報表工作的內容。