В этом документе объясняется, как использовать Core Reporting API для доступа к данным Google Analytics.
Введение
Core Reporting API обеспечивает доступ к табличным данным в стандартных и пользовательских отчетах Google Analytics. Чтобы получить доступ к данным, вы создаете запрос, который указывает: представление (профиль), даты начала и окончания, а также измерения и показатели, составляющие заголовки столбцов в таблице. Этот запрос отправляется в Core Reporting API, и Core Reporting API возвращает все данные в виде таблицы.
Если вы новичок в API, прочтите Обзор Core Reporting API , чтобы получить представление о назначении Core Reporting API и данных, которые он предоставляет.
Прежде чем вы начнете
В этом руководстве показано, как получить доступ к API Google Analytics с помощью языков программирования Java, Python, PHP и JavaScript.
- Прочтите страницу клиентских библиотек , чтобы получить полный список клиентских библиотек для конкретного языка программирования, которые работают с API.
- Прочтите Справочное руководство , чтобы получить доступ к API без клиентской библиотеки.
Каждая клиентская библиотека предоставляет один объект службы аналитики для доступа ко всем данным Core Reporting API. Чтобы создать объект службы, вам обычно необходимо выполнить следующие шаги:
- Зарегистрируйте свое приложение в консоли Google API .
- Разрешите доступ к данным Google Analytics.
- Создайте объект службы Analytics.
Если вы не выполнили эти шаги, остановитесь и прочитайте руководство Hello Google Analytics API . В этом руководстве вы пройдете начальные этапы создания приложения Google Analytics API. После завершения вы сможете использовать это руководство для выполнения реальных задач.
Следующий фрагмент кода содержит переменную для хранения авторизованного объекта службы.
Джава
Analytics analytics = // Read Hello Analytics Tutorial for details.
Питон
analytics = # Read Hello Analytics Tutorial for details.
PHP
$client = // Read Hello Analytics Tutorial for details. // Return results as objects. $client->setUseObjects(true); $analytics = new apiAnalyticsService($client);
Библиотека PHP вернет все результаты API в виде ассоциативного массива. Чтобы вместо этого вернуть реальные объекты, вы можете вызвать клиентский метод useObject , как показано в примере выше.
JavaScript
<script src="https://apis.google.com/js/client.js?onload=loadLib"</script>
<script>
function loadLib() {
// Handle all the authorization work.
// Read Hello Analytics Tutorial for details.
gapi.client.load('analytics', 'v3', makeApiCall);
}
</script>
Первый тег сценария загружает библиотеку JavaScript Google API. После загрузки выполняется loadLib для загрузки класса службы аналитики. После завершения gapi.client.analytics должен существовать в DOM и быть готовым к использованию для запроса к Core Reporting API.
После создания объекта службы аналитики вы готовы отправлять запросы к Core Reporting API.
Примечание . Объект службы аналитики также можно использовать для доступа к Management API .
Обзор
Приложение, использующее Core Reporting API, обычно выполняет два шага:
- Запросить основной API отчетов
- Работа с результатами API
Давайте рассмотрим оба шага.
Запросить основной API отчетов
Создайте запрос к API базовой отчетности.
Объект службы аналитики содержит метод для создания запроса Core Reporting API.
Каждый запрос Core Reporting API содержит набор параметров, которые определяют, какие данные следует возвращать. Одним из наиболее важных параметров запроса является параметр ids или идентификатор таблицы. Этот параметр указывает, из какого представления (профиля) Google Analytics следует получать данные. Значение имеет формат ga:xxx , где xxx — идентификатор представления (профиля).
Джава
Get apiQuery = analytics.data().ga()
.get(tableId, // Table Id.
"2012-01-01", // Start date.
"2012-01-15", // End date.
"ga:sessions") // Metrics.
.setDimensions("ga:source,ga:keyword")
.setSort("-ga:sessions,ga:source")
.setFilters("ga:medium==organic")
.setMaxResults(25);
Питон
api_query = service.data().ga().get(
ids=TABLE_ID,
start_date='2012-01-01',
end_date='2012-01-15',
metrics='ga:sessions',
dimensions='ga:source,ga:keyword',
sort='-ga:sessions,ga:source',
filters='ga:medium==organic',
max_results='25')
PHP
private function queryCoreReportingApi() {
$optParams = array(
'dimensions' => 'ga:source,ga:keyword',
'sort' => '-ga:sessions,ga:source',
'filters' => 'ga:medium==organic',
'max-results' => '25');
return $service->data_ga->get(
TABLE_ID,
'2010-01-01',
'2010-01-15',
'ga:sessions',
$optParams);
}
В этой библиотеке метод get не только создает запрос к Core Reporting API, но также выполняет запрос к API.
JavaScript
function makeApiCall() {
var apiQuery = gapi.client.analytics.data.ga.get({
'ids': TABLE_ID,
'start-date': '2010-01-01',
'end-date': '2010-01-15',
'metrics': 'ga:sessions',
'dimensions': 'ga:source,ga:keyword',
'sort': '-ga:sessions,ga:source',
'filters': 'ga:medium==organic',
'max-results': 25
});
// ...
}
В этом примере функция makeApiCall вызывается после загрузки клиентской библиотеки JavaScript. Внутри функция создает новый запрос API Google Analytics и сохраняет объект в переменной apiQuery .
Полный список всех параметров запроса и того, что они делают, можно найти в справочном руководстве по Core Reporting API . Кроме того, параметры измерения и показателя позволяют указать, какие данные следует получать из Google Analytics. Полный список можно найти на справочной странице параметров и показателей .
Выполнение запроса данных Core Reporting API
После определения запроса вы вызываете его метод execute , чтобы отправить запрос на серверы Google Analytics.
Джава
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();
Питон
try:
results = get_api_query(service).execute()
print_results(results)
except TypeError, error:
# Handle errors in constructing a query.
print ('There was an error in constructing your query : %s' % error)
except HttpError, error:
# Handle API service errors.
print ('There was an API error : %s : %s' %
(error.resp.status, error._get_reason()))
PHP
try {
$results = queryCoreReportingApi();
// Success. Do something cool!
} catch (apiServiceException $e) {
// Handle API service exceptions.
$error = $e->getMessage();
}
JavaScript
function makeApiCall() {
// ...
apiQuery.execute(handleCoreReportingResults);
}
function handleCoreReportingResults(results) {
if (!results.error) {
// Success. Do something cool!
} else {
alert('There was an error: ' + results.message);
}
}
Этот пример следует из предыдущего шага, где был создан запрос Core Reporting API. На этом этапе выполняется запрос. Параметр метода execute — это ссылка на функцию обратного вызова, которая будет выполнена после возврата данных из API.
Как только API возвращает результаты, выполняется функция обратного вызова, и ей передаются данные из API. Если произойдет ошибка, результаты будут содержать свойство с именем error .
В этом примере выполняется проверка на наличие error или успешность возврата API.
Если запрос прошел успешно, API вернет запрошенные данные. Если возникнут какие-либо ошибки, API вернет конкретный код состояния и сообщение с описанием ошибки. Все приложения должны правильно ловить и обрабатывать ошибки.
Работа с результатами API
Если запрос Core Reporting API был успешным, API возвращает данные отчетов Analytics, а также другую связанную информацию о данных.
Данные отчетов аналитики
Основные данные, возвращаемые API, можно рассматривать как таблицу с двумя основными типами данных:
- Заголовок, описывающий типы значений в каждом столбце.
- Строки данных в таблице
Данные заголовка столбца
Каждый ответ API содержит поле заголовка столбца, которое представляет информацию заголовка таблицы. Поле представляет собой список (или массив) объектов, где каждый объект описывает тип данных в столбце. Порядок столбцов — это столбцы измерений, за которыми следуют столбцы показателей в том же порядке, который указан в исходном запросе.
Джава
private void printColumnHeaders(GaData gaData) {
System.out.println("Column Headers:");
for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
System.out.println("Column Name: " + header.getName());
System.out.println("Column Type: " + header.getColumnType());
System.out.println("Column Data Type: " + header.getDataType());
}
}
Питон
def print_column_headers():
headers = results.get('columnHeaders')
for header in headers:
# Print Dimension or Metric name.
print 'Column name = %s' % header.get('name'))
print 'Column Type = %s' % header.get('columnType')
print 'Column Data Type = %s' % header.get('dataType')
PHP
private function printColumnHeaders(&results) {
$html = '';
$headers = $results->getColumnHeaders();
foreach ($headers as $header) {
$html .= <<<HTML
Column Name = {$header->getName()}
Column Type = {$header->getColumnType()}
Column Data Type = {$header->getDataType()}
HTML;
print $html;
}
JavaScript
function printColumnHeaders(results) {
var output = [];
for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
output.push(
'Name = ', header.name, '\n',
'Column Type = ', header.columnType, '\n',
'Data Type = ', header.dataType, '\n'
);
}
alert(output.join(''));
}
Данные ряда
Основные данные, возвращаемые API, возвращаются в виде двумерного List строк. Внешний список представляет все строки данных. Каждый внутренний список представляет собой одну строку, где порядок ячеек в строке такой же, как и поля в объекте заголовка столбца, описанном выше.
Поскольку данные в каждой ячейке возвращаются в виде строки, поле DataType в каждом объекте заголовка столбца особенно полезно, поскольку его можно использовать для анализа строковых значений в соответствующий тип. См. ответ API метаданных для всех возможных типов данных.
В следующих примерах печатаются как заголовки, так и строки таблицы.
Джава
private void printDataTable(GaData gaData) {
if (gaData.getTotalResults() > 0) {
System.out.println("Data Table:");
// Print the column names.
for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')');
}
System.out.println();
// Print the rows of data.
for (List<String> rowValues : gaData.getRows()) {
for (String value : rowValues) {
System.out.format("%-32s", value);
}
System.out.println();
}
} else {
System.out.println("No Results Found");
}
Питон
def print_data_table(results):
# Print headers.
output = []
for header in results.get('columnHeaders'):
output.append('%30s' % header.get('name'))
print ''.join(output)
# Print rows.
if results.get('rows', []):
for row in results.get('rows'):
output = []
for cell in row:
output.append('%30s' % cell)
print ''.join(output)
else:
print 'No Results Found'
PHP
private function printDataTable(&$results) {
if (count($results->getRows()) > 0) {
$table .= '<table>';
// Print headers.
$table .= '<tr>';
foreach ($results->getColumnHeaders() as $header) {
$table .= '<th>' . $header->name . '</th>';
}
$table .= '</tr>';
// Print table rows.
foreach ($results->getRows() as $row) {
$table .= '<tr>';
foreach ($row as $cell) {
$table .= '<td>'
. htmlspecialchars($cell, ENT_NOQUOTES)
. '</td>';
}
$table .= '</tr>';
}
$table .= '</table>';
} else {
$table .= '<p>No Results Found.</p>';
}
print $table;
}
JavaScript
function printRows(results) {
output = [];
if (results.rows && results.rows.length) {
var table = ['<table>'];
// Put headers in table.
table.push('<tr>');
for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
table.push('<th>', header.name, '</th>');
}
table.push('</tr>');
// Put cells in table.
for (var i = 0, row; row = results.rows[i]; ++i) {
table.push('<tr><td>', row.join('</td><td>'), '</td></tr>');
}
table.push('</table>');
output.push(table.join(''));
} else {
output.push('<p>No Results Found</p>');
}
alert(output.join(''));
}
Сообщить информацию
Помимо данных основной таблицы, данные, возвращаемые API, содержат некоторую информацию высокого уровня об ответе. Вы можете распечатать его, используя:
Джава
private void printResponseInfo(GaData gaData) {
System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData());
System.out.println("Kind: " + gaData.getKind());
System.out.println("ID:" + gaData.getId());
System.out.println("Self link: " + gaData.getSelfLink());
}
Питон
def print_response_info(results):
print 'Contains Sampled Data = %s' % results.get('containsSampledData')
print 'Kind = %s' % results.get('kind')
print 'ID = %s' % results.get('id')
print 'Self Link = %s' % results.get('selfLink')
PHP
private function printReportInfo(&$results) {
$html = <<<HTML
<pre>
Contains Sampled Data = {$results->getContainsSampledData()}
Kind = {$results->getKind()}
ID = {$results->getId()}
Self Link = {$results->getSelfLink()}
</pre>
HTML;
print $html;
}
JavaScript
function printReportInfo(results) {
var output = [];
output.push(
'Contains Sampled Data = ', results.containsSampledData, '\n',
'Kind = ', results.kind, '\n',
'ID = ', results.id, '\n',
'Self Link = ', results.selfLink, '\n');
alert(output.join(''));
}
Поле containsSampledData важно, поскольку оно описывает, была ли выборка ответа API. Выборка может повлиять на результаты ваших данных и является распространенной причиной того, что значения, возвращаемые API, не соответствуют веб-интерфейсу. Более подробную информацию см. в руководстве по концепции выборки .
Просмотр информации (профиля)
Каждый ответ содержит группу параметров, которые указывают учетную запись, веб-ресурс и представление (профиль), которым принадлежат эти данные.
Джава
private void printProfileInfo(GaData gaData) {
GaDataProfileInfo profileInfo = gaData.getProfileInfo();
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());
}
Питон
def print_profile_info(result):
info = results.get('profileInfo')
print 'Account Id = %s' % info.get('accountId')
print 'Web Property Id = %s' % info.get('webPropertyId')
print 'Web Property Id = %s' % info.get('internalWebPropertyId')
print 'View (Profile) Id = %s' % info.get('profileId')
print 'Table Id = %s' % info.get('tableId')
print 'View (Profile) Name = %s' % info.get('profileName')
PHP
private function printProfileInformation(&$results) {
$profileInfo = $results->getProfileInfo();
$html = <<<HTML
<pre>
Account ID = {$profileInfo->getAccountId()}
Web Property ID = {$profileInfo->getWebPropertyId()}
Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()}
Profile ID = {$profileInfo->getProfileId()}
Table ID = {$profileInfo->getTableId()}
Profile Name = {$profileInfo->getProfileName()}
</pre>
HTML;
print $html;
}
JavaScript
function printProfileInfo(results) {
var output = [];
var info = results.profileInfo;
output.push(
'Account Id = ', info.accountId, '\n',
'Web Property Id = ', info.webPropertyId, '\n',
'View (Profile) Id = ', info.profileId, '\n',
'Table Id = ', info.tableId, '\n',
'View (Profile) Name = ', info.profileName);
alert(output.join(''));
}
Каждый из этих идентификаторов соответствует различным объектам в иерархии Management API. Вы можете использовать эти идентификаторы для формирования запросов Management API для получения дополнительной информации о конфигурации представления (профиля). Например, вы можете запросить коллекцию целей Management API, чтобы узнать, какие цели активны, а также их настроенные имена целей.
Запросить информацию
Каждый ответ Core Reporting API содержит объект, содержащий все значения параметров запроса, использованные для создания ответа.
Джава
private void printQueryInfo(GaData gaData) {
GaDataQuery query = gaData.getQuery();
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
System.out.println("Dimensions: " + query.getDimensions());
System.out.println("Sort: " + query.getSort()); // List
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());
}
Питон
def print_query_info(results):
query = results.get('query')
for key, value in query.iteritems():
print '%s = %s' % (key, value)
PHP
private function printQueryParameters(&$results) {
$query = $results->getQuery();
$html = '<pre>';
foreach ($query as $paramName => $value) {
$html .= "$paramName = $value\n";
}
$html .= '</pre>';
print $html;
}
JavaScript
function printQuery(results) {
output = [];
for (var key in results.query) {
output.push(key, ' = ', results.query[key], '\n');
}
alert(output.join(''));
}
metrics и параметры sort возвращаются в виде значений в списке, а другие параметры — в виде строк.
Информация о страницах
Любой запрос Core Reporting API может соответствовать сотням тысяч строк данных Google Analytics. Core Reporting API будет возвращать только подмножество в определенный момент времени, которое можно назвать одной страницей данных. Поля нумерации страниц используются для получения всех страниц данных.
Джава
private void printPaginationInfo(GaData gaData) {
System.out.println("Items Per Page: " + gaData.getItemsPerPage());
System.out.println("Total Results: " + gaData.getTotalResults());
System.out.println("Previous Link: " + gaData.getPreviousLink());
System.out.println("Next Link: " + gaData.getNextLink());
}
Питон
def print_pagination_info(results):
print 'Items per page = %s' % results.get('itemsPerPage')
print 'Total Results = %s' % results.get('totalResults')
print 'Previous Link = %s' % results.get('previousLink')
print 'Next Link = %s' % results.get('nextLink')
PHP
private function getPaginationInfo(&$results) {
$html = <<<HTML
<pre>
Items per page = {$results->getItemsPerPage()}
Total results = {$results->getTotalResults()}
Previous Link = {$results->getPreviousLink()}
Next Link = {$results->getNextLink()}
</pre>
HTML;
print $html;
}
JavaScript
function printPaginationInfo(results) {
var output = [];
output.push(
'Items Per Page = ', results.itemsPerPage, '\n',
'Total Results = ', results.totalResults, '\n',
'Previous Link = ', results.previousLink, '\n',
'Next Link = ', results.nextLink, '\n');
alert(output.join(''));
}
Поле totalResults представляет общее количество строк данных, которым соответствует ваш запрос в Google Analytics. Это может быть больше, чем фактическое количество строк, возвращаемых на одной странице ответа. Поле itemsPerPage представляет количество строк, возвращаемых на этой странице.
Параметры previousLink и nextLink присутствуют только в том случае, если существует предыдущая или следующая страница. Проверьте эти ссылки, чтобы узнать, можно ли получить дополнительные страницы данных из Core Reporting API.
Итоги по всем результатам
Как упоминалось выше в разделе информации о разбивке на страницы , запрос к Core Reporting API может сопоставлять множество строк данных в Google Analytics, но возвращать только подмножество данных. Общие значения показателей для всех совпавших строк возвращаются в объекте totalsForAllResults . Эти данные полезны для расчета средних значений.
Джава
private void printTotalsForAllResults(GaData gaData) {
Map totalsMap = gaData.getTotalsForAllResults();
for (Map.Entry entry : totalsMap.entrySet()) {
System.out.println(entry.getKey() + " : " + entry.getValue());
}
}
Питон
def print_totals_for_all_results(results):
totals = results.get('totalsForAllResults')
for metric_name, metric_total in totals.iteritems():
print 'Metric Name = %s' % metric_name
print 'Metric Total = %s' % metric_total
PHP
private function printTotalsForAllResults(&$results) {
$totals = $results->getTotalsForAllResults();
foreach ($totals as $metricName => $metricTotal) {
$html .= "Metric Name = $metricName\n";
$html .= "Metric Total = $metricTotal";
}
print $html;
}
JavaScript
function printTotalsForAllResults(results) {
var output = [];
var totals = results.totalsForAllResults;
for (metricName in totals) {
output.push(
'Metric Name = ', metricName, '\n',
'Metric Total = ', totals[metricName], '\n');
}
alert(output.join(''));
}
Рабочие образцы
Чтобы увидеть полные рабочие примеры, ознакомьтесь с примером Core Reporting API в каталоге примеров каждой клиентской библиотеки.
Джава
Google API Клиентская библиотека Java Пример Core Reporting API
Питон
Google API Клиентская библиотека Python Пример Core Reporting API
PHP
Google API PHP-клиентская библиотека Пример Core Reporting API
JavaScript
Клиентская библиотека Google API JavaScript. Пример Core Reporting API.