В этой статье описываются основные принципы использования Metadata API для доступа к списку столбцов Google Analytics и их атрибутам.
Введение
Metadata API возвращает список столбцов (параметры и показатели), которые доступны в API Google Analytics для отчетности, а также их атрибуты. Если вы ещё не знакомы с Metadata API, изучите этот раздел.
Подготовка к работе
Доступ ко всем Google Analytics API осуществляется одинаково. Прежде чем начать работу с Metadata API, ознакомьтесь со следующими материалами:
- Клиентские библиотеки. На этой странице представлены клиентские библиотеки для всех языков программирования, которые поддерживает этот API.
- Справочное руководство по интерфейсу API и доступу к данным без использования клиентских библиотек.
В каждой библиотеке реализован один объект службы Google Analytics, который обеспечивает доступ ко всем данным Metadata API. Чтобы создать объект службы, обычно нужно выполнить следующие действия:
- Зарегистрируйте приложение в Google API Console.
- Создайте объект службы Google Analytics и задайте ключ API.
Регистрация и ключ API
В каждом запросе к Analytics API ваше приложение должно идентифицироваться с помощью ключа API.
Получение и использование ключа API
Чтобы получить ключ API, выполните следующие действия:
- Откройте раздел Учетные данные в API Console.
-
В этом 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 могут потребоваться в следующих случаях:
- Неподдерживаемые столбцы
- Названия столбцов
- Шаблонные столбцы
- Рассчитываемые столбцы
- Столбцы и сегменты
- Версии API
- Etag
Неподдерживаемые столбцы
Атрибуту 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
(если версия в кеше актуальна).