本文档提供了有关 Multi-Channel Funnels Reporting API 查询和响应的完整参考。
简介
利用 Multi-Channel Funnels Reporting API,您可以请求 Google Analytics(分析)多渠道路径报告数据。每个报告均包含根据跟踪代码发回给 Google Analytics(分析)的数据得到的统计信息,这些信息按维度和指标进行划分。通过自行选择维度和指标的组合,您可以使用报告 API 来根据自己的规范生成自定义报告。
该 API 包含一个用于请求报告数据的方法:report.get。通过该方法,您可以提供与您要从中提取数据的数据视图(配置文件)相对应的表格 ID。另外,您还可以指定以下各项内容:
- 维度和指标的组合。
- 日期范围。
- 一组用于控制返回哪些数据的选项参数。
该 API 在 REST 端点上提供 report.get 方法:https://www.googleapis.com/analytics/v3/data/mcf。下一节将介绍一个示例请求,并对每个参数进行说明。
请求
该 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-Channel Funnels Reporting API 的所有请求都必须得到授权(最好是通过 OAuth 2.0 授权)。
查询参数汇总
下表汇总了 Multi-Channel Funnels 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 对转化指标进行细分。例如,虽然您可以查询自己网站的总转化次数,但是查询按媒介细分的转化次数可能会让您更感兴趣。进行这类查询时,您将看到自然搜索、引荐和电子邮件等媒介带来的转化次数。
在数据请求中使用 dimensions
时,请注意以下限制:
- 您在任何查询中最多只能提供 7 个维度。
- 您不能发送完全由维度组成的查询:必须将所请求的维度与至少一个指标进行组合。
不可用的值
当无法确定维度的具体值时,Google Analytics(分析)会使用特殊的字符串 (not set)。
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
用户在您网站上的活动的汇总统计数据,例如总转化次数或总转化价值。如果查询中没有使用 dimensions
参数,则返回的指标将提供所请求日期范围内的汇总值,例如总转化价值。不过,如果查询中请求了维度,返回的值就会按维度值细分。例如,如果请求 mcf:totalConversions
并使用了 mcf:source
,则系统将返回按来源细分的总转化次数。
请求指标时,请注意以下事项:
- 任何请求都必须包含至少一个指标;请求不能完全由维度组成。
- 对于任何查询,您最多可以提供 10 个指标。
sort
sort=mcf:source,mcf:medium
用于指示返回数据的排序顺序和排序方向的一系列指标和维度。
- 排序顺序由所列指标和维度指定,其中指标和维度的排序优先级从左到右依次降低。
- 排序方向默认为升序。您可以通过为所请求的字段添加减号 (
-
) 前缀将排序方向改为降序。
通过对查询结果排序,您可以解决许多数据方面的疑问。例如,要解决“哪些来源带来的转化次数最多,以及通过哪些媒介带来转化?”这样的问题,您可以使用以下参数进行查询。查询结果首先按 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,那么当仅按媒介细分时,您能得到的结果将不会超过 300 行,即使您将 max-results
设为超过 300 的值仍是如此。
响应
如果成功,此请求返回的响应正文将具有如下定义的 JSON 结构。
请注意:“结果”一词指的是与查询条件相符的所有行,而“响应”指的是当前结果页上返回的所有行。当结果总数大于当前响应页面可显示的结果数上限时(如 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 或 10000 之间取较小者。itemsPerPage 的默认值为 1000。
|
totalResults |
integer |
查询结果中的总行数,与响应中返回的行数无关。如果查询结果包含的行数非常多,totalResults 可能会大于 itemsPerPage 。请参阅分页,了解当查询返回的结果非常多时,有关使用 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 会返回错误代码和相关说明。使用 Google Analytics(分析)API 的每个应用都必须实现适当的错误处理逻辑。有关错误代码以及处理方法的详情,请参阅错误响应参考指南。
立即试用!
您可以尝试一下向 Multi-Channel Funnels Reporting API 发送查询。
-
要在请求中发送实时数据并查看 JSON 格式的响应,您可以在
Google API Explorer
中尝试 analytics.data.mcf.get 方法。
抽样
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
。以下是正确格式的 HTTP 标头(用于启用 gzip 压缩)的示例:
Accept-Encoding: gzip User-Agent: my program (gzip)