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, прочитайте эту статью.

Подготовка к работе

В этой статье описывается, как использовать клиентскую библиотеку Java для доступа к Multi-Channel Funnels Reporting API. В каждой библиотеке реализован один объект службы Google Analytics, который обеспечивает доступ ко всем данным Multi-Channel Funnels Reporting API. Если вы не используете клиентскую библиотеку для доступа к API, ознакомьтесь с этим руководством.

Чтобы создать служебный объект Google Analytics, выполните следующие действия:

  1. Зарегистрируйте приложение в Google Developers Console.
  2. Разрешите доступ к Google Analytics.
  3. Напишите код для создания служебного объекта Google Analytics.

Если у вас возникли проблемы, узнайте, как начать работу с приложением Google Analytics API, из этого руководства, а затем переходите к изучению информации, изложенной в этой статье.

Вот пример кода, в котором создается авторизованный служебный объект Google Analytics:

Java

Analytics analytics = initializeAnalytics();

Используйте служебный объект analytics для вызова 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.

  1. Создайте объект запроса к Multi-Channel Funnels Reporting API.
  2. С помощью этого объекта запросите данные с серверов Multi-Channel Funnels API.

Как создать запрос к Multi-Channel Funnels Reporting API

Чтобы создать объект запроса к Multi-Channel Funnels Reporting API, вызовите этот метод:

analytics.data.mcf.get()    // analytics is the Analytics service object

В качестве первого параметра метод принимает уникальный идентификатор таблицы в формате ga:XXXX, где XXXX – это идентификатор представления (профиля) Google Аналитики, содержащего запрашиваемые данные. В этом же объекте указываются и параметры запроса (например, 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);

Полный список параметров запроса приведен здесь. Параметры metrics и dimensions позволяют указать, какие данные нужно получить из Multi-Channel Funnels API. Доступные параметры и показатели перечислены в этом документе.

Как выполнить запрос к Multi-Channel Funnels Reporting API

После создания объекта запроса вызовите его метод execute, чтобы запросить данные с серверов Multi-Channel Funnels API. Пример:

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 возвращаются данные отчетов и связанные с ними метаданные.

Данные отчетов по многоканальным последовательностям

Запрос возвращает следующие табличные данные отчетов:

  • данные заголовков столбцов;
  • данные строк.

Данные заголовков столбцов

Ответ на запрос содержит поле заголовка с информацией о заголовках таблицы в виде списка или массива объектов 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());
  }
}

Данные строк

Запрашиваемые данные возвращаются в виде двухмерного списка List параметров McfData.Rows. Каждый параметр 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();
}

Информация об отчете

Помимо самих данных отчетов, в ответе на запрос содержится также дополнительная информация (например, идентификатор отчета). Так, следующий метод выводит сведения об отчете:

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, и значениями в веб-интерфейсе. Подробнее…

Информация о представлении (профиле)

Ответ на запрос содержит идентификатор веб-ресурса, название и идентификатор представления (профиля) и идентификатор аккаунта Google Analytics, к которому относится представление (профиль). В примере ниже эта информация выводится на терминал (стандартный поток вывода).

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 могут соответствовать сотни тысяч строк с данными о многоканальных последовательностях, однако за один раз возвращается ограниченный набор или страница данных. Чтобы получить все страницы с данными, используйте поле pagination. Пример:

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() – на следующую.

Сводные данные по всем результатам

Чтобы получить итоговые значения запрошенных показателей по всем результатам, а не только по тем, которые возвращены в ответе, вызовите метод getTotalsForAllResults() в объекте ответа McfData. По итоговым значениям можно рассчитать средние значения.

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());
  }
}

Рабочий пример