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, которые требуют авторизации пользователя, вам потребуются учетные данные 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 Not Modified (если версия в кеше актуальна).