API метаданных — Руководство разработчика

В этом документе объясняются важные понятия об использовании API метаданных для доступа к списку и атрибутам столбцов Google Analytics.

Введение

API метаданных возвращает список столбцов (т. е. параметров и показателей), представленных в API отчетов Google Analytics, и их атрибуты. Если вы новичок в API, ознакомьтесь с обзором API метаданных , чтобы познакомиться с API метаданных.

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

Доступ ко всем API Google Analytics осуществляется одинаковым образом. Прежде чем начать работу с API метаданных, вам необходимо:

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

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

1. Зарегистрируйте свое приложение в консоли Google API .
2. Создайте объект службы Analytics и установите ключ API .

Регистрация и ключ API

Ваше приложение должно идентифицировать себя каждый раз, когда оно отправляет запрос к Analytics API, включая ключ API в каждый запрос.

Получение и использование ключа API

Чтобы получить ключ API:

1. Откройте страницу «Учетные данные» в консоли API.
2. Этот API поддерживает два типа учетных данных. Создайте учетные данные, подходящие для вашего проекта:

   • OAuth 2.0: всякий раз, когда ваше приложение запрашивает личные данные пользователя, оно должно отправить токен OAuth 2.0 вместе с запросом. Ваше приложение сначала отправляет идентификатор клиента и, возможно, секрет клиента для получения токена. Вы можете создать учетные данные OAuth 2.0 для веб-приложений, учетных записей служб или установленных приложений.

     Примечание. Поскольку в этом API нет методов, требующих авторизации OAuth 2.0, вам может потребоваться только получить ключи API , которые описаны ниже. Однако если ваше приложение вызывает другие API, требующие авторизации пользователя, вам все равно понадобятся учетные данные OAuth 2.0.

     Дополнительную информацию см. в документации OAuth 2.0 .

   • Ключи API. Запрос, который не предоставляет токен OAuth 2.0, должен отправить ключ API. Ключ идентифицирует ваш проект и обеспечивает доступ к API, квоту и отчеты.

     API поддерживает несколько типов ограничений для ключей API. Если нужный вам ключ API еще не существует, создайте ключ API в консоли, нажав Создать учетные данные > Ключ API . Вы можете ограничить ключ перед его использованием в рабочей среде, нажав «Ограничить ключ» и выбрав одно из «Ограничений» .

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

После того, как у вас есть ключ API, ваше приложение может добавить параметр запроса key= yourAPIKey ко всем URL-адресам запроса.

Ключ API можно безопасно встраивать в URL-адреса; ему не нужна никакая кодировка.

Примечание . Если ваше приложение уже аутентифицировало и авторизовало пользователя (например, с помощью OAuth 2.0), то любой запрос, который вы делаете к API метаданных с использованием авторизованного объекта службы Analytics, автоматически идентифицирует ваше приложение. В этом случае вам не нужно устанавливать ключ API .

Следующие фрагменты кода иллюстрируют, как установить ключ API для различных клиентских библиотек:

Джава

import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;

import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;

public class ApiKeySample {
  private static final String API_KEY = "YOUR API KEY";

  public static void main(String[] args) {
    NetHttpTransport netHttpTransport = new NetHttpTransport();
    JacksonFactory jacksonFactory = new JacksonFactory();

    // Set the API Key
    AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);

    // Build the Analytics Service object
    Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
        .setAnalyticsRequestInitializer(analyticsInitializer)
        .setApplicationName("ApiKeySample")
        .build();

    // Start coding cool things.
  }
}

Питон

from apiclient.discovery import build

API_KEY = 'YOUR API KEY'

def main(argv):
  # Set the API Key and build the Analytics service object.
  service = build('analytics', 'v3', developerKey=API_KEY)

  # Start coding cool things.

PHP

require_once 'google-api-php-client/src/Google_Client.php';
require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php';

const API_KEY = 'YOUR API KEY'

$client = new Google_Client();

// Set the API Key
$client->setDeveloperKey($API_KEY);

// Build the Analytics Service object.
$analytics = new google_AnalyticsService($client);

// Start coding cool things.

JavaScript

<!--
  Method 1:
  Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';

function handleClientLoad() {
  gapi.client.setApiKey(apiKey);
  gapi.client.load('analytics', 'v3', makeRequest);
}

function makeRequest() {
  // Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>


<!--
  Method 2:
  Using REST and callback parameter
-->
<script>
function render() {
  // Place your awesome code here.
}
</script>

<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>

Атрибуты столбца

Ответ API метаданных включает свойство attributeNames , в котором перечислены все допустимые атрибуты столбца. Каждый столбец имеет свойство attributes , которое включает подмножество атрибутов, применимых к столбцу.

В следующей таблице приведен полный список допустимых атрибутов:

** Атрибут appUiName устарел. Вам следует удалить весь код, использующий атрибут appUiName , и использовать только атрибут uiName . Подробную информацию об удалении атрибутов см. в Политике устаревания данных .

Случаи использования

API метаданных можно использовать для решения следующих случаев:

• Устаревшие столбцы
• Имена столбцов
• Шаблонизированные столбцы
• Вычисляемые столбцы
• Столбцы и сегменты
• Версии API
• Этаги

Устаревшие столбцы

Если столбец (т. е. параметр или показатель) устарел, его атрибуту status будет присвоено значение DEPRECATED .

Примечание . Ваше приложение должно проверить и прекратить использование DEPRECATED столбцов в запросах API отчетов. Если имеется запасная колонка, ее следует использовать вместо нее. Столбцы DEPRECATED будут удалены из API отчетов и метаданных после окончания периода устаревания , а запросы к этим столбцам будут возвращать ошибку.

В следующем фрагменте показано, как использовать атрибут status , чтобы проверить, устарел ли столбец:

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

Если столбец переименован/удален, его атрибуту status будет присвоено DEPRECATED , а атрибут replacedBy может быть установлен на Id замещающего столбца.

В следующем фрагменте показано, как использовать атрибут replacedBy для получения идентификатора замещающего столбца:

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

Имена столбцов

Атрибут uiName — это имя измерения или показателя, которое используется в пользовательских интерфейсах Google Analytics (например, в веб-интерфейсе).

Атрибут appUiName устарел. Вам следует удалить весь код, использующий атрибут appUiName , и использовать только атрибут uiName . Подробную информацию об удалении атрибутов см. в Политике устаревания данных .

В следующем фрагменте показано, как получить имя столбца в пользовательском интерфейсе:

function getColumnName(column) {
  return column.attributes.uiName;
}

Шаблонизированные столбцы

Шаблонизированные столбцы включают параметры или показатели с числовым индексом. Например, ga:goalXXStarts , ga:dimensionXX , ga:metricXX и т. д. Шаблонизированный столбец будет иметь атрибуты minTemplateIndex и maxTemplateIndex , которые определяют диапазон индекса.

В следующем фрагменте показано, как проверить, шаблонизирован ли столбец:

function isTemplatized(column) {
  return !!column.attributes.minTemplateIndex ||
         !!column.attributes.maxTemplateIndex;
}

В следующем фрагменте показано, как получить список допустимых идентификаторов для шаблонного столбца:

function getTemplatizedIdList(column) {
  var columnIdList = [];
  var columnId = column.id;

  if (isTemplatized(column)) {
    minIndex = parseInt(column.attributes.minTemplateIndex);
    maxIndex = parseInt(column.attributes.maxTemplateIndex);

    for (var i = minIndex; i <= maxIndex; i++) {
      columnIdList.push(columnId.replace('XX', i));
    }
  }
  return columnIdList;
}

Вычисляемые столбцы

Столбец, полученный на основе вычислений других столбцов, будет иметь атрибут calculation . Например, расчет для ga:percentNewSessions выглядит так ga:newSessions / ga:sessions .

В следующем примере показано, как проверить, рассчитан ли столбец, и как получить расчет для столбца:

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

Столбцы и сегменты

allowedInSegments позволяет проверить, можно ли использовать столбец в параметре запроса сегмента.

В следующем примере показано, как определить, можно ли использовать столбец в сегментах:

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

Добавлено в версию API

Используйте атрибут addedInApiVersion , чтобы проверить, можно ли использовать столбец в API отчетов указанной версии. Например, вызовите следующую функцию, чтобы убедиться, что столбец можно использовать в Core Reporting API V3 :

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

ETag

ETag включается в каждый ответ API метаданных. ETag — это идентификатор, который можно использовать для кэширования и обновления ответов API метаданных. Это важно, поскольку данные столбцов (т. е. измерений и показателей) могут оставаться неизменными в течение длительного периода времени, и неэффективно выполнять ненужные запросы и обновления, когда можно использовать кэшированные данные.

Если вы храните ETag коллекции столбцов, его можно в основном использовать двумя способами: проверить актуальность кэшированного ответа API метаданных и включить его как часть запроса API метаданных.

Проверка кэшированного ответа

Если вы сравните значение ETag, возвращенное из ответа API метаданных, и оно эквивалентно ETag для кэшированного ресурса, то кэшированная версия является текущей. Если ETags не эквивалентны, обновите приложение и обновите кеш последним ответом.

Если вы хотите получить только значение ETag из API метаданных, установите для параметра запроса полей значение etag при выполнении запроса. См. пример .

Использование ETag с запросом API

Если у вас есть кэшированная версия коллекции столбцов, вы можете включить ее значение ETag в запрос API метаданных, установив поле HTTP-заголовка If-None-Match . API метаданных проверит значение ETag и либо ответит обновленной версией ресурса и статусом HTTP 200 OK , либо пустым ответом со статусом 304 Not Modified если ваша кэшированная версия актуальна.

Примечание . Клиентская библиотека, которую вы используете для выполнения запросов к API метаданных, может распознавать и использовать ETag или предоставлять для этого поддержку. Вам следует просмотреть документацию библиотеки, чтобы убедиться, доступна ли поддержка ETag.