Metadata API: руководство для разработчиков

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

Введение

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

Подготовка к работе

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

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

В каждой библиотеке реализован один объект службы Google Analytics, который обеспечивает доступ ко всем данным Metadata API. Чтобы создать объект службы, обычно нужно выполнить следующие действия:

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

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

В каждом запросе к Analytics API ваше приложение должно идентифицироваться с помощью ключа API.

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

Чтобы получить ключ API, выполните следующие действия:

  1. Откройте раздел Учетные данные в API Console.
  2. В этом API поддерживаются учетные данные двух типов:
    • OAuth 2.0. Когда приложение запрашивает конфиденциальные данные пользователя, вместе с запросом оно должно отправить токен OAuth 2.0. Чтобы получить его, приложение сначала отправляет идентификатор клиента и, возможно, секретный код клиента. Учетные данные OAuth 2.0 можно создавать для веб-приложений, сервисных аккаунтов и установленных приложений.

      Подробнее…

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

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

Рекомендации по безопасной работе с ключами API

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

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

Далее показано, как задавать ключ API при работе с различными клиентскими библиотеками:

Java

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.
  }
}

Python

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>

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

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

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

Примеры использования

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

Неподдерживаемые столбцы

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

Следующий код проверяет атрибут status столбца:

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

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

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

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

Названия столбцов

В атрибуте uiName указывается название параметра или показателя, которое используется в интерфейсе Google Analytics.

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

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

Атрибут addedInApiVersion

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

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

ETag

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

ETag, хранящийся в коллекции столбцов, можно использовать для проверки актуальности кешированного ответа Metadata API, а также в составе запроса к Metadata API.

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

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

Чтобы получить из Metadata API только значение ETag, присвойте параметру запроса fields значение etag. Пример.

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

Если у вас есть кешированная версия коллекции столбцов, вы можете включать в запросы к Metadata API соответствующее значение ETag с помощью поля HTTP-заголовка If-None-Match. После проверки Metadata API возвращает обновленную версию со статусом HTTP 200 OK или пустой ответ со статусом 304 Не изменено (если версия в кеше актуальна).