本文介绍如何使用 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-Channel Funnels Reporting API。每个客户端库提供单个 Analytics 服务对象来调用 Multi-Channel Funnels Reporting API,从而获取数据。 每个客户端库提供单个 Analytics 服务对象来访问所有的 Core Reporting API 数据。如果您没有使用客户端库访问该 API,请参阅 Multi-Channel Funnels Reporting API - 参考指南。
要创建 Google Analytics(分析)服务对象,请执行以下操作:
- 在 Google API 控制台中注册您的应用。
- 授予访问 Google Analytics(分析)数据的权限。
- 编写代码,以创建 Analytics 服务对象。
如果您未能完成上述步骤,请停止操作,并阅读 Hello Google Analytics(分析)API 入门教程,该教程将为您详细介绍构建 Google Analytics(分析)API 应用的最初几个步骤。学完该教程后,请继续阅读以下指南。
例如,以下代码可创建已获授权的 Analytics 服务对象:
Java
Analytics analytics = initializeAnalytics();
使用 Analytics 服务对象 analytics
来调用 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 请求数据,请执行以下操作:
- 创建 Multi-Channel Funnels Reporting API 查询对象。
- 使用该查询对象请求多渠道路径服务器中的数据。
创建 Multi-Channel Funnels Reporting API 查询
要创建 Multi-Channel Funnels Reporting API 查询对象,请调用以下方法:
analytics.data.mcf.get() // analytics is the Analytics service object
为该方法提供的第一个参数是 ga:XXXX
形式的唯一表格 ID,其中 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();
如果查询成功,则 API 会返回请求的数据。如果发生错误,execute
方法就会抛出异常,其中包含错误的状态代码以及对错误的说明。该应用应能够捕获并处理异常。
处理 API 结果
如果 Multi-Channel Funnels Reporting API 查询成功,则 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-Channel Funnels 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 示例