Управление доступом

С помощью Google Analytics Management API можно программно управлять разрешениями пользователей. Этот инструмент будет особенно полезен большим кампаниям с частым внесением изменений в списки контроля доступа.

Введение

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

Кроме того, поддерживается специальное пакетирование запросов для операций записи разрешений.

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

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

  • MANAGE_USERS – позволяет выполнять запросы на запись к API разрешений пользователей;
  • EDIT – позволяет изменять ресурсы управления данными;
  • COLLABORATE;
  • READ_AND_ANALYZE.

Подробнее о каждом уровне доступа читайте в этой статье Справочного центра.

Предоставление разрешений

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

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

Разрешение на редактирование (EDIT) на уровне аккаунта наследуется всеми его профилями и ресурсами. Это отражает ресурс permissions.effective.

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

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

Получение списка всех пользователей аккаунта

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

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

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

  1. Получите все пользовательские ссылки для аккаунта.
    • Для этого примените метод list ко всем объектам accountUserLinks.
  2. Создайте запросы на изменение для всех пользователей с соответствующими разрешениями.
    • Для этого примените метод update ко всем объектам accountUserLink.
  3. Создайте пакетированный запрос для каждых 300 пользователей с запросами на изменение из предыдущего пункта.
    • Для этого примените метод batch для каждых 300 пользователей.

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

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

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

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

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

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

  1. Получите все пользовательские ссылки для объектов каждого уровня. Выполните три запроса list для аккаунта:

    • list – для вывода всех объектов accountUserLinks.
    • list – для вывода всех объектов webpropertyUserLinks (присвойте параметру webpropertyId значение ~all).
    • list – для вывода всех объектов profileUserLinks (присвойте параметрам webpropertyId и profileId значения ~all).
  2. Найдите и обновите список пользователей с разрешениями local. Для каждого ответа, полученного после выполнения трех операций list на предыдущем шаге, проверьте все ресурсы entityUserLink:

    • Если значения свойств userRef соответствуют пользователю и предоставлены разрешения local с уровнем READ_AND_ANALYZE, то выполните операцию update для объекта.

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

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

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

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

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

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

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

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

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

Обработка ошибок

Все запросы, входящие в пакетированный запрос, обрабатываются как одна транзакция. Это значит, что если хоть один из них содержит ошибку, изменения внесены не будут. Такой механизм используется по следующим причинам:

  • Чтобы отредактировать разрешения одного пользователя, может потребоваться внести несколько изменений. Если одно изменение содержит ошибку, выполнение остальных может привести к нежелательным последствиям.
  • Обрабатывая изменения как одну транзакцию, мы оптимизируем трафик и снижаем риск превысить квоту для вызова.

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

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

"""Простой пример пакетированного запроса, связанного с разрешениями пользователей Google Analytics."""
import json
from apiclient.errors import HttpError
from apiclient.http import BatchHttpRequest

def call_back(request_id, response, exception):
  """Обработка ответов на пакетированный запрос."""
  print request_id
  if exception is not None:
    if isinstance(exception, HttpError):
      message = json.loads(exception.content)['error']['message']
      print ('Request %s returned API error : %s : %s ' %
             (request_id, exception.resp.status, message))
  else:
    print response


def add_users(users, permissions):
  """Добавление пользователей ко всем представлениям (профилям) с заданными разрешениями.

  Аргументы:
    users: список адресов электронной почты пользователей;
    permissions: список пользовательских разрешений.
  Примечание. Применение этого кода предполагает наличие разрешений уровня MANAGE_USERS
  для каждого профиля, а также авторизованного объекта службы Analytics.
  """

  # Получить полный набора сводок по аккаунтам.
  account_summaries = analytics.management().accountSummaries().list().execute()

  # Перебор всех аккаунтов.
  for account in account_summaries.get('items', []):
    account_id = account.get('id')

    # Перебор всех пользователей.
    for user in users:
      # Создание объекта BatchHttpRequest.
      batch = BatchHttpRequest(callback=call_back)

      # Перебор всех ресурсов.
      for property_summary in account.get('webProperties', []):
        property_id = property_summary.get('id')

        # Перебор всех представлений (профилей).
        for view in property_summary.get('profiles', []):
          view_id = view.get('id')

          # Создание ссылки на профиль пользователя.
          link = analytics.management().profileUserLinks().insert(
              accountId=account_id,
              webPropertyId=property_id,
              profileId=view_id,
              body={
                  'permissions': {
                      'local': permissions
                  },
                  'userRef': {
                      'email': user
                  }
              }
          )
          batch.add(link)

      # Выполнение пакетированного запроса для каждого пользователя.
      batch.execute()

if __name__ == '__main__':

  # Создание списка пользователей.
  emails = ['ona@gmail.com', 'emi@gmail.com', 'sue@gmail.com', 'liz@gmail.com']

  # Вызов функции add_users со списком требуемых разрешений.
  add_users(emails, ['READ_AND_ANALYZE'])

Дополнительная информация

Из следующей статьи вы узнаете, как настраивать различные ресурсы данных при помощи Google Analytics Management API.