В этом документе объясняется, как использовать API отчетов по многоканальным последовательностям для доступа к данным многоканальных последовательностей.
Введение
API отчетов по многоканальным последовательностям обеспечивает доступ к табличным данным в стандартных и пользовательских отчетах по многоканальным последовательностям. Чтобы получить доступ к данным, вы создаете запрос, который указывает: представление (профиль), даты начала и окончания, а также измерения и показатели, составляющие заголовки столбцов в таблице. Этот запрос отправляется в API отчетности по многоканальным последовательностям, и API отчетности по многоканальным последовательностям возвращает все данные в виде таблицы.
Если вы новичок в API, прочтите Обзор API отчетности по многоканальным последовательностям, чтобы получить представление о назначении API отчетности по многоканальным последовательностям и данных, которые он предоставляет.
Прежде чем вы начнете
В этом руководстве используется клиентская библиотека Java для доступа к API отчетов по многоканальным последовательностям. Каждая клиентская библиотека предоставляет один объект службы Analytics для вызова API отчетов по многоканальным последовательностям для получения данных. Если вы не используете клиентскую библиотеку для доступа к API, прочтите Справочное руководство по API отчетности по многоканальным последовательностям .
Чтобы создать объект службы Analytics:
- Зарегистрируйте свое приложение в консоли Google API .
- Разрешите доступ к данным Google Analytics.
- Напишите код для создания объекта службы Analytics.
Если вы еще не выполнили эти шаги, остановитесь и прочитайте руководство Hello Analytics API , которое проведет вас через начальные этапы создания приложения Google Analytics API. После завершения руководства продолжайте читать следующее руководство.
Например, следующий код создает авторизованный объект службы Analytics :
Джава
Analytics analytics = initializeAnalytics();
Используйте analytics объектов службы Analytics для вызова API отчетов по многоканальным последовательностям.
Обзор
Чтобы использовать API отчетов по многоканальным последовательностям для получения данных, напишите приложение для:
- Запросите API отчетов по многоканальным последовательностям.
- Работайте с результатами, возвращаемыми из API.
Запрос API отчетов по многоканальным последовательностям
Чтобы запросить данные из API отчетности по многоканальным последовательностям:
- Создайте объект запроса API отчетов по многоканальным последовательностям.
- Используйте объект запроса, чтобы запросить данные с серверов многоканальных последовательностей.
Создание запроса к API отчетов по многоканальным последовательностям
Чтобы создать объект запроса API отчетов по многоканальным последовательностям, вызовите этот метод:
analytics.data.mcf.get() // analytics is the Analytics service object
Первый параметр, передаваемый методу, — это уникальный идентификатор таблицы в формате ga:XXXX , где XXXX — это идентификатор представления (профиля) Analytics, содержащего запрошенные данные. Используйте объект запроса, чтобы указать параметры запроса (т. е. setDimensions ). Например:
Джава
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);
Список всех параметров запроса см. в разделе Сводка параметров запроса . Параметры метрик и размеров позволяют указать, какие данные из многоканальных последовательностей нужно получить. Список всех параметров и показателей см. в Справочнике по параметрам и метрикам .
Выполнение запроса данных API отчетности по многоканальным последовательностям
После создания объекта запроса вызовите метод execute объекта, чтобы запросить данные с серверов многоканальных последовательностей. Например:
Джава
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
Если запрос API отчетности по многоканальным последовательностям выполнен успешно, он возвращает данные отчета и информацию о данных.
Данные отчетов многоканальных последовательностей
Запрос возвращает следующие данные табличной отчетности:
- Данные заголовка столбца
- Данные ряда
Данные заголовка столбца
Ответ на запрос имеет поле заголовка столбца, содержащее информацию заголовка таблицы. Поле представляет собой список (или массив) объектов ColumnHeaders , каждый из которых содержит имя столбца, тип столбца и тип данных столбца. Порядок столбцов — это столбцы измерений, за которыми следуют столбцы показателей в том же порядке, который указан в исходном запросе. Например, следующий метод печатает заголовки столбцов:
Джава
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, возвращаются в виде двумерного List McfData.Rows . Каждый McfData.Rows представляет одну ячейку, которая является либо примитивным значением типа String , либо значением пути преобразования типа McfData.Rows.ConversionPathValue . Порядок ячеек в строке такой же, как и поля в объекте заголовка столбца, описанном выше.
Поскольку данные в каждой ячейке возвращаются либо в виде строки, либо в виде типа последовательности многоканальных последовательностей, поле DataType в каждом объекте заголовка столбца особенно полезно для синтаксического анализа значений в соответствующие типы. См. справочное руководство для всех возможных типов данных.
Например, следующий метод печатает заголовки и строки таблицы:
Джава
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");
}
}
В следующем примере показано, как проанализировать объект типа последовательности «Многоканальные последовательности» и преобразовать его в строку:
Джава
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();
}
Сообщить информацию
Помимо данных отчета, запрос возвращает информацию (например, идентификатор отчета) о данных. Например, следующий метод печатает информацию отчета:
Джава
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), не соответствуют значениям, отображаемым в веб-интерфейсе. Дополнительную информацию см. в разделе Выборка .
Просмотр информации (профиля)
Ответ на запрос включает идентификатор веб-ресурса, имя и идентификатор представления (профиля), а также идентификатор учетной записи Analytics, содержащей представление (профиль). Например, следующий метод выводит их на терминал (стандартный вывод):
Джава
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 , который содержит значения всех параметров запроса запроса данных. Например, следующий метод печатает значения таких параметров:
Джава
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 ) отчета.
Информация о страницах
Любой запрос API отчетности по многоканальным последовательностям может соответствовать сотням тысяч строк данных многоканальных последовательностей. API отчетов по многоканальным последовательностям будет возвращать только подмножество, называемое одной страницей данных, в определенный момент времени. Чтобы получить все страницы данных, используйте поле нумерации страниц. Следующий метод печатает информацию о страницах:
Джава
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 . Используйте общие значения для расчета средних значений.
Джава
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());
}
}
Рабочий образец
Джава
Google API Клиентская библиотека Java Пример API для создания отчетов по многоканальным последовательностям