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

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

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

Введение

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

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

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

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

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

  1. Зарегистрируйте свое приложение в Google API Console .
  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-адреса; ему не нужна кодировка.

Следующие фрагменты кода иллюстрируют, как установить ключ 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 , которое включает подмножество атрибутов, применимых к столбцу.

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

Сценарии использования

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

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

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

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

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

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

В следующем фрагменте показано, как использовать атрибут 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;
}

Добавлено в версию 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 для кэшированного ресурса, то кэшированная версия является текущей. Если ETag не эквивалентны, обновите приложение и обновите кеш последним ответом.

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

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

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