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

Use the Analytics service object analytics to call the 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 Reporting API

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

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

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

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

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