利用 Google Analytics(分析)Management API,您可以通过编程对用户权限进行管理。这对于经常更新访问控制列表的大型企业非常有用。
简介
共有三种主要的资源可用于控制哪些用户可以访问帐户、媒体资源或数据视图(配置文件):
另外,还针对用户权限写入操作,提供了特殊的批量处理支持。
用户权限
可将 Google Analytics(分析)帐户、媒体资源或数据视图(配置文件)的以下访问权限级别授予用户(由 Google 帐户代表相应用户):
MANAGE_USERS
- 向用户权限 API 发出写入请求所需的访问权限级别。EDIT
- 修改数据管理资源所需的访问权限级别。COLLABORATE
READ_AND_ANALYZE
有关各个访问权限级别的更多详细信息,请参阅帮助中心内的用户权限一文。
分配权限
API 提供两类权限:local
和 effective
。Local 权限适用于指定的帐户、媒体资源或数据视图(配置文件)。利用 API 分配权限时,您应使用 permissions.local
属性。Effective
权限表示从父级资源继承下来的权限。
继承权限
如果对用户授予了帐户的 EDIT
权限,则此帐户下的所有配置文件和媒体资源都将继承该权限;这种情况将由 permissions.effective 属性来表示。
使用情形
Management API 中的用户权限可用来应对以下使用情形:
列出帐户的所有用户
要列出帐户的所有用户,包括所有对帐户中的任何媒体资源或数据视图(配置文件)拥有权限的用户,您只需要执行 accountUserLinks 资源的 list
方法。
更新大量用户
要更新大量用户的权限,强烈建议您使用批量处理;这不仅能节省配额,而且非常高效 -- 请参见下文的批量处理部分,了解完整的详情。对帐户完成这一操作所需执行的步骤如下:
- 获取帐户的所有用户关联:
list
所有accountUserLinks
。
- 针对每个用户构造更新请求,其中包含适当的权限:
- 针对每个
accountUserLink
构造update
。
- 针对每个
- 针对每 300 个用户,构造一个包含上述更新请求的批量处理请求:
- 对每 300 个用户调用
batch
。
- 对每 300 个用户调用
从帐户层级结构中移除某个用户
从帐户层级结构(即:帐户、媒体资源和数据视图(配置文件))中彻底移除某个用户。完成这一操作所需要的步骤如下:
- 获取每个实体级别的所有用户关联。 对帐户执行 3 次
list
请求: - 查找并删除有 local 权限的用户。 对于从第 1 步的 3 次 list 操作中得到的每个响应,遍历每个
entityUserLink
:- 如果
userRef
属性与用户匹配,并且设置了local
权限,则对该资源执行delete
操作
- 如果
请参阅 API 参考,详细了解“帐户用户关联”、“网络媒体资源用户关联”和“数据视图(配置文件)用户关联”资源的 delete
方法。
更新单个用户
您还可以利用 Management API 来更新用户权限。例如,将用户权限级别从 READ_AND_ANALYZE
更改为 EDIT
的步骤如下(假设您不知道数据视图(配置文件)的名称或 ID):
-
获取每个实体级别的所有用户关联。对帐户执行 3 次
list
请求: -
查找并更新有 local 权限的用户。 对于从第 1 步的 3 次 list 操作中得到的每个响应,遍历每个
entityUserLink
:- 如果
userRef
属性与用户匹配,并且用户拥有带READ_AND_ANALYZE
访问权限的local
权限,则对该资源执行update
操作。
- 如果
请参阅 API 参考,详细了解“帐户用户关联”、“网络媒体资源用户关联”和“数据视图(配置文件)用户关联”资源的 update
方法。
添加单个用户
要向帐户层级结构添加用户,例如向某个数据视图(配置文件)添加用户,需要完成以下步骤:
- 使用 Management API 或网页界面获取帐户、媒体资源和数据视图(配置文件)的 ID。
- 通过执行
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 来配置各种数据资源。