Core Reporting API — руководство для разработчиков

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

В этом документе объясняется, как использовать Core Reporting API для доступа к данным Google Analytics.

Введение

Core Reporting API обеспечивает доступ к табличным данным в стандартных и пользовательских отчетах Google Analytics. Чтобы получить доступ к данным, вы создаете запрос, который указывает: представление (профиль), даты начала и окончания, а также измерения и показатели, составляющие заголовки столбцов в таблице. Этот запрос отправляется в Core Reporting API, и Core Reporting API возвращает все данные в виде таблицы.

Если вы новичок в API, прочтите обзор Core Reporting API , чтобы ознакомиться с назначением Core Reporting API и данными, которые он предоставляет.

Прежде чем вы начнете

В этом руководстве показано, как получить доступ к Google Analytics API с помощью языков программирования Java, Python, PHP и JavaScript.

  • Полный список клиентских библиотек для конкретных языков программирования, которые работают с API, см. на странице клиентских библиотек.
  • Прочтите Справочное руководство , чтобы получить доступ к API без клиентской библиотеки.

Каждая клиентская библиотека предоставляет один объект службы аналитики для доступа ко всем данным Core Reporting API. Для создания объекта службы обычно необходимо выполнить следующие шаги:

  1. Зарегистрируйте свое приложение в Google API Console .
  2. Разрешите доступ к данным Google Analytics.
  3. Создайте объект службы 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 API Google. После загрузки loadLib для загрузки класса службы аналитики. После завершения объект gapi.client.analytics должен существовать в DOM и быть готовым к использованию для запросов к Core Reporting API.

Создав объект службы аналитики, вы готовы делать запросы к Core Reporting API.

Примечание . Объект службы аналитики также можно использовать для доступа к Management API .

Обзор

Приложение, использующее Core Reporting API, обычно выполняет 2 шага:

  • Запрос к Core Reporting API
  • Работа с результатами API

Давайте посмотрим на оба шага.

Запрос к Core Reporting API

Создайте запрос Core Reporting 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 в каталоге образцов каждой клиентской библиотеки.