- 資源:ReportTask
- ReportDefinition
- Dimension
- DimensionExpression
- CaseExpression
- ConcatenateExpression
- 指標
- DateRange
- FilterExpression
- FilterExpressionList
- 篩選器
- StringFilter
- MatchType
- InListFilter
- NumericFilter
- 作業
- NumericValue
- BetweenFilter
- EmptyFilter
- MetricAggregation
- OrderBy
- MetricOrderBy
- DimensionOrderBy
- OrderType
- CohortSpec
- 同類群組
- CohortsRange
- 精細程度
- CohortReportSettings
- SamplingLevel
- ReportMetadata
- 狀態
- 方法
資源:ReportTask
特定報表工作設定。
| JSON 表示法 |
|---|
{ "name": string, "reportDefinition": { object ( |
| 欄位 | |
|---|---|
name |
僅供輸出。ID。建立時指派的報表工作資源名稱。格式:「properties/{property}/reportTasks/{reportTask}」 |
reportDefinition |
(選用步驟) 用於擷取報表資料的報表定義,說明報表結構。通常包括報表要納入的欄位,以及用於篩選資料的條件。 |
reportMetadata |
僅供輸出。特定報表工作的報表中繼資料,提供報表相關資訊。通常包括下列資訊:報表的資源名稱、報表狀態、報表建立時間戳記等。 |
ReportDefinition
報表的執行方式定義。
| JSON 表示法 |
|---|
{ "dimensions": [ { object ( |
| 欄位 | |
|---|---|
dimensions[] |
(選用步驟) 要求和顯示的維度。 |
metrics[] |
(選用步驟) 要求和顯示的指標。 |
dateRanges[] |
(選用步驟) 要讀取的資料日期範圍。如果要求多個日期範圍,每個回應列都會包含以零為基準的日期範圍索引。如果兩個日期範圍重疊,重疊日期的事件資料會同時納入兩個日期範圍的回應列。在同類群組要求中,這個 |
dimensionFilter |
(選用步驟) 維度篩選器可讓您只要求報表中的特定維度值。如需更多範例,請參閱「維度篩選器基本概念」。這個篩選條件無法使用指標。 |
metricFilter |
(選用步驟) 指標的篩選子句。在匯總報表資料列後套用,類似於 SQL 的 having 子句。這個篩選器無法使用維度。 |
offset |
(選用步驟) Google Analytics 儲存空間中起始列的列數。第一列會計為第 0 列。 建立報表工作時, |
limit |
(選用步驟) 報表中要傳回的列數。如未指定,系統會傳回 10,000 個資料列。無論您要求多少資料列,API 每次最多只會傳回 250,000 列。 如果維度值的數量少於要求的 |
metricAggregations[] |
(選用步驟) 匯總指標。如果 dimensionValues 設為「RESERVED_(MetricAggregation)」,系統會在對應的資料列中顯示匯總指標值。 |
orderBys[] |
(選用步驟) 指定回應中的資料列排序方式。 |
currencyCode |
(選用步驟) ISO4217 格式的貨幣代碼,例如「AED」、「USD」、「JPY」。如果這個欄位空白,報表會使用資源的預設幣別。 |
cohortSpec |
(選用步驟) 與這項要求相關聯的同類群組。如果要求中有同類群組,就必須提供「同類群組」維度。 |
keepEmptyRows |
(選用步驟) 如果為 false 或未指定,系統不會傳回所有指標都等於 0 的資料列。如果為 true,且資料列未遭篩選器個別移除,系統就會傳回這些資料列。 無論這項 舉例來說,如果資源從未記錄 |
samplingLevel |
(選用步驟) 報表的取樣層級。 |
維度
維度是資料的屬性。舉例來說,「城市」維度會指出事件的來源城市。報表回應中的維度值是字串,例如城市可以是「巴黎」或「紐約」。
| JSON 表示法 |
|---|
{
"name": string,
"dimensionExpression": {
object ( |
| 欄位 | |
|---|---|
name |
維度的名稱。如需核心報表方法 (例如 如果指定 維度會由 |
dimensionExpression |
一個維度可能是多個維度的運算式結果。舉例來說,維度「國家/地區、城市」:concatenate(country, ", ", city)。 |
DimensionExpression
用於表示多個維度公式的結果維度。使用範例:1) lowerCase(dimension) 2) concatenate(dimension1, symbol, dimension2)。
| JSON 表示法 |
|---|
{ // Union field |
| 欄位 | |
|---|---|
聯集欄位 one_expression。為 DimensionExpression 指定一種維度運算式。one_expression 只能是下列其中一項: |
|
lowerCase |
用於將維度值轉換為小寫。 |
upperCase |
將維度值轉換為大寫。 |
concatenate |
用於將維度值合併為單一維度。舉例來說,維度「國家/地區、城市」:concatenate(country, ", ", city)。 |
CaseExpression
用於將維度值轉換為單一大小寫。
| JSON 表示法 |
|---|
{ "dimensionName": string } |
| 欄位 | |
|---|---|
dimensionName |
維度名稱。名稱必須參照要求維度欄位中的名稱。 |
ConcatenateExpression
用於將維度值合併為單一維度。
| JSON 表示法 |
|---|
{ "dimensionNames": [ string ], "delimiter": string } |
| 欄位 | |
|---|---|
dimensionNames[] |
維度名稱。名稱必須參照要求維度欄位中的名稱。 |
delimiter |
維度名稱之間的分隔符號。 分隔符號通常是單一字元,例如「|」或「,」,但也可以是較長的字串。如果維度值包含分隔符號,回應中會同時顯示這兩者,且不會區分。舉例來說,如果維度 1 的值為「US,FR」,維度 2 的值為「JP」,且分隔符為「,」,則回應會包含「US,FR,JP」。 |
指標
報表的量化評估方式。舉例來說,「事件數」指標 eventCount 代表事件總數,要求最多可包含 10 項指標。
| JSON 表示法 |
|---|
{ "name": string, "expression": string, "invisible": boolean } |
| 欄位 | |
|---|---|
name |
指標名稱。如需核心報表方法 (例如 如果指定 指標會由 |
expression |
衍生指標的數學運算式。舉例來說,「每位使用者的事件計數」指標為 |
invisible |
指出指標是否在報表回應中隱藏。如果指標不可見,回應中不會產生資料欄,但可在 |
DateRange
連續的天數:startDate、startDate + 1、...、endDate。最多可要求 4 個日期範圍。
| JSON 表示法 |
|---|
{ "startDate": string, "endDate": string, "name": string } |
| 欄位 | |
|---|---|
startDate |
查詢的開始日期 (含此日期),格式為 |
endDate |
查詢的結束日期 (含此日期),格式為 |
name |
為這個日期範圍指派名稱。報表回應中的維度 |
FilterExpression
用來表示維度或指標篩選條件。相同 FilterExpression 中的欄位必須全為維度或全為指標。
| JSON 表示法 |
|---|
{ // Union field |
| 欄位 | |
|---|---|
聯集欄位 expr。為 FilterExpression 指定一種篩選運算式。expr 只能是下列其中一項: |
|
andGroup |
andGroup 中的 FilterExpressions 具有 AND 關係。 |
orGroup |
orGroup 中的 FilterExpression 具有 OR 關係。 |
notExpression |
FilterExpression 不是 notExpression。 |
filter |
原始篩選器。在同一個 FilterExpression 中,篩選器的所有欄位名稱都必須是維度或指標。 |
FilterExpressionList
篩選運算式清單。
| JSON 表示法 |
|---|
{
"expressions": [
{
object ( |
| 欄位 | |
|---|---|
expressions[] |
篩選運算式清單。 |
篩選器
用來篩選維度或指標值的運算式。
| JSON 表示法 |
|---|
{ "fieldName": string, // Union field |
| 欄位 | |
|---|---|
fieldName |
維度名稱或指標名稱。必須是維度或指標中定義的名稱。 |
聯集欄位 one_filter。為 Filter 指定一種篩選條件類型。one_filter 只能是下列其中一項: |
|
stringFilter |
與字串相關的篩選器。 |
inListFilter |
用於篩選清單中值的篩選器。 |
numericFilter |
數字或日期值的篩選條件。 |
betweenFilter |
篩選介於兩個值之間的值。 |
emptyFilter |
篩選空白值,例如「(not set)」和「」值。 |
StringFilter
字串的篩選器
| JSON 表示法 |
|---|
{
"matchType": enum ( |
| 欄位 | |
|---|---|
matchType |
這個篩選器的比對類型。 |
value |
用於比對的字串值。 |
caseSensitive |
如為 true,字串值會區分大小寫。 |
MatchType
字串篩選器的比對類型
| 列舉 | |
|---|---|
MATCH_TYPE_UNSPECIFIED |
未指定 |
EXACT |
字串值完全相符。 |
BEGINS_WITH |
以字串值開頭。 |
ENDS_WITH |
結尾為字串值。 |
CONTAINS |
包含字串值。 |
FULL_REGEXP |
字串值與規則運算式完全相符。 |
PARTIAL_REGEXP |
字串值與規則運算式部分相符。 |
InListFilter
結果必須是字串值清單。
| JSON 表示法 |
|---|
{ "values": [ string ], "caseSensitive": boolean } |
| 欄位 | |
|---|---|
values[] |
字串值清單。不得為空白。 |
caseSensitive |
如為 true,字串值會區分大小寫。 |
NumericFilter
篩選數值或日期值。
| JSON 表示法 |
|---|
{ "operation": enum ( |
| 欄位 | |
|---|---|
operation |
這個篩選器的操作類型。 |
value |
數值或日期值。 |
作業
套用至數字篩選器的運算
| 列舉 | |
|---|---|
OPERATION_UNSPECIFIED |
未指明 |
EQUAL |
等於 |
LESS_THAN |
小於 |
LESS_THAN_OR_EQUAL |
小於或等於 |
GREATER_THAN |
大於 |
GREATER_THAN_OR_EQUAL |
大於或等於 |
NumericValue
代表數字。
| JSON 表示法 |
|---|
{ // Union field |
| 欄位 | |
|---|---|
聯集欄位 one_value。數值 one_value 只能是下列其中一項: |
|
int64Value |
整數值 |
doubleValue |
雙重值 |
BetweenFilter
表示結果必須介於兩個數字之間 (含首尾)。
| JSON 表示法 |
|---|
{ "fromValue": { object ( |
| 欄位 | |
|---|---|
fromValue |
開頭為這個數字。 |
toValue |
結尾為這個數字。 |
EmptyFilter
這個類型沒有任何欄位。
篩選空白值。
MetricAggregation
代表指標匯總。
| 列舉 | |
|---|---|
METRIC_AGGREGATION_UNSPECIFIED |
未指定運算子。 |
TOTAL |
SUM 運算子。 |
MINIMUM |
最低運算子。 |
MAXIMUM |
最大運算子。 |
COUNT |
Count 運算子。 |
排序依據
排序依據會定義回應中的資料列排序方式。舉例來說,依事件計數遞減排序資料列是一種排序方式,依事件名稱字串排序資料列則是另一種排序方式。
| JSON 表示法 |
|---|
{ "desc": boolean, // Union field |
| 欄位 | |
|---|---|
desc |
如為 true,則依遞減順序排序。 |
聯集欄位 one_order_by。請為 OrderBy 指定一種排序依據。one_order_by 只能是下列其中一項: |
|
metric |
依指標值排序結果。 |
dimension |
依維度值排序結果。 |
MetricOrderBy
依指標值排序。
| JSON 表示法 |
|---|
{ "metricName": string } |
| 欄位 | |
|---|---|
metricName |
要求中用於排序的指標名稱。 |
DimensionOrderBy
依維度值排序。
| JSON 表示法 |
|---|
{
"dimensionName": string,
"orderType": enum ( |
| 欄位 | |
|---|---|
dimensionName |
要求中用於排序的維度名稱。 |
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 ( |
| 欄位 | |
|---|---|
cohorts[] |
定義將使用者分組為同類群組的選取條件。 大多數同類群組報表只會定義單一同類群組。如果指定多個同類群組,報表會顯示每個同類群組的名稱。 |
cohortsRange |
同類群組報表會追蹤同類群組在較長報表日期範圍內的行為。這個範圍會指定要追蹤同類群組的偏移時間長度。 |
cohortReportSettings |
同類群組報表的選用設定。 |
同類群組
定義同類群組選取條件。同類群組是指具有共同特徵的使用者。舉例來說,具有相同firstSessionDate的使用者會歸為同一個同類群組。
| JSON 表示法 |
|---|
{
"name": string,
"dimension": string,
"dateRange": {
object ( |
| 欄位 | |
|---|---|
name |
為這個同類群組指派名稱。報表回應中的維度 |
dimension |
同類群組使用的維度。這是必要欄位,且僅支援 |
dateRange |
同類群組會選取初次接觸日期介於 在同類群組要求中,這是必要欄位,且 這項 |
CohortsRange
設定同類群組報表的延長報表日期範圍。指定要追蹤同類群組的偏移時間長度。
| JSON 表示法 |
|---|
{
"granularity": enum ( |
| 欄位 | |
|---|---|
granularity |
必填。用於解讀同類群組報表擴展報表日期範圍的 |
startOffset |
如果 如果 如果 |
endOffset |
必填。 如果 如果 如果 |
精細程度
用於解讀同類群組報表擴展報表日期範圍的 startOffset 和 endOffset 細微程度。
| 列舉 | |
|---|---|
GRANULARITY_UNSPECIFIED |
一律不應指定。 |
DAILY |
以天為單位。如果同類群組的 dateRange 為單日,且要求包含 cohortNthDay,則通常會使用這項功能。 |
WEEKLY |
每週精細程度。如果同類群組的 dateRange 為期一週 (從週日開始,週六結束),且要求包含 cohortNthWeek,則通常會使用這個值。 |
MONTHLY |
以月為單位。如果同類群組的 dateRange 持續時間為一個月,且要求包含 cohortNthMonth,則通常會使用這項功能。 |
CohortReportSettings
同類群組報表的選用設定。
| JSON 表示法 |
|---|
{ "accumulate": boolean } |
| 欄位 | |
|---|---|
accumulate |
如果為 true,則會累計從首次接觸日到結束日之間的結果。不支援使用以下發布途徑: |
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 ( |
| 欄位 | |
|---|---|
creationQuotaTokensCharged |
僅供輸出。建立報表時收取的配額權杖總數。由於這項權杖數是根據 |
state |
僅供輸出。這項報表工作的目前狀態。 |
beginCreatingTime |
僅供輸出。呼叫 使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例: |
taskRowCount |
僅供輸出。報表結果中的資料列總數。如果狀態為有效,系統會填入這個欄位。您可以在現有報表的範圍內,使用 |
errorMessage |
僅供輸出。如果報表工作在建立期間失敗,系統會填入錯誤訊息。 |
totalRowCount |
僅供輸出。Google Analytics 儲存空間中的資料列總數。如要查詢目前報表以外的資料列,可以根據
舉例來說,假設目前報表的 |
州
處理狀態。
| 列舉 | |
|---|---|
STATE_UNSPECIFIED |
系統絕不會使用未指定狀態。 |
CREATING |
報表目前正在建立中,日後即可使用。建立作業會在呼叫 CreateReport 後立即執行。 |
ACTIVE |
報表已完全建立,隨時可供查詢。 |
FAILED |
無法建立報表。 |
方法 |
|
|---|---|
|
啟動報表工作建立程序。 |
|
取得特定報表工作的報表中繼資料。 |
|
列出資源的所有報表工作。 |
|
擷取報表工作的內容。 |