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