Core Reporting API - 细分

本文档介绍在 Core Reporting API 中使用细分的语法和注意事项。

简介

使用 Core Reporting API 的细分功能时,您可以通过两种方式在 Core Reporting API 中请求细分:

  1. 按 ID 细分:使用内置细分或自定义细分的数字 ID 进行查询。
  2. 动态细分:在请求时动态指定细分。

按 ID 细分

您可以使用内置细分或自定义细分的 ID 在 Core Reporting API 中请求细分。用户的所有可用细分都可以使用 Google Analytics(分析)Management API 中细分集合list 方法来提取。每个细分的 ID 都存储在细分资源id 属性之中。

要了解有关在 API 请求中使用细分 ID 的详情,请参阅 Core Reporting API 参考

动态细分

您也可以在发送 API 请求时动态创建和使用细分。在创建动态细分时,您通常要考虑以下事项:

  1. 选择用户还是选择会话
  2. 使用条件还是使用顺序
  3. 使用指标范围

下文将概括介绍创建动态细分时要考虑的每个事项。要查看动态细分的完整语法,请参阅动态细分语法参考

允许在细分中使用的维度和指标。
并非所有维度和指标都能在细分中使用。要查看允许在细分中使用哪些维度和指标,请访问维度和指标浏览器

1. 选择用户还是选择会话

指定您要选择用户还是选择会话(或两者皆选)。

  • 使用 users:: 选择用户。
  • 使用 sessions:: 选择会话。
  • 如果同时指定了 users:: 条件和 sessions:: 条件:
    1. 系统会首先应用“用户”条件,并输出符合条件的用户的会话。
    2. 会话条件仅适用于在第 1 步中筛选出的会话。

例如:

  • 选择在至少一个会话中使用 Chrome 浏览器的用户。
    • users::condition::ga:browser==Chrome
  • 选择使用 Chrome 浏览器的会话。
    • sessions::condition::ga:browser==Chrome
  • 选择在至少一个会话中使用 Chrome 浏览器的用户,并从这些用户的会话中选出位于伦敦这一城市的会话。
    • users::condition::ga:browser==Chrome;sessions::condition::ga:city==London

有关选择用户和选择会话的详情,请参阅 conditionScope 一节中的语法参考。

2. 使用条件还是使用顺序

确定了要对用户还是要对会话进行细分之后,您还要指定一个或多个条件和/或顺序。

条件

条件使用 condition:: 前缀。例如:

  • 选择使用 Chrome 浏览器访问过网页的伦敦用户。
    • users::condition::ga:city==London;ga:browser==Chrome

顺序

顺序条件由一个或多个步骤组成,其中每个步骤都由一个或多个维度/指标条件定义。

指定基于顺序的条件时应使用 sequence:: 前缀和之后 (;–>>) 或之后紧接着 (;–>) 运算符。例如:

  • 选择首先使用桌面设备,之后又使用移动设备的用户。我们要对用户进行细分。这样做会搜索用户的所有会话,并检查用户是否在一个会话中使用过桌面设备,之后又在后来的会话中用过移动设备。
    • users::sequence::ga:deviceCategory==desktop;->>ga:deviceCategory==mobile
  • 您也可以在每一步中使用多重条件。
    • users::sequence::ga:deviceCategory==desktop;ga:operatingSystem==Windows->>ga:deviceCategory==mobile;ga:operatingSystem==Android
  • 您也可以使用 AND(即“;”)运算符在细分中结合使用条件和顺序。
    • users::condition::ga:totalEvents>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile

有关简单条件和基于顺序的条件的详情,请参阅 conditionType 一节中的语法参考。要查看更多示例,请参阅细分功能参考中的条件顺序这两节。

3. 使用指标范围

指标范围可以界定指标定义的级别(匹配、会话或用户)。例如,ga:pageviewsga:transactions 是“匹配”级别指标,因为它们发生在匹配过程之中;ga:sessionDurationga:bounces 是“会话”级别指标,因为这些“每次会话”指标有单一值。从概念上讲,“用户”是最高级别范围,“匹配”是最低级别范围。

报告指标值时所用的范围可以大于其主要范围。例如,对于 ga:pageviewsga:transactions 这两项“匹配”级别指标,只需将发生在会话中的匹配或用户实施的匹配予以累加,报告它们时就能使用“会话”级别和“用户”级别。

您可以指定每个指标条件的范围,而这个范围将确定在哪一级别应用条件。使用 perUser::perSession::perHit:: 前缀指定指标范围。

例如:

  • 选择在网站上花费了至少 10 元的用户(即用户的生命周期价值至少为 10 元)。
    users::condition::perUser::ga:transactionRevenue>=10
    
  • 选择在一次会话中花费了至少 10 元的用户。
    users::condition::perSession::ga:transactionRevenue>=10
    

范围限制

为确保指定查询有效,Core Reporting API 会对指标范围进行验证。范围验证规则如下:

  1. 指定的指标范围必须始终等于或小于父级条件范围(由 users::sessions:: 前缀表示)。
  2. 指定的指标范围必须等于或大于其主要范围(根据数据模型中的定义)。要查看指标及对应主要范围的完整列表,请参阅指标:主要范围参考

以下均为有效指标范围示例:

  • 条件范围和指标范围相等(即“用户”级别)。
    • users::condition::perUser::ga:transactionRevenue>10
  • 条件范围大于指标范围(即“用户”>“会话”)。
    • users::condition::perSession::ga:transactionRevenue>10
  • ga:totalEvents 是“匹配”级别指标,因此它在条件中可能的范围是 perHit::perSession::perUser::(因为所有这些都大于或等于“匹配”级别范围)。
    • users::condition::perHit::ga:totalEvents>5
    • users::condition::perSession::ga:totalEvents>5

以下均为无效指标范围示例:

  • 下面这个细分无效,因为父级条件范围小于指标范围(即“会话”<“用户”)。
    • sessions::condition::perUser::ga:transactionRevenue>10
  • 为“会话”级别指标使用“匹配”级别范围,而“匹配”级别<“会话”级别。
    • users::condition::perHit::ga:sessionDuration>60

默认范围

当没有为指标条件明确指定范围时,它会默认使用条件范围。例如,以下细分将为所有指标条件使用“用户”级别范围:users::condition::ga:transactionRevenue>=10;ga:sessionDuration>60

动态细分语法参考

基本语法

用于定义细分的语法格式为:segment=<segmentCondition>+。也就是说,细分由一个或多个 segmentCondition 语句组成。

<segmentCondition> 采用如下定义:<conditionScope><conditionType><dimensionOrMetricConditions>

其中:
conditionScope 指定条件的顶级范围。
conditionType 指定条件的类型。
dimensionOrMetricConditions 指定维度/指标条件或顺序步骤。

conditionScope

指定条件的顶级范围。可能的值包括:

  • 使用 users:: 选择用户。
  • 使用 sessions:: 选择会话。

有关 conditionScope 的限制和注意事项:

  • 如果在一个细分中指定多个用户条件和会话条件,必须使用 AND 运算符将它们合并。
  • 在既选择用户又选择会话的条件中,也必须使用 AND 运算符合并条件。当既指定了用户条件又指定了会话条件时,系统会首先应用用户条件查找符合条件的用户,之后再对筛选出的用户的会话应用所有会话条件。
  • 如果您使用任何用户级别条件,则日期范围一定不能超过 90 天
  • 条件范围也将决定其下所属的所有指标条件的默认范围级别(有关范围级别的详情,请参阅指标:主要范围参考)。

conditionType

指定条件的类型。可能的值包括:

  • 使用 condition:: 指定简单条件(非基于顺序的条件)。
  • 使用 sequence:: 指定基于顺序的条件。

有关 conditionType 的限制和注意事项:

  • 如果指定多个“简单条件”和“顺序”,必须使用 AND 运算符将它们合并。
  • 对于基于顺序的条件,一个细分中最多允许使用 10 个步骤。

简单条件

简单条件由一个或多个可合并的维度/指标组成。

简单条件可以使用的有效条件运算符包括:

简单条件的语法为:

condition::<dimensionOrMetricConditions>

简单条件示例:

  • users::condition::ga:transactionRevenue>10;ga:sessionDuration>60
  • 对于可能有多个维度/指标条件的给定简单条件,可以通过指定顶级否定运算符查找给定条件的补集。例如:users::condition::!ga:transactionRevenue>10;ga:sessionDuration>60

排除条件

排除条件用于创建不满足定义条件的细分。

相应语法使用 NOT 运算符! 字符)来否定某个条件并排除与该条件相符的会话。

排除退出网页与根网页路径完全相符的会话:
sessions::condition::!ga:exitPagePath==/

多重条件

您可以使用一个 users:: 前缀将所有用户级别条件归为一组,也可以为每个条件使用单独的 users:: 前缀。此规则同样适用于会话级别条件。

例如,以下两个细分是等同的。这两个细分均通过 AND 合并 condition1condition2 来选择用户:
users::<condition1>;<condition2>
users::<condition1>users::<condition2>

顺序条件

顺序条件由一个或多个步骤组成,其中每个步骤都由一个或多个维度/指标条件定义。利用特殊的顺序运算符可以将多个步骤合并在一起。

以下是可用于顺序条件的有效顺序运算符:

  • –>> 运算符表示,后一个步骤在前一个步骤之后发生。
  • –> 运算符表示,后一个步骤紧接着前一个步骤发生。

顺序条件的语法为:

sequence:: NOT? FIRST_HIT_MATCHES_FIRST_STEP? (AND (PRECEDES|IMMEDIATELY_PRECEDES) <step>)*

其中:

NOT! 表示
FIRST_HIT_MATCHES_FIRST_STEP^ 表示
PRECEDES;–>> 表示
IMMEDIATELY_PRECEDES;–> 表示
step<dimensionOrMetricConditions> 表示

顺序条件示例:

  • users::sequence::ga:deviceCategory==desktop;->ga:deviceCategory==tablet
  • 对于可能有多个步骤和/或维度/指标条件的指定顺序,仍然可以通过指定顶级否定运算符查找给定顺序的补集。例如:users::sequence::!ga:deviceCategory==desktop;->ga:deviceCategory==tablet
  • 利用 ^ 运算符可以指定,第一步要与给定日期范围内首个会话的第一次匹配相符。例如:users::sequence::^ga:deviceCategory==desktop;->ga:deviceCategory==tablet

会话日期条件

细分支持运用 dateOfSession 语法进行的一类分析;结合“之间”(<>) 运算符,您可以将细分限制为在一定日期范围内发起了会话的用户群组。dateOfSession 的最大日期范围为 31 天。有关其使用方法的详情,请参见下面的会话日期示例

维度和指标条件

合并条件

您可以使用 AND(即“;”)和 OR(即“,”)运算符合并一个或多个维度条件,其中 OR 运算符的运算优先级较高。

所用语法与合并过滤条件的语法相同。有关详情,请参见 Core Reporting API 参考中的合并过滤条件

运算符

下表介绍可在细分中使用的所有运算符,以及维度和/或指标是否支持使用这些运算符。

运算符 说明 是否支持在维度条件中使用? 是否支持在指标条件中使用?
== 等于,或完全匹配。
例如:ga:city==London

例如:ga:adCost==10
!= 不等于,或不完全匹配。
例如:ga:city!=London

例如:ga:adCost!=10
< 小于。 是(仅支持数值)。
例如:ga:hour<12

例如:ga:adCost<10
<= 小于或等于。 是(仅支持数值)。
例如:ga:hour<=12

例如:ga:adCost<=10
> 大于。 是(仅支持数值)。
例如:ga:hour>12

例如:ga:adCost>10
>= 大于或等于。 是(仅支持数值)。
例如:ga:hour>=12

例如:ga:adCost>=10
<> 之间(值介于给定的范围之间)。1 是(仅支持数值)。
例如:ga:hour<>1_12

例如:ga:adCost<>10_20
[] 在列表中(值是列出的值其中之一)。2
例如:ga:browser[]Chrome|Firefox|Opera
=@ 包含子字符串。
例如:ga:keyword=@shoes
!@ 不包含子字符串。
例如:ga:keyword!@shoes
=~ 包含与正则表达式匹配的内容。
例如:ga:keyword=~shoes
!~ 不包含与正则表达式匹配的内容。
例如:ga:keyword!~shoes

1“之间”运算符 <>
您可以利用此运算符查询介于一定范围内的值。取值范围包含上限和下限值,包含数值的指标和维度(例如 ga:hour)均支持使用此运算符。取值范围最小值和最大值之间必须用下划线分隔。

语法:
{dimensionOrMetricName}<>{minValue}_{maxValue}

示例:
选择在 12 点到 23 点这一时段内发生的会话。
sessions::condition::ga:hour<>12_23

2“在列表中”运算符 []
您可以使用此运算符查询给定列表中的值。只有维度能使用此运算符。列表中的值必须使用“|”字符分隔。如果值中包含“|”字符的话,必须进行转义。

语法:
{dimensionName}[]{value1}|{value2}|...

限制:
每个“在列表中”条件最多包含 10 个值(例如,ga:city[]city1|city2|...|city10)。

示例:
选择使用 Chrome、Firefox 或 Opera 浏览器的会话。
sessions::condition::ga:browser[]Chrome|Firefox|Opera

特殊字符转义

如果值表达式中包含特殊字符“,”和“;”,则必须进行转义。例如:ga:keyword==nike\,shoes

有关维度和指标条件的更多详情,请参阅 Core Reporting API 参考

限制条件

与维度和指标条件相关的限制包括:

  • 一个细分中最多包含 10 个维度或指标条件。
  • 指标条件表达式的最大长度为 1024 个字符。

迁移旧动态细分

使用 dynamic:: 前缀的旧动态细分等同于现有语法中使用维度和指标条件的会话级别细分。如果您使用的是旧动态细分,应当通过将 dynamic:: 前缀替换为 sessions::condition:: 前缀迁移到新语法。例如,以下两个细分是等同的:

dynamic::ga:browser==Chrome
等同于
sessions::condition::ga:browser==Chrome

细分示例

1. 受众特征:男性,语言是美国英语,对游戏感兴趣,来自于美洲。

首先应用基于用户的细分。因此,基于用户的条件应返回对游戏感兴趣的男性用户。然后根据基于会话的条件,对这些用户的会话进行筛选,找到在美洲发起的美国英语会话。

users::condition::ga:userGender==Male;users::condition::ga:interestAffinityCategory==Games ; sessions::condition::ga:region==Americas;sessions::condition::ga:language==en-u

2. 行为:选择以下用户:发起的会话数 > 100;在过去 7 天没有访问过网站;在每个会话中的交易次数 > 2 次;每个会话在网站上的时长 > 100 秒。

users::condition::ga:sessions>100;ga:daysSinceLastSession>=7; perSession::ga:transactions>2;perSession::ga:sessionDuration>100

3. 会话:选择以下会话:浏览器为 Chrome;国家/地区为美国;每次匹配中的异常次数 > 1 次;并且选择以下用户:每次会话中的退出次数 < 2 次。

sessions::condition::ga:browser==Chrome;ga:country==US;perHit::ga:exceptions>1; users::condition::perSession::ga:exits<2

4. 通过顺序条件选择会话:按这一步骤选择会话:浏览器为 Chrome;每次匹配中的事件总数 > 5。并且先按这一步骤选择用户:使用桌面设备;之后按这一步骤选择用户:使用移动设备。

sessions::sequence::ga:browser==Chrome;condition::perHit::ga:totalEvents>5;users::sequence::ga:deviceCategory==desktop->>ga:deviceCategory=mobile

5. 会话日期:选择以下用户:在 2014 年 5 月 20 日到 2014 年 5 月 30 日之间发起首次会话;在网站上的会话时长 > 600 秒。

users::sequence::^ga:sessionCount==1;dateOfSession<>2014-05-20_2014-05-30;->>ga:sessionDurationBucket>600

指标:主要范围参考

指标 主要范围
ga:adClicks匹配
ga:adCost匹配
ga:adsenseAdsClicks 匹配
ga:adsenseAdsViewed匹配
ga:adsenseAdUnitsViewed匹配
ga:adsenseCTR匹配
ga:adsenseECPM匹配
ga:adsensePageImpressions匹配
ga:adsenseRevenue匹配
ga:avgDomainLookupTime匹配
ga:avgDomContentLoadedTime匹配
ga:avgDomInteractiveTime匹配
ga:avgEventValue匹配
ga:avgPageDownloadTime匹配
ga:avgPageLoadTime匹配
ga:avgRedirectionTime匹配
ga:avgScreenviewDuration匹配
ga:avgSearchDepth匹配
ga:avgSearchDuration匹配
ga:avgSearchResultViews匹配
ga:avgServerConnectionTime匹配
ga:avgServerResponseTime匹配
ga:avgUserTimingValue匹配
ga:costPerConversion匹配
ga:costPerGoalConversion匹配
ga:costPerTransaction匹配
ga:CPC匹配
ga:CPM匹配
ga:CTR匹配
ga:domainLookupTime匹配
ga:domContentLoadedTime匹配
ga:domInteractiveTime匹配
ga:domLatencyMetricsSample匹配
ga:eventValue匹配
ga:exceptions匹配
ga:exceptionsPerScreenview匹配
ga:fatalExceptions匹配
ga:fatalExceptionsPerScreenview匹配
ga:goalAbandonRateAll匹配
ga:goalAbandonsAll匹配
ga:goalCompletionsAll匹配
ga:goalStartsAll匹配
ga:goalValueAll匹配
ga:goalValueAllPerSearch匹配
ga:goalXXAbandonRate匹配
ga:goalXXAbandons匹配
ga:goalXXCompletions匹配
ga:goalXXStarts匹配
ga:goalXXValue匹配
ga:impressions匹配
ga:itemQuantity匹配
ga:itemRevenue匹配
ga:itemsPerPurchase匹配
ga:localItemRevenue匹配
ga:localTransactionRevenue匹配
ga:localTransactionShipping匹配
ga:localTransactionTax匹配
ga:margin匹配
ga:metricXX匹配
ga:pageDownloadTime匹配
ga:pageLoadSample匹配
ga:pageLoadTime匹配
ga:pageValue匹配
ga:pageviews匹配
ga:percentSearchRefinements匹配
ga:redirectionTime匹配
ga:revenuePerItem匹配
ga:revenuePerTransaction匹配
ga:ROI匹配
ga:RPC匹配
ga:screenviews匹配
ga:searchDepth匹配
ga:searchDuration匹配
ga:searchGoalConversionRateAll匹配
ga:searchGoalXXConversionRate匹配
ga:searchRefinements匹配
ga:searchResultViews匹配
ga:searchUniques匹配
ga:serverConnectionTime匹配
ga:serverResponseTime匹配
ga:socialActivities匹配
ga:socialInteractions匹配
ga:socialInteractionsPerSession匹配
ga:speedMetricsSample匹配
ga:timeOnScreen匹配
ga:totalEvents匹配
ga:totalValue匹配
ga:transactionRevenue匹配
ga:transactions匹配
ga:transactionShipping匹配
ga:transactionTax匹配
ga:uniqueAppviews匹配
ga:uniqueEvents匹配
ga:uniquePageviews匹配
ga:uniquePurchases匹配
ga:uniqueScreenviews匹配
ga:uniqueSocialInteractions匹配
ga:userTimingSample匹配
ga:userTimingValue匹配
ga:adsenseExits会话
ga:avgTimeOnPage会话
ga:avgSessionDuration会话
ga:bounces会话
ga:entranceBounceRate会话
ga:entranceRate会话
ga:entrances会话
ga:eventsPerSessionWithEvent会话
ga:exitRate会话
ga:exits会话
ga:goalConversionRateAll会话
ga:goalValuePerSession会话
ga:goalXXConversionRate会话
ga:organicSearches会话
ga:pageviewsPerSession会话
ga:percentSessionsWithSearch会话
ga:screenviewsPerSession会话
ga:searchExitRate会话
ga:searchExits会话
ga:searchSessions会话
ga:sessionDuration会话
ga:transactionRevenuePerSession会话
ga:transactionsPerSession会话
ga:bounceRate会话
ga:sessions会话
ga:sessionsWithEvent会话
ga:newSessions用户
ga:percentNewSessions用户
ga:users用户