本文提供有关 Multi-Channel Funnels Reporting API 查询和响应的完整参考。
简介
利用 Multi-Channel Funnels Reporting API，您可以请求 Google Analytics（分析）多渠道路径报告数据。每个报告均包含根据跟踪代码发回给 Google Analytics（分析）的数据得到的统计信息，这些信息按维度和指标进行划分。通过自行选择维度和指标的组合，您可以使用报告 API 来根据自己的规范生成自定义报告。
该 API 包含一种请求报告数据的方法：report.get。 通过这种方法，您需要提供与您希望提取其数据的数据视图（配置文件）相对应的表格 ID。另外，您还可以指定以下各项内容：
- 维度和指标的组合。
- 日期范围。
- 一组用于控制返回哪些数据的选项参数。
该 API 在 REST 端点 ( https://www.googleapis.com/analytics/v3/data/mcf) 上提供了 report.get 方法。 以下部分显示了一个示例请求，并介绍了每个参数。
请求
该 API 提供如下用于请求数据的单一方法：
analytics.data.mcf.get()
另外，也可以采用 REST 端点的形式查询该 API：
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
每个网址查询参数指定一个 API 查询参数（必须经过网址编码）。
发送到 Multi-ChannelFunnel Reporting API 的所有请求都必须进行授权（最好通过 OAuth 2.0 授权）。
查询参数汇总
下表汇总了 Multi-ChannelFunnel Reporting API 接受的所有查询参数。点击每个参数名称即可查看详细说明。
| 名称 | 值 | 必需 | 摘要 |
|---|---|---|---|
ids |
string |
是 | ga:XXXX 形式的唯一表格 ID，其中 XXXX 是查询从中提取数据的 Google Analytics（分析）数据视图（配置文件）的 ID。 |
start-date |
string |
是 |
获取 Google Analytics（分析）数据的开始日期。请求可以指定格式为 YYYY-MM-DD 的开始日期或相对日期（例如today、yesterday 或 NdaysAgo，其中 N 为正整数）。
|
end-date |
string |
是 |
获取 Google Analytics（分析）数据的结束日期。请求可以指定格式为 YYYY-MM-DD 的结束日期，也可以指定相对日期（例如today、yesterday 或 NdaysAgo，其中 N 为正整数）。
|
metrics |
string |
是 | 以英文逗号分隔的指标的列表，例如 mcf:totalConversions,mcf:totalConversionValue。有效查询必须至少指定一个指标。 |
dimensions |
string |
否 | 您的“多渠道漏斗”报告的一系列以英文逗号分隔的维度，例如 mcf:source,mcf:keyword。 |
sort |
string |
否 | 以英文逗号分隔的一系列维度和指标，用于指示所返回数据的排序顺序和排序方向。 |
filters |
string |
否 | 维度或指标过滤条件，用于限制您的请求返回的数据。 |
samplingLevel |
string |
否 | 需要的抽样级别。允许的值：
|
start-index |
integer |
否 | 要检索的第一行数据，从 1 开始。此参数可与 max-results 参数搭配使用，作为分页机制。 |
max-results |
integer |
否 | 响应中包含的行数上限。 |
查询参数详情
ids
ids=ga:12345
ga: 与报告的数据视图（配置文件）ID 串联而成。您可以使用 analytics.management.profiles.list 方法获取报告的数据视图（配置文件）ID，此方法会在
Google Analytics（分析）Management API 的“数据视图（配置文件）”资源中提供 id。start-date
start-date=2011-10-01
start-date 和 end-date 参数，服务器会返回错误。
日期值可以是使用 YYYY-MM-DD 模式的特定日期，也可以使用 today、yesterday 或 NdaysAgo 模式的相对日期值。
值必须与 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) 匹配。start-date 是 2011-01-01。
start-date 没有上限限制。以下示例使用相对日期表示过去 7 天的日期范围（从昨天开始向前追溯）：
&start-date=7daysAgo &end-date=yesterday
end-date
end-date=2011-10-31
start-date 和 end-date 参数，服务器会返回错误。
日期值可以是使用 YYYY-MM-DD 模式的特定日期，也可以使用 today、yesterday 或 NdaysAgo 模式的相对日期值。
值必须与 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) 匹配。end-date 为 2005-01-01。end-date 没有上限限制。以下示例使用相对日期表示过去 10 天的日期范围（从今天开始向前追溯）：
&start-date=9daysAgo &end-date=today
dimensions
dimensions=mcf:source,mcf:keyword
“dimensions”参数定义了“多渠道漏斗”报告的主要数据键，如 mcf:source 或 mcf:medium。
使用维度对转化指标进行细分。例如，虽然您可以询问网站的总转化次数，但询问按媒介细分的转化次数可能更有趣。
在这种情况下，您将看到来自自然、引荐、电子邮件等来源的转化次数。
在数据请求中使用 dimensions 时，请注意以下限制：
- 您在任何查询中最多只能提供 7 个维度。
- 您不能发送完全由维度组成的查询：必须将所请求的维度与至少一个指标进行组合。
不可用的值
当无法确定维度的具体值时，Google Analytics（分析）会使用特殊的字符串 (not set)。
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
有关用户在您网站上的活动的汇总统计信息，例如总转化次数或总转化价值。
如果查询没有 dimensions 参数，则返回的指标会提供所请求日期范围内的汇总值，例如总体总转化价值。不过，在请求维度时，值将按维度值细分。
例如，如果请求使用 mcf:source 方法，则 mcf:totalConversions 会返回每个来源的总转化次数。
请求指标时，请注意以下事项：
- 任何请求都必须包含至少一个指标；请求不能完全由维度组成。
- 对于任何查询，您最多可以提供 10 个指标。
sort
sort=mcf:source,mcf:medium
用于指示返回数据的排序顺序和排序方向的一系列指标和维度。
- 排序顺序由所列指标和维度指定，其中指标和维度的排序优先级从左到右依次降低。
- 排序方向默认为升序。您可以通过为所请求的字段添加减号 (
-) 前缀将排序方向改为降序。direction
通过对查询结果排序，您可以解决许多数据方面的疑问。例如，要解决“我的哪些转化来源最多，通过哪些媒介？”这个问题，
您可以使用以下参数进行查询。查询结果首先按 mcf:source 排序，然后按 mcf:medium 排序，并且这两个指标均按升序排序：
sort=mcf:source,mcf:medium
要回答“哪些媒介带来的转化次数最多，以及通过哪些来源带来转化？”这样的问题，您可以使用以下参数进行查询。查询结果首先按 mcf:medium 排序，然后按 mcf:source 排序，并且这两个指标均按升序排序：
sort=mcf:medium,mcf:source
使用 sort 参数时，请注意以下几点：
- 只能按在
dimensions或metrics参数中使用的维度或指标值进行排序。如果您请求按未在 dimensions 或 metrics 参数中指定的字段排序，将会收到错误。 - 默认情况下，字符串将按 en-US 语言区域的字母顺序升序排序。
- 默认情况下，数字将按数值顺序升序排序。
- 默认情况下，日期将按日期顺序升序排序。
filters
filters=mcf:medium%3D%3Dreferral
filters 查询字符串参数会限制从您的请求返回的数据。如需使用 filters 参数，请提供要用作过滤依据的维度或指标，后跟过滤器表达式。例如，以下查询针对数据视图（配置文件）12134 请求 mcf:totalConversions 和 mcf:source，其中 mcf:medium 维度是字符串 referral：
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
有关详情，请参阅 Core Reporting API 参考。
samplingLevel
samplingLevel=DEFAULT
DEFAULT— 返回的响应采用默认抽样规模，速度和准确度相平衡。FASTER— 返回的响应采用较小抽样规模，但响应速度更快。HIGHER_PRECISION— 返回的响应采用较大抽样规模，准确度更高，但是响应速度可能较慢。
DEFAULT 抽样级别。max-results
max-results=100
此响应中包含的行数上限。您可以将此参数与 start-index 结合使用，以检索一部分元素；也可以单独使用此参数，以限制返回的元素数量（从第一个元素开始返回）。
如果未提供 max-results，则查询默认最多返回 1000 行。
无论您要求返回多少行结果，对于每个请求，Multi-Channel Funnels Reporting API 最多只能返回 10000 行。如果维度细分数量达不到您的预期，API 返回的行数也可能小于请求的数量。例如，如果 mcf:medium 的可能值少于 300 个，那么当仅按媒介细分时，即使您将 max-results 设置为更高的值，所获得的行数也不能超过 300 行。
响应
如果成功，此请求将返回具有下面定义的 JSON 结构的响应正文。
请注意：“结果”一词指的是与查询条件相符的所有行，而“响应”指的是当前结果页上返回的所有行。如果结果总数超过当前响应的页面大小，则这些 ID 可能会有所不同（如 itemsPerPage 中所述）。
响应格式
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
响应字段
响应正文结构的属性定义如下：
| 属性名称 | 值 | 说明 |
|---|---|---|
kind |
string |
资源类型。值为“analytics#mcfData”。 |
id |
string |
此数据响应的 ID。 |
query |
object |
此对象包含以参数形式传递给查询的所有值。有关每个字段含义的介绍，请参阅对应查询参数的说明。 |
query.start-date |
string |
开始日期。 |
query.end-date |
string |
结束日期。 |
query.ids |
string |
唯一表格 ID。 |
query.dimensions[] |
list |
分析维度列表。 |
query.metrics[] |
list |
分析指标列表。 |
query.sort[] |
list |
用作数据排序依据的指标或维度列表。 |
query.filters |
string |
以逗号分隔的指标或维度过滤条件列表。 |
query.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
行起始索引。默认值为 1。 |
query.max-results |
integer |
每页显示的结果数上限。 |
startIndex |
integer |
行起始索引由 start-index 查询参数指定。默认值为 1。 |
itemsPerPage |
integer |
响应所能包含的行数上限，与返回的实际行数无关。如果指定了 max-results 查询参数，则 itemsPerPage 的值将在 max-results 或 10,000 中取较小者。itemsPerPage 的默认值为 1000。
|
totalResults |
integer |
查询结果中的总行数，与响应中返回的行数无关。对于生成大量行的查询，totalResults 可以大于 itemsPerPage。请参阅 Paging，了解有关用于大型查询的 totalResults 和 itemsPerPage 的更多说明。
|
selfLink |
string |
指向此数据查询结果页的链接。 |
previousLink |
string |
指向此数据查询前一结果页的链接。 |
nextLink |
string |
指向此数据查询下一结果页的链接。 |
profileInfo |
object |
与作为数据请求对象的数据视图（配置文件）相关的信息。数据视图（配置文件）数据可以通过 Google Analytics（分析）Management API 得到。 |
profileInfo.profileId |
string |
数据视图（配置文件）ID，例如 1174。 |
profileInfo.accountId |
string |
此数据视图（配置文件）所属的账号 ID，例如 30481。 |
profileInfo.webPropertyId |
string |
此数据视图（配置文件）所属的网络媒体资源 ID，例如 UA-30481-1。 |
profileInfo.internalWebPropertyId |
string |
此数据视图（配置文件）所属的网络媒体资源的内部 ID，例如 UA-30481-1。 |
profileInfo.profileName |
string |
数据视图（配置文件）的名称。 |
profileInfo.tableId |
string |
数据视图（配置文件）的表格 ID，由“ga:”紧接数据视图（配置文件）ID 组成。 |
containsSampledData |
boolean |
当响应包含抽样数据时为 true。 |
sampleSize |
string |
计算抽样数据所用的样本数量。 |
sampleSpace |
string |
抽样空间总大小。指明抽样可用的样本空间的总大小。 |
columnHeaders[] |
list |
列标题，其中列出维度名称和指标名称（先维度名称后指标名称）。维度和指标的顺序与请求中通过 metrics 和 dimensions 参数指定的维度和指标的顺序相同。标头数量等于维度数量与指标数量之和。 |
columnHeaders[].name |
string |
维度或指标的名称。 |
columnHeaders[].columnType |
string |
列类型。值为“DIMENSION”或“METRIC”。 |
columnHeaders[].dataType |
string |
数据类型。维度列标题只有 "STRING" 或 "MCF_SEQUENCE" 作为数据类型。
指标列标题包含指标值的数据类型，例如 "INTEGER"、"DOUBLE"、"CURRENCY" 等。 |
totalsForAllResults |
object |
以指标名称和值这种键值对的形式，给出所请求指标值的总计。指标总计的顺序与请求中指定的指标顺序相同。 |
rows[] |
list |
报告数据行，其中每行都包含一个
{
"primitiveValue": "2183"
}
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
错误代码
如果请求成功，Multi-Channel Funnels Reporting API 会返回 200 HTTP 状态代码。如果在处理查询期间发生错误，该 API 会返回错误代码和说明。每个使用 Analytics API 的应用都需要实现适当的错误处理逻辑。如需详细了解错误代码及其处理方式，请参阅
错误响应参考指南。
试试看！
请使用下面的 API Explorer 对实际数据调用此方法，并查看响应。
采样
Google Analytics（分析）需要即时计算维度和指标的特定组合。为了在合理的时间内返回数据，Google Analytics（分析）可能只会处理一部分数据。
您可以通过设置 samplingLevel 参数，为请求指定要使用的抽样级别。
如果 MCF Reporting API 响应中包含抽样数据，则 containsSampledData 响应字段将为 true。此外，sampleSize 和 sampleSpace 这两个属性还会提供有关查询的抽样级别信息。利用这两个值，您可以计算用于查询的会话所占的百分比。例如，如果 sampleSize 为 201,000，sampleSpace 为 220,000，则报告的抽样基准是 (201,000 / 220,000) * 100 = 91.36% 的会话。
有关抽样及 Google Analytics（分析）中抽样方法的一般说明，请参阅抽样。
处理大规模的数据结果
如果您预计查询会返回大量结果，请参考以下指南，帮助您优化 API 查询、避免错误以及最大限度减少配额超支情况。请注意，我们设定了性能基准，允许每个 API 请求最多包含 7 个维度和 10 个指标。虽然某些指定大量指标和维度的查询可能比其他查询需要更长的处理时间，但限制所请求指标的数量可能不足以提高查询性能。 不过，您可以使用以下方法获得最佳性能。
减少每个查询中的维度数量
该 API 允许在任何请求中指定最多 7 个维度。 很多时候，Google Analytics（分析）必须实时计算这些复杂查询的结果。如果结果行数很多，这样做可能特别耗时。 例如，按城市（按小时）查询关键字可能会匹配数百万行数据。您可以限制查询中维度的数量，以减少 Google Analytics（分析）处理的行数，从而提高性能。
按日期范围拆分查询
对于日期范围较长的日期键结果，除了分页之外，您还可以考虑仅针对一周甚至一天创建单独查询。当然，对于大型数据集，即使请求一天的数据，返回的数量也可能会超过 max-results，在这种情况下，分页无法避免。但在任何情况下，如果与查询匹配的行数高于 max-results，对日期范围进行拆分可能会缩短获取结果所需的总时间。无论是单线程查询还是并行查询，上述方法都有助于提高性能。
分页
对结果进行分页是将较大的结果集拆分成易管理区块的有效方式。totalResults 字段指示存在多少匹配行，itemsPerPage 则提供结果中可返回的最大行数。如果 totalResults 与 itemsPerPage 的比率较高，则个别查询可能需要更长的时间。如果您只需要有限数量的行（例如，仅用于显示目的），您可能会发现使用 max-results 参数明确限制响应大小会非常方便。不过，如果您的应用需要处理的结果总量非常大，那么，请求行数上限将能提高效率。
使用 gzip
要降低单个请求的带宽需求，您可以选择启用 gzip 压缩，这是一种既方便又简单的方法。虽然这种方法需要一些额外的 CPU 时间对结果进行解压缩，但考虑到它对节约网络费用的贡献，通常还是值得一用的。要接收 gzip 编码的响应，您必须执行以下两项操作：设置 Accept-Encoding 标头，并修改用户代理，使其包含字符串 gzip。
下面提供了一个用于启用 gzip 压缩的格式正确的 HTTP 标头示例：
Accept-Encoding: gzip User-Agent: my program (gzip)