В этом руководстве описывается, как приложение авторизует запросы к Management API.
Авторизация запросов
Прежде чем пользователи смогут просматривать информацию о своей учетной записи на веб-сайте Google Analytics, они должны сначала войти в свои учетные записи Google. Точно так же, когда пользователи впервые получают доступ к вашему приложению, им необходимо авторизовать ваше приложение для доступа к своим данным.
Каждый запрос, отправляемый вашим приложением в Analytics API, должен включать токен авторизации. Токен также идентифицирует ваше приложение для Google.
О протоколах авторизации
Ваше приложение должно использовать OAuth 2.0 для авторизации запросов. Никакие другие протоколы авторизации не поддерживаются. Если ваше приложение использует Sign In With Google , некоторые аспекты авторизации выполняются за вас.
Авторизация запросов с помощью OAuth 2.0
Все запросы к Analytics API должны быть авторизованы пользователем, прошедшим проверку подлинности.
Детали процесса авторизации или «потока» для OAuth 2.0 несколько различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применяется ко всем типам приложений:
- Когда вы создаете свое приложение, вы регистрируете его с помощью Google API Console . Затем Google предоставляет информацию, которая понадобится вам позже, например идентификатор клиента и секрет клиента.
- Активируйте Analytics API в Google API Console. (Если API не указан в консоли API, пропустите этот шаг.)
- Когда вашему приложению требуется доступ к пользовательским данным, оно запрашивает у Google определенную область доступа.
- Google отображает пользователю экран согласия , предлагая ему разрешить вашему приложению запрашивать некоторые из его данных.
- Если пользователь одобряет, Google предоставляет вашему приложению краткосрочный токен доступа .
- Ваше приложение запрашивает данные пользователя, прикрепляя к запросу токен доступа.
- Если Google определяет, что ваш запрос и токен действительны, он возвращает запрошенные данные.
Некоторые потоки включают дополнительные шаги, например использование маркеров обновления для получения новых маркеров доступа. Подробную информацию о потоках для различных типов приложений см. в документации Google по OAuth 2.0 .
Вот информация об области действия OAuth 2.0 для Analytics API:
| Сфера | Значение |
|---|---|
https://www.googleapis.com/auth/analytics.readonly | Доступ только для чтения к Analytics API. |
https://www.googleapis.com/auth/analytics.edit | Изменить объекты управления Google Analytics. |
https://www.googleapis.com/auth/analytics.manage.users | Просмотр и управление разрешениями пользователей для учетных записей Google Analytics. |
https://www.googleapis.com/auth/analytics.manage.users.readonly | Просмотр разрешений пользователей Google Analytics. |
Чтобы запросить доступ с помощью OAuth 2.0, вашему приложению требуется информация о области, а также информация, которую Google предоставляет при регистрации вашего приложения (например, идентификатор клиента и секрет клиента).
Совет . Клиентские библиотеки API Google могут выполнить часть процесса авторизации за вас. Они доступны для различных языков программирования; проверьте страницу с библиотеками и примерами для более подробной информации.
Общие потоки OAuth 2.0
Ниже перечислены распространенные варианты использования для конкретных потоков OAuth 2.0.
Веб сервер
Этот поток хорош для автоматического, автономного или запланированного доступа к данным Google Analytics пользователя.
Пример:
- Автоматическое обновление пользовательских панелей с последними данными Google Analytics.
Сторона клиента
Этот поток идеально подходит для приложений, когда пользователи напрямую взаимодействуют с приложением для доступа к своим данным Google Analytics в браузере. Это устраняет необходимость в возможностях на стороне сервера, но делает автоматические, автономные или запланированные отчеты непрактичными.
Пример:
- Браузерный инструмент отчетности, такой как Analytics Query Explorer .
Установленные приложения
Этот поток предназначен для приложений, которые распространяются в виде пакета и устанавливаются пользователем. Этот поток требует, чтобы приложение или пользователь имели доступ к браузеру для завершения потока проверки подлинности.
Примеры:
- Виджет рабочего стола на ПК или Mac.
- Плагин для системы управления контентом. Преимущество этого потока по сравнению с веб-сервером или на стороне клиента заключается в том, что для вашего приложения можно использовать один проект консоли API. Это позволяет составлять сводные отчеты и упрощает установку для пользователей.
Сервисные аккаунты
Служебные учетные записи полезны для автоматического, автономного или запланированного доступа к данным Google Analytics для вашей собственной учетной записи. Например, чтобы создать живую информационную панель из ваших собственных данных Google Analytics и поделиться ею с другими пользователями.
Чтобы приступить к работе с Analytics API, вам необходимо сначала использовать инструмент настройки , который поможет вам создать проект в Google API Console, включить API и создать учетные данные.
Чтобы настроить новую учетную запись службы, выполните следующие действия:
- Щелкните Создать учетные данные > Ключ служебной учетной записи .
- Выберите, загружать ли открытый/закрытый ключ сервисного аккаунта в виде стандартного файла P12 или в виде файла JSON, который может быть загружен клиентской библиотекой Google API.
Ваша новая пара открытый/закрытый ключ будет сгенерирована и загружена на ваш компьютер; он служит единственной копией этого ключа. Вы несете ответственность за его безопасное хранение.
Исправление проблем
Ваша авторизация не проходит в следующих ситуациях:
Вы получите код состояния
401, если срок действия вашегоaccess_tokenистек или если вы используете неправильную область действия для API.Вы получите код состояния
403, если авторизованный пользователь не имеет доступа к представлению (профилю). Убедитесь, что вы авторизованы с правильным пользователем и что у него действительно есть выбранное вами представление (профиль).
Игровая площадка OAuth 2.0
Этот инструмент позволяет пройти весь процесс авторизации через веб-интерфейс. Инструмент также отображает все заголовки HTTP-запросов, необходимые для выполнения авторизованного запроса. Если вы не можете получить авторизацию для работы в своем собственном приложении, попробуйте заставить его работать через игровую площадку OAuth 2.0. Затем вы можете сравнить заголовки HTTP и запрос из игровой площадки с тем, что ваше приложение отправляет в Google Analytics. Эта проверка — простой способ убедиться, что вы правильно форматируете запросы.
Недействительный грант
Когда вы пытаетесь использовать токен обновления, следующее возвращает вам ошибку invalid_grant :
- Часы вашего сервера не синхронизированы с сетевым протоколом времени - NTP .
- Превышен лимит токена обновления.
Приложения могут запрашивать несколько токенов обновления для доступа к одной учетной записи Google Analytics.
Например, если пользователь хочет установить приложение на несколько компьютеров и получить доступ к одной и той же учетной записи Google Analytics, для каждого компьютера потребуется отдельный токен. Когда количество токенов обновления превышает лимит, старые токены становятся недействительными. Если приложение пытается использовать недействительный токен обновления, возвращается сообщение об ошибке invalid_grant .
Ограничение для каждой уникальной пары клиента OAuth 2.0 и аккаунта Google Analytics составляет 25 токенов обновления . Если приложение продолжает запрашивать токены обновления для той же пары «Клиент/Учетная запись», после выдачи 26-го токена первый токен обновления, который был выпущен ранее, станет недействительным. 27-й запрошенный токен обновления сделает недействительным 2-й ранее выпущенный токен и так далее.