用户管理

利用 Google Analytics(分析)Management API,您可以通过编程对用户权限进行管理。这对于经常更新访问控制列表的大型企业非常有用。

简介

共有三种主要的资源可用于控制哪些用户可以访问帐户、媒体资源或数据视图(配置文件):

另外,还针对用户权限写入操作,提供了特殊的批量处理支持。

用户权限

可将 Google Analytics(分析)帐户、媒体资源或数据视图(配置文件)的以下访问权限级别授予用户(由 Google 帐户代表相应用户):

  • MANAGE_USERS - 向用户权限 API 发出写入请求所需的访问权限级别。
  • EDIT - 修改数据管理资源所需的访问权限级别。
  • COLLABORATE
  • READ_AND_ANALYZE

有关各个访问权限级别的更多详细信息,请参阅帮助中心内的用户权限一文。

分配权限

API 提供两类权限:localeffective。Local 权限适用于指定的帐户、媒体资源或数据视图(配置文件)。利用 API 分配权限时,您应使用 permissions.local 属性Effective 权限表示从父级资源继承下来的权限。

继承权限

如果对用户授予了帐户的 EDIT 权限,则此帐户下的所有配置文件和媒体资源都将继承该权限;这种情况将由 permissions.effective 属性来表示。

使用情形

Management API 中的用户权限可用来应对以下使用情形:

列出帐户的所有用户

要列出帐户的所有用户,包括所有对帐户中的任何媒体资源或数据视图(配置文件)拥有权限的用户,您只需要执行 accountUserLinks 资源的 list 方法。

更新大量用户

要更新大量用户的权限,强烈建议您使用批量处理;这不仅能节省配额,而且非常高效 -- 请参见下文的批量处理部分,了解完整的详情。对帐户完成这一操作所需执行的步骤如下:

  1. 获取帐户的所有用户关联
    • list 所有 accountUserLinks
  2. 针对每个用户构造更新请求,其中包含适当的权限
    • 针对每个 accountUserLink 构造 update
  3. 针对每 300 个用户,构造一个包含上述更新请求的批量处理请求
    • 对每 300 个用户调用 batch

从帐户层级结构中移除某个用户

从帐户层级结构(即:帐户、媒体资源和数据视图(配置文件))中彻底移除某个用户。完成这一操作所需要的步骤如下:

  1. 获取每个实体级别的所有用户关联。 对帐户执行 3 次 list 请求:
    • list 所有 accountUserLinks
    • 通过将 webpropertyId 参数设置为 ~alllist 所有 webpropertyUserLinks
    • 通过将 webpropertyIdprofileId 参数设置为 ~alllist 所有 profileUserLinks
  2. 查找并删除有 local 权限的用户。 对于从第 1 步的 3 次 list 操作中得到的每个响应,遍历每个 entityUserLink
    • 如果 userRef 属性与用户匹配,并且设置了 local 权限,则对该资源执行 delete 操作

请参阅 API 参考,详细了解“帐户用户关联”、“网络媒体资源用户关联”和“数据视图(配置文件)用户关联”资源的 delete 方法。

更新单个用户

您还可以利用 Management API 来更新用户权限。例如,将用户权限级别从 READ_AND_ANALYZE 更改为 EDIT 的步骤如下(假设您不知道数据视图(配置文件)的名称或 ID):

  1. 获取每个实体级别的所有用户关联。对帐户执行 3 次 list 请求:

    • list 所有 accountUserLinks
    • 通过将 webpropertyId 参数设置为 ~alllist 所有 webpropertyUserLinks
    • 通过将 webpropertyIdprofileId 参数设置为 ~alllist 所有 profileUserLinks
  2. 查找并更新有 local 权限的用户。 对于从第 1 步的 3 次 list 操作中得到的每个响应,遍历每个 entityUserLink

    • 如果 userRef 属性与用户匹配,并且用户拥有带 READ_AND_ANALYZE 访问权限的 local 权限,则对该资源执行 update 操作。

请参阅 API 参考,详细了解“帐户用户关联”、“网络媒体资源用户关联”和“数据视图(配置文件)用户关联”资源的 update 方法。

添加单个用户

要向帐户层级结构添加用户,例如向某个数据视图(配置文件)添加用户,需要完成以下步骤:

  1. 使用 Management API 或网页界面获取帐户、媒体资源和数据视图(配置文件)的 ID。
  2. 通过执行 profileUserLinks 资源的 insert 方法添加用户。

批量处理

批量处理方式发送用户权限 API 写入(删除、插入、更新)请求可以提升性能和获得配额奖励。

  • 批量发送用户权限请求可以发挥后台优化的优势,并获得显著的性能提升。
  • 每 30 个批量用户权限 API 请求仅计为一个写入操作
  • 每个批量请求可以发送多达 300 个用户权限 API 请求,允许您使用更高的每秒查询次数每用户限额

要以这种方式最大程度地提升性能,您需要进行以下操作。

  • 将您的 API 请求按用户分组。
  • 在批量请求中仅包含针对同一帐户的请求。使用多个 Google Analytics(分析)帐户的批量用户权限请求会导致出错,错误信息为:All batched requests must be under the same account

错误处理

批量请求中的所有权限调用均计为一次事务。也就是说,如果有任何转变出错,都不会进行更改。我们将其计为一次调用的原因如下:

  • 调整单个用户的权限可能需要进行多次修改。如果有一次修改出错,提交部分批处理会导致该用户的权限出现异常状态。
  • 将所有修改计为一次事务,可优化流量,减少该调用所需的配额。

批处理示例 - Python

下面是一个简单的 Python 示例,将会显示如何批量处理将一个用户列表添加到一组数据视图(配置文件)的请求。该示例循环处理授权用户的帐户,为每个帐户创建一个批处理请求。在每个批处理请求中,包含了针对指定用户的所有更改操作。

"""A simple example of Google Analytics batched user permissions."""
import json
from apiclient.errors import HttpError
from apiclient.http import BatchHttpRequest

def call_back(request_id, response, exception):
  """Handle batched request responses."""
  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):
  """Adds users to every view (profile) with the given permissions.

  Args:
    users: A list of user email addresses.
    permissions: A list of user permissions.
  Note: this code assumes you have MANAGE_USERS level permissions
  to each profile and an authorized Google Analytics service object.
  """

  # Get the a full set of account summaries.
  account_summaries = analytics.management().accountSummaries().list().execute()

  # Loop through each account.
  for account in account_summaries.get('items', []):
    account_id = account.get('id')

    # Loop through each user.
    for user in users:
      # Create the BatchHttpRequest object.
      batch = BatchHttpRequest(callback=call_back)

      # Loop through each property.
      for property_summary in account.get('webProperties', []):
        property_id = property_summary.get('id')

        # Loop through each view (profile).
        for view in property_summary.get('profiles', []):
          view_id = view.get('id')

          # Construct the Profile User Link.
          link = analytics.management().profileUserLinks().insert(
              accountId=account_id,
              webPropertyId=property_id,
              profileId=view_id,
              body={
                  'permissions': {
                      'local': permissions
                  },
                  'userRef': {
                      'email': user
                  }
              }
          )
          batch.add(link)

      # Execute the batch request for each user.
      batch.execute()

if __name__ == '__main__':

  # Construct a list of users.
  emails = ['ona@gmail.com', 'emi@gmail.com', 'sue@gmail.com', 'liz@gmail.com']

  # call the add_users function with the list of desired permissions.
  add_users(emails, ['READ_AND_ANALYZE'])

后续步骤

接下来,我们将介绍如何使用 Google Analytics(分析)Management API 来配置各种数据资源