Method: reports.batchGet

傳回 Analytics (分析) 資料。

HTTP 要求

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構:

JSON 表示法
{
  "reportRequests": [
    {
      object(ReportRequest)
    }
  ],
  "useResourceQuotas": boolean
}
欄位
reportRequests[]

object(ReportRequest)

每個要求都會產生個別的回應。最多可以有 5 個要求。所有要求都必須具有相同的 dateRangesviewIdsegmentssamplingLevelcohortGroup

useResourceQuotas

boolean

啟用以資源為基礎的配額 (預設為 False)。如果將這個欄位設為 True,每次資料檢視 (設定檔) 的配額都會取決於要求的計算費用。請注意,使用以費用為準的配額會提高取樣率。(SMALL 為 1, 000 萬,LARGE 1 億。詳情請參閱限制與配額說明文件

回應主體

如果成功,回應主體即會包含具有以下結構的資料:

主要回應類別,保留 Reporting API batchGet 呼叫的報表。

JSON 表示法
{
  "reports": [
    {
      object(Report)
    }
  ],
  "queryCost": number,
  "resourceQuotasRemaining": {
    object(ResourceQuotasRemaining)
  }
}
欄位
reports[]

object(Report)

與每項要求相對應的回應。

queryCost

number

為執行查詢而扣除的資源配額權杖數量。包含所有回覆。

resourceQuotasRemaining

object(ResourceQuotasRemaining)

資源剩餘的資源配額。

授權範圍

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

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

ReportRequest

指定 Reporting API 要求的主要要求類別。

JSON 表示法
{
  "viewId": string,
  "dateRanges": [
    {
      object(DateRange)
    }
  ],
  "samplingLevel": enum(Sampling),
  "dimensions": [
    {
      object(Dimension)
    }
  ],
  "dimensionFilterClauses": [
    {
      object(DimensionFilterClause)
    }
  ],
  "metrics": [
    {
      object(Metric)
    }
  ],
  "metricFilterClauses": [
    {
      object(MetricFilterClause)
    }
  ],
  "filtersExpression": string,
  "orderBys": [
    {
      object(OrderBy)
    }
  ],
  "segments": [
    {
      object(Segment)
    }
  ],
  "pivots": [
    {
      object(Pivot)
    }
  ],
  "cohortGroup": {
    object(CohortGroup)
  },
  "pageToken": string,
  "pageSize": number,
  "includeEmptyRows": boolean,
  "hideTotals": boolean,
  "hideValueRanges": boolean
}
欄位
viewId

string

要從中擷取資料的 Analytics (分析) 資料檢視 IDbatchGet 方法中的每個 ReportRequest 都必須包含相同的 viewId

dateRanges[]

object(DateRange)

要求中的日期範圍。要求最多只能有 2 個日期範圍。回應中會包含要求中每個日期範圍的每個維度組合的一組指標值。因此,如果有兩個日期範圍,就會有兩組指標值,一個代表原始日期範圍,另一個代表第二個日期範圍。同類群組或生命週期價值要求不應指定「reportRequest.dateRanges」欄位。如未提供日期範圍,預設日期範圍會是 (startDate:目前日期 - 7 天,endDate:目前日期 - 1 天)。batchGet 方法中的每個 ReportRequest 都必須包含相同的 dateRanges 定義。

samplingLevel

enum(Sampling)

所需報表樣本大小。如果未指定 samplingLevel 欄位,系統會使用 DEFAULT 取樣層級。batchGet 方法中的每個 ReportRequest 都必須包含相同的 samplingLevel 定義。詳情請參閱開發人員指南

dimensions[]

object(Dimension)

要求的維度。要求總共可以有 9 個維度。

dimensionFilterClauses[]

object(DimensionFilterClause)

用來篩選維度值的維度篩選器子句。這些會在邏輯上與 AND 運算子合併。請注意,篩選作業是在維度匯總之前進行,因此傳回的指標只代表相關維度的總數。

metrics[]

object(Metric)

要求的指標,要求必須指定至少一個指標。要求總共可以有 10 個指標。

metricFilterClauses[]

object(MetricFilterClause)

指標篩選器子句。這些會在邏輯上與 AND 運算子合併。指標篩選器只會查看第一個日期範圍,而非比較日期範圍。請注意,指標篩選作業是在指標匯總後執行。

filtersExpression

string

用來限制請求所傳回資料的維度或指標篩選器。如要使用 filtersExpression,請提供要篩選的維度或指標,並在後面加上篩選器運算式。舉例來說,以下運算式選取以 Firefox 開頭的「ga:browser」維度;ga:browser=~^Firefox。如要進一步瞭解維度和指標篩選器,請參閱「篩選器參考資料」一文。

orderBys[]

object(OrderBy)

輸出資料列的排序順序。如要比較兩列,系統會依序套用下列元素,直到發現差異為止。輸出中的所有日期範圍都會取得相同的資料列順序。

segments[]

object(Segment)

區隔要求傳回的資料。區隔定義有助您瞭解區隔請求的子集。每項要求最多可包含四個區隔。batchGet 方法中的每個 ReportRequest 都必須包含相同的 segments 定義。含有區隔的要求必須具有 ga:segment 維度。

pivots[]

object(Pivot)

資料透視定義。要求最多可以有 2 個資料透視。

cohortGroup

object(CohortGroup)

與這項要求相關聯的同類群組。如果要求中有同類群組群組,則 ga:cohort 維度必須存在。batchGet 方法中的每個 ReportRequest 都必須包含相同的 cohortGroup 定義。

pageToken

string

用於取得下一頁結果的接續權杖。將這個參數新增至要求中,會傳回 pageToken 後方的資料列。pageToken 則應在 report.batchGet 要求的回應中,於 nextPageToken 參數中傳回的值。

pageSize

number

頁面大小用於分頁,並指定傳回的資料列數量上限。網頁大小必須 >= 0。查詢會傳回預設值 (1,000 個資料列)。不論您要求多少個資料,Analytics (分析) Core Reporting API 都能傳回最多 100,000 列資料。如果維度區隔數量未達預期,系統也會傳回比要求少的列數。舉例來說,ga:country 的可能值少於 300 個,因此,如果只依國家/地區區隔資料,即使您將 pageSize 設為較高的值,仍無法顯示超過 300 列。

includeEmptyRows

boolean

如果設為 False,當所有擷取的指標都等於零時,回應就不會包含資料列。預設值為 false,系統會排除這些資料列。

hideTotals

boolean

如果設為 True,系統會隱藏每個日期範圍內所有相符資料列的所有指標總計。預設值為 false,並傳回總計。

hideValueRanges

boolean

如果設為 true,系統會隱藏所有相符資料列的最小值和最大值。預設值為 false,並傳回值的範圍。

取樣

取樣層級的值。

列舉
SAMPLING_UNSPECIFIED 如果未指定 samplingLevel 欄位,系統會使用 DEFAULT 取樣層級。
DEFAULT 傳回在速度和準確率之間平衡的樣本大小。
SMALL 這個方法會傳回取樣大小更小的快速回應。
LARGE 使用較大的樣本數,傳回更準確的回應。但這可能會導致回應速度變慢。

維度

維度是指資料屬性,舉例來說,ga:city 維度指出工作階段的來源城市名稱 (例如「巴黎」或「紐約」),

JSON 表示法
{
  "name": string,
  "histogramBuckets": [
    string
  ]
}
欄位
name

string

要擷取的維度名稱,例如 ga:browser

histogramBuckets[]

string (int64 format)

如果非空白,系統會將維度值放在字串後面,插入到 int64。非以字串表示的維度值將轉換為零。值區值必須按照遞增順序排列。每個值區都會在下端關閉,並於上端開啟。「第一個」區塊包含小於第一個邊界的所有值,「最後一個」區塊則包含直至無限大的所有值。值區中的維度值會轉換為新的維度值。舉例來說,假設有人提供「0, 1, 3, 4, 7」的清單,我們就會傳回下列值區:

  • 區塊 #1:值 < 0,維度值「<0」
  • 值區 #2:[0,1] 中的值)、維度值「0」
  • 值區 #3:[1,3] 中的值)、維度值「1-2」
  • 值區 #4:[3,4] 中的值)、維度值「3」
  • 值區 #5:[4,7] 中的值,維度值「4-6」
  • 值區 #6:值 >= 7,維度值「7+」

注意:如果您要對任何維度套用直方圖異動事件,並以該維度排序,則要使用排序類型 HISTOGRAM_BUCKET。如未使用該維度值,系統將根據字典 (字典編列) 順序排序維度值。舉例來說,字典的遞增順序如下:

「<50」、「1001+」、「121-1000」、「50-120」

HISTOGRAM_BUCKET 遞增順序為:

「<50」、「50-120」、「121-1000」、「1001+」

用戶端必須針對直方圖的變動維度明確要求 "orderType": "HISTOGRAM_BUCKET"

DimensionFilterClause

一組維度篩選器。設定運算子值以指定篩選器的邏輯合併方式。

JSON 表示法
{
  "operator": enum(FilterLogicalOperator),
  "filters": [
    {
      object(DimensionFilter)
    }
  ]
}
欄位
operator

enum(FilterLogicalOperator)

合併多個維度篩選器的運算子。如果未指定,則視為 OR

filters[]

object(DimensionFilter)

一組重複的篩選器。系統會根據指定的運算子,以邏輯方式合併這些運算子。

FilterLogicalOperator

篩選器在邏輯中組合的方式。

列舉
OPERATOR_UNSPECIFIED 未指定運算子。系統會將其視為 OR
OR 邏輯 OR 運算子。
AND 邏輯 AND 運算子。

DimensionFilter

維度篩選器可指定維度的篩選選項。

JSON 表示法
{
  "dimensionName": string,
  "not": boolean,
  "operator": enum(Operator),
  "expressions": [
    string
  ],
  "caseSensitive": boolean
}
欄位
dimensionName

string

要篩選的維度。DimensionsFilter 必須包含維度。

not

boolean

邏輯 NOT 運算子。如果將布林值設為 true,系統會排除報表中相符的維度值。預設值為「false」。

operator

enum(Operator)

如何將維度與運算式進行比對。預設值為 REGEXP。

expressions[]

string

要比對的字串或規則運算式。除非運算子為 IN_LIST,否則系統只會使用清單的第一個值進行比較。如果使用 IN_LIST 運算子,系統會按照 IN_LIST 運算子說明的說明,使用整份清單篩選維度。

caseSensitive

boolean

比對相符項目是否區分大小寫?預設值為 false。

運算子

支援不同的比對類型。

列舉
OPERATOR_UNSPECIFIED 如未指定比對類型,系統會將其視為 REGEXP
REGEXP 系統會將比對運算式視為規則運算式。系統不會將所有比對類型視為規則運算式。
BEGINS_WITH 比對開頭為提供比對運算式的值。
ENDS_WITH 比對結尾與提供的比對運算式的值。
PARTIAL 子字串比對。
EXACT 值應與比對運算式完全相符。
NUMERIC_EQUAL

整數比較篩選器。系統會忽略這些條件的大小寫,並假設運算式是代表整數的字串。失敗條件:

  • 如果運算式不是有效的 int64,用戶端應該會發生錯誤。
  • 輸入的維度如果無效的 int64 值,就一律不符合篩選器條件。
NUMERIC_GREATER_THAN 檢查維度是否大於比對運算式的數字。請參閱 NUMERIC_EQUALS 的說明,瞭解相關限制。
NUMERIC_LESS_THAN 檢查維度是否小於比對運算式。請參閱 NUMERIC_EQUALS 的說明,瞭解相關限制。
IN_LIST

這個選項可用於指定維度篩選器,這個篩選器的運算式可擷取所選值清單中的任何值。如此可避免評估每個回應列使用 OR 的多個完全比對維度篩選器。例如:

expressions: ["A", "B", "C"]

維度值為 A、B 或 C 的所有回應列,皆與這個 DimensionsFilter 相符。

指標

指標是量化的測量結果,舉例來說,ga:users 指標代表指定時間範圍內的使用者總數。

JSON 表示法
{
  "expression": string,
  "alias": string,
  "formattingType": enum(MetricType)
}
欄位
expression

string

要求中的指標運算式。運算式是由一或多個指標和數字所建構。系統接受的運算子包括:加號 (+)、減號 (-)、否定 (一元 -)、否定 (/)、乘法符號 (/)、乘法符號 (*)、括號、正基數 (0-9) 可包含小數,且上限為 1024 個字元。範例 ga:totalRefunds/ga:users,在多數情況下,指標運算式只是單一的指標名稱,例如 ga:users。新增混合的 MetricType (例如CURRENCY + PERCENTAGE) 指標會導致非預期的結果。

alias

string

指標運算式的別名是運算式的替代名稱。別名可用於篩選及排序。這個欄位是選用欄位,如果運算式不是單一指標,而是無法用於篩選和排序的複雜運算式,就相當實用。這個別名也會用於回應欄標題。

formattingType

enum(MetricType)

指定指標運算式的格式,例如 INTEGER

MetricType

指標類型。

列舉
METRIC_TYPE_UNSPECIFIED 未指定指標類型。
INTEGER 整數指標。
FLOAT 浮點指標。
CURRENCY 貨幣指標。
PERCENT 百分比指標。
TIME 時間指標,採用 HH:MM:SS 格式。

MetricFilterClause

代表一組指標篩選器。設定運算子值以指定篩選器的邏輯合併方式。

JSON 表示法
{
  "operator": enum(FilterLogicalOperator),
  "filters": [
    {
      object(MetricFilter)
    }
  ]
}
欄位
operator

enum(FilterLogicalOperator)

合併多個指標篩選器的運算子。如果未指定,則視為 OR

filters[]

object(MetricFilter)

一組重複的篩選器。系統會根據指定的運算子,以邏輯方式合併這些運算子。

MetricFilter

MetricFilter 會指定指標的篩選器。

JSON 表示法
{
  "metricName": string,
  "not": boolean,
  "operator": enum(Operator),
  "comparisonValue": string
}
欄位
metricName

string

要篩選的指標。指標篩選器必須包含指標名稱。指標名稱可以是先前定義為指標的別名,也可以是指標運算式。

not

boolean

邏輯 NOT 運算子。如果將布林值設為 True,系統會在報表中排除相符的指標值。預設值為「false」。

operator

enum(Operator)

指標為 EQUALLESS_THANGREATER_THAN,而 CompareValue ,預設值為 EQUAL。如果運算子是 IS_MISSING,系統會檢查該指標是否缺少,並忽略 CompareValue。

comparisonValue

string

要用來比較的值。

運算子

不同的比較類型選項。

列舉
OPERATOR_UNSPECIFIED 如未指定運算子,系統會將其視為 EQUAL
EQUAL 指標的值應等於比較值。
LESS_THAN 指標值必須小於比較值。
GREATER_THAN 指標值是否大於比較值。
IS_MISSING 驗證是否缺少指標。不會將 ComparisonValue 納入考量。

OrderBy

指定排序選項。

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

string

要做為排序依據的欄位。預設排序順序為遞增。範例:ga:browser。請注意,您只能指定一個欄位做為排序依據。舉例來說,ga:browser, ga:city 無效。

orderType

enum(OrderType)

訂單類型。預設 orderType 為 VALUE

sortOrder

enum(SortOrder)

欄位的排序順序。

OrderType

OrderType 會控制排序順序的方式。

列舉
ORDER_TYPE_UNSPECIFIED 系統會將未指定的順序類型視為根據值排序。
VALUE 排序順序會以所選資料欄的值為基準,只查看第一個日期範圍。
DELTA 排序順序取決於前兩個日期範圍之間所選資料欄的值差異。只有在確切有兩個日期範圍時才能使用。
SMART 排序順序取決於所選資料欄的加權值。如果欄具有「n/d」格式,則這個比率的加權值將為 (n + totals.n)/(d + totals.d)。僅適用於代表比率的指標。
HISTOGRAM_BUCKET 直方圖順序類型僅適用於含有非空白直方圖值區的維度資料欄。
DIMENSION_AS_INTEGER 如果維度是固定長度,則一般排序都沒有問題。如果尺寸為變數長度數字,就可以使用 DIMENSION_AS_INTEGER

SortOrder

排序的排序順序。

列舉
SORT_ORDER_UNSPECIFIED 如未指定排序順序,預設為遞增。
ASCENDING 遞增排序。這個欄位將以遞增方式排序。
DESCENDING 遞減排序。這個欄位會以遞減方式排序。

區隔

區隔定義 (如果報表需要區隔的話)。「區隔」是 Analytics (分析) 資料的子集。舉例來說,以整個使用者群來說,某個「區隔」可能是來自特定國家/地區或城市的使用者,

JSON 表示法
{

  // Union field dynamicOrById can be only one of the following:
  "dynamicSegment": {
    object(DynamicSegment)
  },
  "segmentId": string
  // End of list of possible types for union field dynamicOrById.
}
欄位
聯集欄位 dynamicOrById。您可以使用動態區隔或內建或自訂區隔的 ID,以動態方式定義區隔。dynamicOrById 只能是下列其中一項:
dynamicSegment

object(DynamicSegment)

要求中的動態區隔定義。

segmentId

string

內建或自訂區隔的區隔 ID,例如 gaid::-3

DynamicSegment

定義請求中區隔的動態區隔定義。區隔可以選取使用者、工作階段或同時選取兩者。

JSON 表示法
{
  "name": string,
  "userSegment": {
    object(SegmentDefinition)
  },
  "sessionSegment": {
    object(SegmentDefinition)
  }
}
欄位
name

string

動態區隔的名稱。

userSegment

object(SegmentDefinition)

使用者區隔,選取要納入區隔的使用者。

sessionSegment

object(SegmentDefinition)

工作階段區隔,選取要納入區隔的工作階段。

SegmentDefinition

SegmentDefinition 會將區隔定義為一組 SegmentFilters,可結合邏輯 AND 運算。

JSON 表示法
{
  "segmentFilters": [
    {
      object(SegmentFilter)
    }
  ]
}
欄位
segmentFilters[]

object(SegmentFilter)

區隔是由一組區隔篩選器定義,搭配邏輯 AND 作業使用。

SegmentFilter

SegmentFilter 會將區隔定義為簡易區隔或序列區隔。簡單的區隔條件包含用來選取工作階段或使用者的維度和指標條件。您可以使用序列區隔條件,根據順序條件選取使用者或工作階段。

JSON 表示法
{
  "not": boolean,

  // Union field simpleOrSequence can be only one of the following:
  "simpleSegment": {
    object(SimpleSegment)
  },
  "sequenceSegment": {
    object(SequenceSegment)
  }
  // End of list of possible types for union field simpleOrSequence.
}
欄位
not

boolean

如果為 true,則代表簡易或序列區隔的互補色。舉例來說,如要比對所有不是來自「紐約」的造訪,我們可以按照下列方式定義區隔:

  "sessionSegment": {
    "segmentFilters": [{
      "simpleSegment" :{
        "orFiltersForSegment": [{
          "segmentFilterClauses":[{
            "dimensionFilter": {
              "dimensionName": "ga:city",
              "expressions": ["New York"]
            }
          }]
        }]
      },
      "not": "True"
    }]
  },

聯集欄位 simpleOrSequence。可以是單純的區隔或序列區隔定義。simpleOrSequence 只能是下列其中一項:
simpleSegment

object(SimpleSegment)

簡易區隔條件包含一或多個可合併的維度/指標條件

sequenceSegment

object(SequenceSegment)

順序條件由一或多個步驟組成,每個步驟則由一或多個維度/指標條件定義。您可以結合多個步驟和特殊序列運算子。

SimpleSegment

簡易區隔條件包含一或多個可合併的維度/指標條件。

JSON 表示法
{
  "orFiltersForSegment": [
    {
      object(OrFiltersForSegment)
    }
  ]
}
欄位
orFiltersForSegment[]

object(OrFiltersForSegment)

結合邏輯 AND 運算子的區隔篩選器群組清單。

OrFiltersForSegment

OR 群組中的區隔篩選器清單會使用邏輯 OR 運算子。

JSON 表示法
{
  "segmentFilterClauses": [
    {
      object(SegmentFilterClause)
    }
  ]
}
欄位
segmentFilterClauses[]

object(SegmentFilterClause)

要與 OR 運算子合併的區隔篩選器清單。

SegmentFilterClause

用於區隔定義的篩選器子句,也可以搭配指標或維度篩選器使用。

JSON 表示法
{
  "not": boolean,

  // Union field dimensionOrMetricFilter can be only one of the following:
  "dimensionFilter": {
    object(SegmentDimensionFilter)
  },
  "metricFilter": {
    object(SegmentMetricFilter)
  }
  // End of list of possible types for union field dimensionOrMetricFilter.
}
欄位
not

boolean

比對篩選器的互補項 (!)。

聯集欄位 dimensionOrMetricFilter。維度或指標篩選器。dimensionOrMetricFilter 只能是下列其中一項:
dimensionFilter

object(SegmentDimensionFilter)

區隔定義的維度篩選器。

metricFilter

object(SegmentMetricFilter)

區隔定義的指標篩選器。

SegmentDimensionFilter

維度篩選器可指定維度的篩選選項。

JSON 表示法
{
  "dimensionName": string,
  "operator": enum(Operator),
  "caseSensitive": boolean,
  "expressions": [
    string
  ],
  "minComparisonValue": string,
  "maxComparisonValue": string
}
欄位
dimensionName

string

套用篩選器的維度名稱。

operator

enum(Operator)

用來比對維度和運算式的運算子。

caseSensitive

boolean

如果比對項目有大小寫之分,IN_LIST 運算子則予以忽略。

expressions[]

string

運算式清單,只有第一個元素會用於所有運算子

minComparisonValue

string

BETWEEN 比對類型的最小比較值。

maxComparisonValue

string

BETWEEN 比對類型的比較值上限。

運算子

支援不同的比對類型。

列舉
OPERATOR_UNSPECIFIED 如未指定比對類型,系統會將其視為 REGEXP。
REGEXP 系統會將比對運算式視為規則運算式。所有其他比對類型都不會視為規則運算式。
BEGINS_WITH 比對開頭為提供比對運算式的值。
ENDS_WITH 比對結尾與提供的比對運算式的值。
PARTIAL 子字串比對。
EXACT 值應與比對運算式完全相符。
IN_LIST

這個選項可用於指定維度篩選器,這個篩選器的運算式可擷取所選值清單中的任何值。如此可避免評估每個回應列使用 OR 的多個完全比對維度篩選器。例如:

expressions: ["A", "B", "C"]

維度值為 A、B 或 C 的所有回應列,皆與這個 DimensionsFilter 相符。

NUMERIC_LESS_THAN

整數比較篩選器。系統會忽略這些條件的大小寫,並假設運算式是代表整數的字串。失敗條件:

  • if 運算式不是有效的 int64,用戶端應該會預期發生錯誤。
  • 輸入維度不是有效的 int64 值,一律不會符合篩選器。

檢查維度是否小於比對運算式。

NUMERIC_GREATER_THAN 檢查維度是否大於比對運算式的值。
NUMERIC_BETWEEN 檢查比對運算式的最小和最大值之間的維度是否為數值 (排除邊界)。

SegmentMetricFilter

要在區隔篩選器子句中使用的指標篩選器。

JSON 表示法
{
  "scope": enum(Scope),
  "metricName": string,
  "operator": enum(Operator),
  "comparisonValue": string,
  "maxComparisonValue": string
}
欄位
scope

enum(Scope)

指標的範圍定義了定義該指標的層級。指定指標範圍必須等於或大於資料模型中定義的主要範圍。如果區隔選取使用者或工作階段,則主要範圍的定義。

metricName

string

要篩選的指標。metricFilter 必須包含指標名稱。

operator

enum(Operator)

指定要執行比較指標的作業。預設為 EQUAL

comparisonValue

string

要用來比較的值。如果運算子是 BETWEEN,系統會將這個值視為最小比較值。

maxComparisonValue

string

最大比較值僅適用於 BETWEEN 運算子。

範圍

指標範圍定義定義該指標的層級:PRODUCTHITSESSIONUSER。指標值也適用於超出主要範圍的範圍。例如:您可以在 SESSIONUSER 層級記錄 ga:pageviewsga:transactions 的資料,方法是根據使用者在這些工作階段中或這些使用者的每次命中中,增加相應的值。

列舉
UNSPECIFIED_SCOPE 如未指定範圍,系統會根據區隔嘗試選擇使用者或工作階段,預設為條件範圍 USERSESSION
PRODUCT 產品範圍。
HIT 命中範圍。
SESSION 工作階段範圍。
USER 使用者範圍。

運算子

不同的比較類型選項。

列舉
UNSPECIFIED_OPERATOR 系統會將未指定的運算子視為 LESS_THAN 運算子。
LESS_THAN 檢查指標值是否小於比較值。
GREATER_THAN 檢查指標值是否大於比較值。
EQUAL 等於運算子。
BETWEEN 運算子之間的最小值和最大值會排除。我們會使用 LTGT 進行比較。

SequenceSegment

順序條件由一或多個步驟組成,每個步驟則由一或多個維度/指標條件定義。多個步驟可與特殊序列運算子搭配使用。

JSON 表示法
{
  "segmentSequenceSteps": [
    {
      object(SegmentSequenceStep)
    }
  ],
  "firstStepShouldMatchFirstHit": boolean
}
欄位
segmentSequenceSteps[]

object(SegmentSequenceStep)

序列中的步驟清單。

firstStepShouldMatchFirstHit

boolean

如有設定,第一個步驟條件必須與 (日期範圍內) 訪客第一次命中相符。

SegmentSequenceStep

區隔序列定義。

JSON 表示法
{
  "orFiltersForSegment": [
    {
      object(OrFiltersForSegment)
    }
  ],
  "matchType": enum(MatchType)
}
欄位
orFiltersForSegment[]

object(OrFiltersForSegment)

序列會以「或」分組的篩選條件清單指定,這些篩選條件結合 AND 運算子。

matchType

enum(MatchType)

指定步驟是否緊接在下一個步驟之前,或任一時間早於下個步驟。

MatchType

序列的比對類型。

列舉
UNSPECIFIED_MATCH_TYPE 系統會將未指定的比對類型視為優先。
PRECEDES 運算子表示前一個步驟發生在下一個步驟。
IMMEDIATELY_PRECEDES 運算子表示前一個步驟緊接在下一個步驟。

資料透視

「資料透視」描述要求中的樞紐分析部分。「資料透視」會以次要維度做為資料透視,藉此重整某些報表中的表格資訊。

JSON 表示法
{
  "dimensions": [
    {
      object(Dimension)
    }
  ],
  "dimensionFilterClauses": [
    {
      object(DimensionFilterClause)
    }
  ],
  "metrics": [
    {
      object(Metric)
    }
  ],
  "startGroup": number,
  "maxGroupCount": number
}
欄位
dimensions[]

object(Dimension)

可顯示為資料透視欄的維度清單。資料透視最多只能有 4 個維度。要求中允許的維度總數限制是資料透視維度的一部分。

dimensionFilterClauses[]

object(DimensionFilterClause)

DimensionsFilterClauses 會將邏輯與 AND 運算子結合:只有所有包含這些 DimensionsFilterClauses 中的資料,才會計入這個資料透視區域中的值。維度篩選器可用來限制資料透視區域中顯示的資料欄。舉例來說,如果您將 ga:browser 做為資料透視區域的要求維度,而且指定了按鍵篩選器將 ga:browser 限制為僅限「IE」或「Firefox」,則只有這兩個瀏覽器會顯示為資料欄。

metrics[]

object(Metric)

資料透視指標。要求中允許的指標總數限制是資料透視指標的一部分。

startGroup

number

如果要求 k 指標,回應就會包含部分以資料為基礎的部分資料,報表中包含的 k 欄。舉例來說,如果您依據維度 ga:browser 進行透視,您會取得「Firefox」的 k 欄、「IE」的 k 欄、「Chrome」的 k 欄等等。資料欄群組的順序取決於前 k 值「總數」的遞減順序。系統會按照第一個資料透視維度的字母順序排序,再依據第二個資料透視維度的字母順序排序,以此類推。舉例來說,如果 Firefox、IE 和 Chrome 的第一個值總計為 8、2、8,各欄的順序應為 Chrome、Firefox、IE。

透過下列指令,您可以選擇要在回應中包含哪些 k 欄群組。

maxGroupCount

number

指定要傳回的群組數量上限。預設值為 10,最大值為 1,000。

CohortGroup

定義同類群組群組。例如:

"cohortGroup": {
  "cohorts": [{
    "name": "cohort 1",
    "type": "FIRST_VISIT_DATE",
    "dateRange": { "startDate": "2015-08-01", "endDate": "2015-08-01" }
  },{
    "name": "cohort 2"
     "type": "FIRST_VISIT_DATE"
     "dateRange": { "startDate": "2015-07-01", "endDate": "2015-07-01" }
  }]
}
JSON 表示法
{
  "cohorts": [
    {
      object(Cohort)
    }
  ],
  "lifetimeValue": boolean
}
欄位
cohorts[]

object(Cohort)

同類群組的定義。

lifetimeValue

boolean

啟用生命週期價值 (LTV)。生命週期價值會評估透過不同管道招攬到的使用者生命週期價值。請參閱「同類群組分析」和「生命週期價值」這兩篇文章,如果 LTV 的值為 false:

  • 指標值與網頁介面同類群組報表中的值類似。
  • 同類群組定義日期範圍必須與日曆週和月份一致。也就是說,當您要求 ga:cohortNthWeek 同類群組定義中的 startDate 時,其定義應為星期日,endDate 應為下週六,而對於 ga:cohortNthMonth 來說,startDate 應為當月的第 1 天,endDate 應為當月的最後一天。

如果生命週期價值為 true:

  • 指標值會與網頁介面 LifeTime 值報表中的值相對應。
  • 「生命週期價值」報表會顯示招攬到使用者後的 90 天內,使用者價值 (收益) 和參與度 (應用程式觀看次數、目標達成數、工作階段數和工作階段持續時間) 的增長情形。
  • 系統會按照時間增量計算每位使用者的累計平均指標。
  • 同類群組定義日期範圍不必與日曆週和月份邊界保持一致。
  • viewId 必須是應用程式資料檢視 ID

同類群組

定義同類群組。同類群組是指具有共同特徵的一群使用者。舉例來說,客戶開發日期是同一天的所有使用者,會歸入相同的同類群組。

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

string

同類群組的專屬名稱。如未定義名稱,系統會自動使用同類群組_[1234...] 值產生名稱。

type

enum(Type)

同類群組的類型。目前唯一支援的類型為 FIRST_VISIT_DATE。如未指定這個欄位,系統會將同類群組視為 FIRST_VISIT_DATE 類型同類群組。

dateRange

object(DateRange)

用於 FIRST_VISIT_DATE 個同類群組,因為同類群組會選取在「日期範圍」中定義的「開始日期」和「結束日期」之間,首次造訪日期介於該日的使用者。同類群組要求的日期範圍應一致。如果要求包含 ga:cohortNthDay,其長度應剛好是一天,假如 ga:cohortNthWeek 應與週邊界 (從週日到週六結束) 對齊,ga:cohortNthMonth 的日期範圍則應與當月一致 (從第一天開始,到當月最後一天結束)。生命週期價值要求則沒有這類限制。您不需要為 reportsRequest.dateRanges 欄位提供日期範圍。

類型

同類群組類型。

列舉
UNSPECIFIED_COHORT_TYPE 如未指定,系統會將其視為 FIRST_VISIT_DATE
FIRST_VISIT_DATE 根據首次造訪日期選取的同類群組。

檢舉

與要求相對應的資料回應。

JSON 表示法
{
  "columnHeader": {
    object(ColumnHeader)
  },
  "data": {
    object(ReportData)
  },
  "nextPageToken": string
}
欄位
columnHeader

object(ColumnHeader)

欄標題。

data

object(ReportData)

回應資料。

nextPageToken

string

擷取清單中下一頁結果的頁面符記。

ColumnHeader

欄標題。

JSON 表示法
{
  "dimensions": [
    string
  ],
  "metricHeader": {
    object(MetricHeader)
  }
}
欄位
dimensions[]

string

回應中的維度名稱。

metricHeader

object(MetricHeader)

回應中指標的指標標頭。

MetricHeader

指標的標頭。

JSON 表示法
{
  "metricHeaderEntries": [
    {
      object(MetricHeaderEntry)
    }
  ],
  "pivotHeaders": [
    {
      object(PivotHeader)
    }
  ]
}
欄位
metricHeaderEntries[]

object(MetricHeaderEntry)

回應中指標的標頭。

pivotHeaders[]

object(PivotHeader)

回應中樞紐的標頭。

MetricHeaderEntry

指標的標題。

JSON 表示法
{
  "name": string,
  "type": enum(MetricType)
}
欄位
name

string

標頭名稱。

type

enum(MetricType)

指標的類型,例如 INTEGER

PivotHeader

要求中定義的每個資料透視部分的標題。

JSON 表示法
{
  "pivotHeaderEntries": [
    {
      object(PivotHeaderEntry)
    }
  ],
  "totalPivotGroupsCount": number
}
欄位
pivotHeaderEntries[]

object(PivotHeaderEntry)

單一資料透視區段的標題。

totalPivotGroupsCount

number

這項資料透視適用的群組總數。

PivotHeaderEntry

與回應中的資料透視部分要求的指標對應的每個指標欄標頭。

JSON 表示法
{
  "dimensionNames": [
    string
  ],
  "dimensionValues": [
    string
  ],
  "metric": {
    object(MetricHeaderEntry)
  }
}
欄位
dimensionNames[]

string

樞紐回應中的維度名稱。

dimensionValues[]

string

資料透視表中的維度值。

metric

object(MetricHeaderEntry)

資料透視表中指標的指標標頭。

ReportData

報表中的資料部分。

JSON 表示法
{
  "rows": [
    {
      object(ReportRow)
    }
  ],
  "totals": [
    {
      object(DateRangeValues)
    }
  ],
  "rowCount": number,
  "minimums": [
    {
      object(DateRangeValues)
    }
  ],
  "maximums": [
    {
      object(DateRangeValues)
    }
  ],
  "samplesReadCounts": [
    string
  ],
  "samplingSpaceSizes": [
    string
  ],
  "isDataGolden": boolean,
  "dataLastRefreshed": string
}
欄位
rows[]

object(ReportRow)

每個不重複的維度組合都有一個 ReportRow。

totals[]

object(DateRangeValues)

針對每個要求的日期範圍,針對符合查詢的一組資料列,每個要求的值格式都會獲得一個總計。系統會先計算值格式中提及的指標,再評估值格式並做為純量運算式,藉此計算值格式的總和。例如:我們計算 3 / ((sum of all relevant ga:sessions) + 2)3 / (ga:sessions + 2)「總數」。系統會在分頁前計算總數。

rowCount

number

這項查詢的相符資料列總數。

minimums[]

object(DateRangeValues)

所有相符資料列的最小值和最大值。如果要求中的 hideValueRanges 為 false,或 rowCount 為零時,這兩個日期均為空白。

maximums[]

object(DateRangeValues)

所有相符資料列的最小值和最大值。如果要求中的 hideValueRanges 為 false,或 rowCount 為零時,這兩個日期均為空白。

samplesReadCounts[]

string (int64 format)

如果結果是取樣,這會傳回已讀取的樣本總數,每個日期範圍一個項目。如未對結果進行取樣,系統就不會定義這個欄位。詳情請參閱開發人員指南

samplingSpaceSizes[]

string (int64 format)

如果結果是取樣,這會傳回目前顯示的樣本總數,每個日期範圍一個項目。如未對結果進行取樣,系統就不會定義這個欄位。詳情請參閱開發人員指南

isDataGolden

boolean

指出針對這項要求的回應是否黃金。如果之後收到明確的相同要求,即便之後不再產生任何新結果,資料就會成為黃金時段。

dataLastRefreshed

string (Timestamp format)

上次重新整理報表資料的時間。凡是在這個時間戳記前收到的命中,都會納入報表中。

RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,範例:"2014-10-02T15:01:23.045123456Z"

ReportRow

報表中的一列。

JSON 表示法
{
  "dimensions": [
    string
  ],
  "metrics": [
    {
      object(DateRangeValues)
    }
  ]
}
欄位
dimensions[]

string

要求的維度清單。

metrics[]

object(DateRangeValues)

每個要求 DateRange 的指標清單。

DateRangeValues

用來傳回單一日期範圍 / 維度組合的指標清單

JSON 表示法
{
  "values": [
    string
  ],
  "pivotValueRegions": [
    {
      object(PivotValueRegion)
    }
  ]
}
欄位
values[]

string

每個值都會對應至要求中的每個指標。

pivotValueRegions[]

object(PivotValueRegion)

每個資料透視區域的值。

PivotValueRegion

資料透視區域中的指標值。

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

string

每個資料透視區域的指標值。

ResourceQuotasRemaining

要求完成後,資源剩餘的資源配額權杖。

JSON 表示法
{
  "dailyQuotaTokensRemaining": number,
  "hourlyQuotaTokensRemaining": number
}
欄位
dailyQuotaTokensRemaining

number

剩餘每日資源配額。

hourlyQuotaTokensRemaining

number

每小時的資源配額權杖。

試試看!