本文介绍如何使用 Multi-Channel Funnels Reporting API 访问多渠道路径数据。
简介
Multi-Channel Funnels Reporting API 可用于访问多渠道路径标准报告和自定义报告中的表格数据。要访问数据，您需要创建指定以下内容的查询：数据视图（配置文件）、开始日期和结束日期、构成表格列标题的维度和指标。此查询将会发送给 Multi-Channel Funnels Reporting API，然后 Multi-Channel Funnels Reporting API 会以表格形式返回所有数据。
如果您刚开始使用该 API，请参阅 Multi-Channel Funnels Reporting API 概览，简要了解 Multi-Channel Funnels Reporting API 的用途及其提供的数据。
准备工作
本指南使用 Java 客户端库访问 Multi-ChannelFunnel Reporting API。每个客户端库提供单个 Google Analytics（分析）服务对象，用于调用 Multi-ChannelFunnel Reporting API 来获取数据。如果您不使用客户端库访问 API，请参阅 Multi-ChannelFunnel Reporting API - 参考指南。
要创建 Google Analytics（分析）服务对象，请执行以下操作：
- 在 Google API 控制台中注册您的应用。
- 授予访问 Google Analytics（分析）数据的权限。
- 编写代码以创建 Google Analytics（分析）服务对象。
如果您尚未完成上述步骤，请停止操作，并阅读 Google Analytics（分析）API 入门教程，该教程将为您详细介绍构建 Google Analytics（分析）API 应用的初始步骤。完成本教程后，请继续阅读以下指南。
例如，以下代码可 创建一个授权的 Google Analytics（分析）服务对象：
Java
Analytics analytics = initializeAnalytics();
您可以使用 Google Analytics（分析）服务对象 analytics 来调用 Multi-ChannelFunnel Reporting API。
概览
要使用 Multi-ChannelFunnel Reporting API 检索数据，请编写一个应用执行以下操作：
- 查询 Multi-ChannelFunnel Reporting API。
- 处理从 API 返回的结果。
查询 Multi-Channel Funnels Reporting API
要请求 Multi-ChannelFunnel Reporting API 中的数据，请执行以下操作：
- 创建 Multi-ChannelFunnel Reporting API 查询对象。
- 使用查询对象从多渠道漏斗服务器请求数据。
创建 Multi-Channel Funnels Reporting API 查询
要创建 Multi-ChannelFunnel Reporting API 查询对象，请调用以下方法：
analytics.data.mcf.get() // analytics is the Analytics service object
为该方法提供的第一个参数是唯一表格 ID，格式为 ga:XXXX，其中 XXXX 是包含所请求数据的 Google Analytics（分析）数据视图（配置文件）的 ID。使用查询对象可指定查询参数（即setDimensions）。例如：
Java
Get apiQuery = analytics.data().mcf()
.get(tableId,
"2012-01-01", // Start date
"2012-03-31", // End date
"mcf:totalConversions") // Metrics
.setDimensions("mcf:sourcePath")
.setSort("-mcf:totalConversions")
.setMaxResults(25);
有关所有查询参数的列表，请参阅 查询参数摘要。利用指标和维度参数，您可以指定从多渠道漏斗中获取哪些数据。如需查看所有维度和指标的列表，请参阅 维度和指标参考。
发出 Multi-Channel Funnels Reporting API 数据请求
创建查询对象后，请针对该对象调用 execute 方法，以请求来自多渠道漏斗服务器的数据。例如：
Java
try {
apiQuery.execute();
// Success. Do something cool!
} catch (GoogleJsonResponseException e) {
// Catch API specific errors.
handleApiError(e);
} catch (IOException e) {
// Catch general parsing network errors.
e.printStackTrace();
}
如果您想改为访问原始 API 响应，请对查询对象调用 executeUnparsed() 方法：
HttpResponse response = apiQuery.executeUnparsed();
如果查询成功，则返回所请求的数据。如果发生错误，execute 方法会抛出异常，其中包含错误的状态代码和对错误的说明。应用应捕获并处理异常。
处理 API 结果
如果 Multi-ChannelFunnel Reporting API 查询成功，则会返回报告数据以及与数据有关的信息。
多渠道路径报告数据
查询将返回以下表格式报告数据：
- 列标题数据
- 行数据
列标题数据
该查询响应有一个列标题字段，其中包含表格标题信息。该字段是一个 ColumnHeaders 对象列表（或数组），其中每个对象都包含列名称、列类型和列数据类型。列的顺序与原始查询中指定的顺序相同，维度列后跟指标列。例如，以下方法可显示列标题：
Java
private static void printColumnHeaders(McfData mcfData) {
System.out.println("Column Headers:");
for (ColumnHeaders header : mcfData.getColumnHeaders()) {
System.out.println("Column Name: " + header.getName());
System.out.println("Column Type: " + header.getColumnType());
System.out.println("Column Data Type: " + header.getDataType());
}
}
行数据
API 返回的主数据采用 McfData.Rows 的二维 List 形式返回。每个 McfData.Rows 表示一个单元格，单元格的值可能是 String 类型的原始值，也可能是 McfData.Rows.ConversionPathValue 类型转化路径值。行中单元格的顺序与上述列标题对象中字段的顺序相同。
由于每个单元格中的数据都会以字符串或多渠道漏斗序列类型的形式返回，因此每个列标题对象中的 DataType 字段对于将值解析为相应类型来说特别有用。如需了解所有可能的数据类型，请参阅
参考指南。
例如，以下方法会输出表格标题和行：
Java
private static void printDataTable(McfData mcfData) {
System.out.println("Data Table:");
if (mcfData.getTotalResults() > 0) {
// Print the column names.
List<ColumnHeaders> headers = mcfData.getColumnHeaders();
for (ColumnHeaders header : headers) {
System.out.print(header.getName());
}
System.out.println();
// Print the rows of data.
for (List<McfData.Rows> row : mcfData.getRows()) {
for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) {
ColumnHeaders header = headers.get(columnIndex);
McfData.Rows cell = row.get(columnIndex);
if (header.getDataType().equals("MCF_SEQUENCE")) {
System.out.print(getStringFromMcfSequence(cell.getConversionPathValue()));
} else {
System.out.print(cell.getPrimitiveValue());
}
}
System.out.println();
}
} else {
System.out.println("No rows found");
}
}
以下示例展示了如何解析 多渠道漏斗序列类型对象并将其转换为字符串：
Java
private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) {
StringBuilder stringBuilder = new StringBuilder();
for (McfData.Rows.ConversionPathValue pathElement : path) {
if (stringBuilder.length() > 0)
stringBuilder.append(" > ");
stringBuilder.append(pathElement.getNodeValue());
}
return stringBuilder.toString();
}
报告信息
除了报告数据之外，该查询还会返回有关数据的信息（例如报告 ID）。例如，以下方法会输出报告信息：
Java
private static void printReportInfo(McfData mcfData) {
System.out.println("Report Info:");
System.out.println("ID:" + mcfData.getId());
System.out.println("Self link: " + mcfData.getSelfLink());
System.out.println("Kind: " + mcfData.getKind());
System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData());
}
containsSampledData 字段可告知您该查询响应是否为抽样结果。由于抽样可能会影响查询结果，所以从查询 (API) 返回的抽样值与网页界面上显示的值不一致。如需了解详情，请参阅抽样。
数据视图（配置文件）信息
查询响应包括网络媒体资源 ID、数据视图（配置文件）名称和 ID，以及包含该数据视图（配置文件）的 Google Analytics（分析）帐号的 ID。例如，以下方法会将这些信息输出到终端（标准输出）：
Java
private static void printProfileInfo(McfData mcfData) {
ProfileInfo profileInfo = mcfData.getProfileInfo();
System.out.println("View (Profile) Info:");
System.out.println("Account ID: " + profileInfo.getAccountId());
System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
System.out.println("Table ID: " + profileInfo.getTableId());
}
查询信息
查询响应包括一个 Query 对象，该对象包含所有数据请求查询参数的值。例如，以下方法会输出此类参数的值：
Java
private static void printQueryInfo(McfData mcfData) {
Query query = mcfData.getQuery();
System.out.println("Query Info:");
System.out.println("Ids: " + query.getIds());
System.out.println("Start Date: " + query.getStartDate());
System.out.println("End Date: " + query.getEndDate());
System.out.println("Metrics: " + query.getMetrics()); // List of Analytics metrics
System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions
System.out.println("Sort: " + query.getSort()); // List of sorte metrics or dimensions
System.out.println("Segment: " + query.getSegment());
System.out.println("Filters: " + query.getFilters());
System.out.println("Start Index: " + query.getStartIndex());
System.out.println("Max Results: " + query.getMaxResults());
}
query.getMetrics()、query.getDimensions() 和 query.getSort() 以外的方法会返回 String。例如，query.getStartDate() 会返回报告的开始日期（一个 String）。
分页信息
任何 Multi-Channel Funnels Reporting API 请求均可能与数十万行多渠道路径数据相匹配。Multi-ChannelFunnel Reporting API 在任何给定时间只会返回一部分数据，被称为一页数据。如需检索所有页面的数据，请使用分页字段。以下方法可显示分页信息：
Java
private static void printPaginationInfo(McfData mcfData) {
System.out.println("Pagination Info:");
System.out.println("Previous Link: " + mcfData.getPreviousLink());
System.out.println("Next Link: " + mcfData.getNextLink());
System.out.println("Items Per Page: " + mcfData.getItemsPerPage());
System.out.println("Total Results: " + mcfData.getTotalResults());
}
方法调用 mcfData.getTotalResults() 会返回查询的总行数，可能会大于查询返回的总行数。方法调用 mcfData.getItemsPerPage() 可返回查询响应可以包含的行数上限。
方法调用 mcfData.getPreviousLink() 可返回指向上一页的链接，mcfData.getNextLink() 则可返回指向下一页的链接。
所有结果的总值
如需获取所请求指标在所有结果（而不仅仅是查询响应中返回的结果）的总值，请对查询响应（一个 McfData 对象）调用 getTotalsForAllResults() 方法。使用总值计算平均值。
Java
private static void printTotalsForAllResults(McfData mcfData) {
System.out.println("Metric totals over all results:");
Map<String, String> totalsMap = mcfData.getTotalsForAllResults();
for (Map.Entry<String, String> entry : totalsMap.entrySet()) {
System.out.println(entry.getKey() + " : " + entry.getValue());
}
}
工作示例
Java
Google API Java 客户端库 Multi-Channel Funnels Reporting API 示例