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 会以表格形式返回所有数据。

如果您刚开始使用该 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(分析)服务对象,请执行以下操作:

  1. Google API 控制台中注册您的应用。
  2. 授予访问 Google Analytics(分析)数据的权限。
  3. 编写代码,以创建 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 提取数据,请编写一个应用来执行以下操作:

  1. 查询 Multi-Channel Funnels Reporting API。
  2. 处理 API 返回的结果。

查询 Multi-Channel Funnels Reporting API

要通过 Multi-Channel Funnels Reporting API 请求数据,请执行以下操作:

  1. 创建 Multi-Channel Funnels Reporting API 查询对象。
  2. 使用该查询对象请求多渠道路径服务器中的数据。

创建 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 示例