Multi-Channel Funnels Reporting API - 参考指南

本文档提供了有关 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 的开始日期,也可以指定相对日期(例如,todayyesterdayNdaysAgo,其中 N 为正整数)。
end-date string 提取 Google Analytics(分析)数据的结束日期。请求可以指定格式为 YYYY-MM-DD 的结束日期,也可以指定相对日期(例如,todayyesterdayNdaysAgo,其中 N 为正整数)。
metrics string 以英文逗号分隔的一系列指标,例如 mcf:totalConversions,mcf:totalConversionValue。有效查询必须指定至少一个指标。
dimensions string 您的多渠道路径报告的一系列以英文逗号分隔的维度,例如 mcf:source,mcf:keyword
sort string 以英文逗号分隔的一系列维度和指标,用于指示返回数据的排序顺序和排序方向。
filters string 维度或指标过滤条件,用于限制您的请求返回的数据。
samplingLevel string 需要的抽样级别。允许使用的值:
  • DEFAULT — 返回的响应采用默认抽样规模,速度和准确度相平衡。
  • FASTER — 返回的响应采用较小抽样规模,但响应速度更快。
  • HIGHER_PRECISION — 返回的响应采用较大抽样规模,准确度更高,但是响应速度可能较慢。
start-index integer 要从哪一行开始提取数据,默认为从 1 开始。此参数与 max-results 参数搭配使用,可以作为分页机制。
max-results integer 响应中包含的行数上限。

查询参数详情

ids

ids=ga:12345
必需参数。
用于提取多渠道路径数据的唯一 ID。此 ID 是由命名空间 ga: 与报告的数据视图(配置文件)ID 组合而成。您可以使用 analytics.management.profiles.list 方法提取报告的数据视图(配置文件)ID(此方法能够提供 Google Analytics(分析)Management API 数据视图(配置文件)资源中的 id)。

返回页首


start-date

start-date=2011-10-01
必需参数。
所有多渠道路径数据请求都必须指定日期范围。如果您不在请求中添加 start-dateend-date 参数,服务器会返回一个错误。日期值可以是采用 YYYY-MM-DD 格式的具体日期,也可以是采用 todayyesterdayNdaysAgo 格式的相对日期。所采用的值必须符合以下规范:[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
最早的有效 start-date2011-01-01start-date 没有上限限制。
相对日期始终与发出查询之时的当前日期相对,而且基于查询中指定的数据视图(配置文件)的时区。

以下示例使用相对日期表示过去 7 天的日期范围(从昨天开始向前追溯):

  &start-date=7daysAgo
  &end-date=yesterday

返回页首


end-date

end-date=2011-10-31
必需参数。
所有多渠道路径数据请求都必须指定日期范围。如果您不在请求中添加 start-dateend-date 参数,服务器会返回一个错误。日期值可以是采用 YYYY-MM-DD 格式的具体日期,也可以是采用 todayyesterdayNdaysAgo 格式的相对日期。所采用的值必须符合以下规范:[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
最早的有效 end-date2005-01-01end-date 没有上限限制。
相对日期始终与发出查询之时的当前日期相对,而且基于查询中指定的数据视图(配置文件)的时区。

以下示例使用相对日期表示过去 10 天的日期范围(从今天开始向前追溯):

  &start-date=9daysAgo
  &end-date=today

返回页首


dimensions

dimensions=mcf:source,mcf:keyword
可选参数。

dimensions 参数用于定义多渠道路径报告的主数据键,例如 mcf:sourcemcf: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 参数时,请注意以下事项:

  • 只能按在 dimensionsmetrics 参数中使用的维度值或指标值进行排序。如果您请求按未在 dimensions 或 metrics 参数中指定的字段排序,将会收到错误。
  • 默认情况下,字符串将按 en-US 语言区域的字母顺序升序排序。
  • 默认情况下,数字将按数值顺序升序排序。
  • 默认情况下,日期将按日期顺序升序排序。

返回页首


filters

filters=mcf:medium%3D%3Dreferral
可选参数。

filters 查询字符串参数可以限制由您的请求返回的数据。要使用 filters 参数,请提供要用作过滤依据的维度或指标,然后紧接着提供过滤条件表达式。例如,以下查询针对数据视图(配置文件)12134 请求 mcf:totalConversionsmcf: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 抽样级别。
要详细了解 Google Analytics(分析)如何计算查询所用会话数的百分比,请参阅抽样一节。

返回页首


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 中所述),这两个词代表的结果数会有所不同。

响应格式

JSON
{
  "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。请参阅分页,了解当查询返回的结果非常多时,有关使用 totalResultsitemsPerPage 的更多说明。
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 列标题,其中列出维度名称和指标名称(先维度名称后指标名称)。维度和指标的顺序与请求中通过 metricsdimensions 参数指定的维度和指标的顺序相同。标头数量等于维度数量与指标数量之和。
columnHeaders[].name string 维度或指标的名称。
columnHeaders[].columnType string 列类型。值为“DIMENSION”或“METRIC”。
columnHeaders[].dataType string 数据类型。维度列标头只有 "STRING""MCF_SEQUENCE" 这两种数据类型。指标列标头指明指标值的数据类型,例如 "INTEGER""DOUBLE""CURRENCY" 等。
totalsForAllResults object 以指标名称和值这种键值对的形式,给出所请求指标值的总计。指标总计的顺序与请求中指定的指标顺序相同。
rows[] list

报告数据行,其中每行都包含一个 Mcf.Rows 对象列表。该内部列表表示维度值和指标值(维度值在指标值之前),其顺序与请求中指定的顺序相同。每行都包含由 N 个字段组成的列表,其中 N = 维度数量 + 指标数量。

一个 Mcf.Rows 对象中封装了另一个类型可能为 primitiveValueconversionPathValue 的对象。维度值的类型可以是上述任一类型之一,但是所有指标值的类型只能是 primitiveValue

primitiveValue 其实就是封装在对象内的一个字符串。例如:


{
  "primitiveValue": "2183"
}

conversionPathValue 是一个对象,它封装在一组对象中,其中每个对象均包含一个 nodeValue 字符串和一个可选的 interactionType 字符串。例如:


{
  "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。另外,sampleSizesampleSpace 这两个属性也会为查询提供与抽样级别相关的信息。利用这两个值,您可以计算查询所用会话数的百分比。例如,如果 sampleSize201,000sampleSpace220,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 指定结果中可返回的行数上限。如果 totalResultsitemsPerPage 的比率较高,则具体查询花费的时间可能会比必要时间要长。如果您只需要有限数量的行(例如只是为了显示结果),您会发现使用 max-results 参数明确限制响应规模会非常方便。不过,如果您的应用需要处理的结果总量非常大,那么,请求行数上限将能提高效率。

使用 gzip

要降低单个请求的带宽需求,您可以选择启用 gzip 压缩,这是一种既方便又简单的方法。虽然这种方法需要一些额外的 CPU 时间对结果进行解压缩,但考虑到它对节约网络费用的贡献,通常还是值得一用的。要接收 gzip 编码的响应,您必须执行以下两项操作:设置 Accept-Encoding 标头,并且修改您的用户代理以包含字符串 gzip。以下是正确格式的 HTTP 标头(用于启用 gzip 压缩)的示例:

Accept-Encoding: gzip
User-Agent: my program (gzip)