本文档介绍在 Core Reporting API 中使用细分的语法和注意事项。
简介
使用 Core Reporting API 的细分功能时,您可以通过两种方式在 Core Reporting API 中请求细分:
按 ID 细分
您可以使用内置细分或自定义细分的 ID 在 Core Reporting API 中请求细分。可以使用 Google Analytics(分析)Management API 中
“细分”集合的 list
方法检索用户的所有可用细分。对于每个片段,
细分资源的 id
属性中都提供了相应 ID。
要了解有关在 API 请求中使用细分 ID 的详情,请参阅 Core Reporting API 参考。
动态细分
您也可以在发出 API 请求时动态创建和使用细分。通常,在创建动态细分时,您应该考虑以下事项:
下文将概括介绍创建动态细分时要考虑的每个事项。要查看动态细分的完整语法,请参阅动态细分语法参考。
允许在细分中使用的维度和指标。
并非所有维度和指标都可以在细分中使用。要查看允许在细分中使用哪些维度和指标,请访问
维度和指标浏览器。
1. 选择用户还是选择会话
指定您要选择用户还是选择会话(或两者皆选)。
- 使用
users::
选择用户。 - 使用
sessions::
选择会话。 - 如果同时指定了
users::
和sessions::
条件:- 系统会首先应用“用户”条件,并输出符合条件的用户的会话。
- 会话条件仅适用于在第 1 步中筛选出的会话。
例如:
- 选择在至少一个会话中使用过 Chrome 浏览器的用户。
users::condition::ga:browser==Chrome
- 选择使用 Chrome 浏览器的会话。
sessions::condition::ga:browser==Chrome
- 从至少有 1 个使用 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. 使用指标范围
指标范围定义了指标定义的级别:HIT、SESSION 或 USER。例如,ga:pageviews
和 ga:transactions
是命中级指标,因为它们发生在命中中;而 ga:sessionDuration
和 ga:bounces
则是会话级指标,因为它们针对每个会话只有一个值。
从概念上讲,“用户”是最高级别范围,“匹配”是最低级别范围。
报告指标值的范围也可以大于其主要范围。
例如,只需将 ga:pageviews
和 ga:transactions
这两个会话中发生的每个命中或这些用户的命中相加,便可在“会话”级和“用户”级进行报告。
您可以指定每个指标条件的范围,而这个范围将确定在哪一级别应用条件。指标范围使用 perUser::
、perSession::
或 perHit::
前缀指定。
例如:
- 选择在网站上花费了至少 10 美元的用户(即用户的生命周期价值至少为 10 元)。
users::condition::perUser::ga:transactionRevenue>=10
- 选择在一次会话中花费了至少 10 美元的用户。
users::condition::perSession::ga:transactionRevenue>=10
范围限制
为确保指定查询有效,Core Reporting API 会对指标范围进行验证。范围验证规则如下:
- 指定的指标范围必须始终等于或小于其父级条件范围(以
users::
或sessions::
前缀表示)。 - 指定的指标范围必须等于或大于其主要范围(根据数据模型中的定义)。要查看指标及对应主要范围的完整列表,请参阅指标:主要范围参考。
以下均为有效指标范围示例:
- 条件范围和指标范围相同(即USER 级)。
users::condition::perUser::ga:transactionRevenue>10
- 条件范围大于指标范围(例如,USER > SESSION)。
users::condition::perSession::ga:transactionRevenue>10
ga:totalEvents
是命中级指标,因此在条件中它可能的范围为perHit::
、perSession::
或perUser::
(因为这三个级别均大于或等于命中级范围)。users::condition::perHit::ga:totalEvents>5
users::condition::perSession::ga:totalEvents>5
以下均为无效指标范围示例:
- 下面的细分无效,因为父级条件范围小于指标范围(即SESSION < USER)。
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 个步骤。
简单条件
简单条件由一个或多个可合并的维度/指标组成。
简单条件可以使用的有效条件运算符包括:
- 使用 AND 或 OR 运算符合并条件。
- 维度和指标运算符。
简单条件的语法为:
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
处理 condition1 和 condition2 来选择用户:
users::<condition1>;<condition2>
users::<condition1>users::<condition2>
顺序条件
顺序条件由一个或多个步骤组成,其中每个步骤都由一个或多个维度/指标条件定义。利用特殊的顺序运算符可以将多个步骤合并在一起。
以下是可用于顺序条件的有效顺序运算符:
–>>
运算符表示前一个步骤在后一个步骤之前。–>
运算符表示,后一个步骤紧接着前一个步骤发生。
顺序条件的语法为:
sequence:: NOT? FIRST_HIT_MATCHES_FIRST_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 运算符结合使用,优先级更高。
所用语法与合并过滤条件的语法相同。有关详情,请参见 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 | 用户 |