Разрешения пользователя: руководство разработчика

В этой статье описываются основные принципы использования Management API для просмотра разрешений пользователей на доступ к аккаунтам, ресурсам и представлениям (профилям) Google Analytics, а также управления такими разрешениями.

Введение

Чтобы выводить список, создавать, редактировать и удалять пользователей своего аккаунта Google Analytics, вам потребуются разрешения в Management API. Например, они применяются для автоматического добавления или удаления нескольких пользователей в Google Analytics.

Подготовка к работе

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

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

В каждой библиотеке реализован один объект службы Google Analytics, который обеспечивает доступ ко всем данным Management API. Чтобы создать объект службы, обычно нужно выполнить следующие действия:

Зарегистрируйте приложение в Google Developers Console.
Разрешите доступ к Google Analytics.
Создайте объект службы Google Analytics.

Если вы не выполнили эти действия, перед продолжением прочитайте вводное руководство по Google Analytics API, в котором описывается, с чего нужно начинать создание приложения на его основе. Это поможет вам использовать Google Analytics API для работы с реальными приложениями.

Основные понятия

Иерархия аккаунта

В иерархии Google Analytics у авторизованного пользователя может быть несколько аккаунтов, в каждом из которых есть один или несколько ресурсов, в свою очередь содержащих несколько представлений (профилей).

Иерархия с аккаунтом верхнего уровня и двумя связанными с ним веб-ресурсами.На третьем уровне находится один профиль, связанный с крайним левым веб-ресурсом. С правым веб-ресурсом связано два профиля.Разрешения пользователей определяются на каждом из трех уровней. — Рис. 1. Иерархия аккаунта

Уровни разрешений

Пользователю Google Account могут назначаться различные уровни доступа к аккаунтам, ресурсам или представлениям (профилям).

Поддерживаемые уровни доступа:

MANAGE_USERS;
EDIT;
COLLABORATE;
READ_AND_ANALYZE.

Подробнее...

Унаследованные разрешения

Разрешение на редактирование (EDIT) на уровне аккаунта наследуется всеми его профилями и ресурсами. Разрешение на совместное использование (COLLABORATE) на уровне ресурса наследуют все принадлежащие ему профили.

Работа с разрешениями

В API используются локальные (local) и действующие (effective) разрешения. Первые применяются к фактическому аккаунту, ресурсу или представлению (профилю) и могут настраиваться. Разрешения effective наследуются от родительских ресурсов.

Извлечение разрешений для авторизованного пользова

Чтобы получить информацию о разрешениях для авторизованного пользователя, выполните операцию list или get в отношении ресурса Accounts, Webproperties или Profiles.

Чтобы выполнить эти операции, пользователь должен быть авторизован в любой из следующих областей доступа:

https://www.googleapis.com/auth/analytics.readonly
https://www.googleapis.com/auth/analytics

Разрешение на управление пользователями

Для просмотра разрешений пользователя в отношении аккаунтов, ресурсов и представлений (профилей) Google Analytics, а также управления этими разрешениями используются следующие ресурсы:

accountUserLinks – вывод списка, удаление, создание и обновление разрешений на уровне аккаунта.
webpropertyUserLinks – вывод списка, удаление, создание и обновление разрешений на уровне ресурса.
profileUserLinks – вывод списка, удаление, создание и обновление разрешений на уровне представления (профиля).

Для выполнения этих операций пользователь должен иметь разрешения уровня MANAGE_USERS и пройти авторизацию в следующей области доступа:

https://www.googleapis.com/auth/analytics.manage.users

Ограничения на количество пользовательских ссылок в аккаунте

Количество аккаунтов на одного пользователя для API не может превышать 100.

При попытке вызвать метод insert для пользователя со 100 аккаунтами возвращается ошибка.
Подробнее об общих квотах и ограничениях...

Примеры использования

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

Вывод списка всех пользователей аккаунта
Удаление пользователя из иерархии аккаунта
Обновление отдельного пользователя
Добавление отдельного пользователя

Вывод списка всех пользователей аккаунта

Чтобы вывести список всех пользователей аккаунта, включая тех, у кого есть разрешения на любые его ресурсы или представления (профили), выполните метод list ресурса accountUserLinks.

Примечание. Если разрешения предоставлены пользователю не в аккаунте, а на более глубоком уровне иерархии, его ресурс разрешений local может быть пустым.

Удаление пользователя из иерархии аккаунта

Чтобы удалить пользователя со всех уровней иерархии (аккаунт, ресурсы и представления (профили)), выполните следующие действия:

Получите все пользовательские ссылки для объектов каждого уровня.
Выполните три запроса list для аккаунта:
1. list для получения всех ресурсов accountUserLinks.
2. list для получения всех ресурсов webpropertyUserLinks (присвойте параметру webpropertyId значение ~all).
3. list для вывода всех ресурсов profileUserLinks (присвойте параметрам webpropertyId и profileId значения ~all).
Найдите и удалите всех пользователей с разрешениями local.
В отношении каждого ответа, полученного после выполнения трех операций на предыдущем шаге, проверьте все ресурсы entityUserLink:
- Если значения свойств userRef соответствуют пользователю и заданы разрешения local, то выполните операцию delete для ресурса.

В справочнике по API вы найдете подробное описание метода delete для ресурсов accountUserLinks, webpropertyUserLinks и profileUserLinks.

Обновление отдельного пользователя

С помощью Management API также можно обновлять разрешения пользователя. Например, если вам неизвестны название или идентификатор представления (профиля), чтобы изменить уровень разрешений с READ_AND_ANALYZE на EDIT, выполните следующие действия:

Получите все пользовательские ссылки для объектов каждого уровня.
Выполните три запроса list для аккаунта:
1. list для получения всех ресурсов accountUserLinks.
2. list для получения всех ресурсов webpropertyUserLinks (присвойте параметру webpropertyId значение ~all).
3. list для вывода всех ресурсов profileUserLinks (присвойте параметрам webpropertyId и profileId значения ~all).
Найдите и обновите пользователей с разрешениями local.
В отношении каждого ответа, полученного после выполнения трех операций на предыдущем шаге, проверьте все ресурсы entityUserLink:
- Если значения свойств userRef соответствуют пользователю и назначено разрешение local с уровнем READ_AND_ANALYZE, то выполните операцию update для ресурса.

В справочнике по API вы найдете подробное описание метода update для ресурсов accountUserLinks, webpropertyUserLinks и profileUserLinks.

Добавление отдельного пользователя

Чтобы добавить пользователя в иерархию аккаунта, например на уровне представления (профиля), выполните следующие действия:

С помощью Management API или веб-интерфейса получите идентификаторы аккаунта, ресурса и представления (профиля).
Выполните метод insert ресурса profileUserLinks.

В справочнике по API вы найдете подробное описание метода insert для ресурсов accountUserLinks, webpropertyUserLinks и profileUserLinks.

Пакетирование запросов

Пакетирование запросов на запись к API, связанных с разрешениями (удаление, добавление или обновление), имеет ряд преимуществ с точки зрения эффективности и действующих ограничений.

Пакетированные запросы подвергаются оптимизации на стороне сервера, что существенно повышает производительность.
30 пакетированных запросов API считаются одной операцией записи.
В одном пакетированном запросе могут содержаться до 300 запросов API, что увеличивает допустимое число запросов в секунду на пользователя.

Чтобы воспользоваться этими преимуществами, следуйте приведенным ниже рекомендациям:

Группируйте запросы к API по пользователям.
Пакетировать запросы следует только в рамках одного аккаунта. Если в запросах, связанных с разрешениями пользователей, указаны несколько аккаунтов Google Analytics, появится следующее сообщение об ошибке: All batched requests must be under the same account (Все пакетированные запросы должны быть в одном аккаунте).

Пример пакетирования: Python

Ниже приводится пример пакетирования на Python, в котором сгруппированы запросы на предоставление списку пользователей доступа к набору представлений (профилей). Для всех аккаунтов авторизованного пользователя создается один пакетированный запрос, в котором объединены все касающиеся этого пользователя изменения.