利用 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
请求: - 查找和删除具有本地权限的用户。对于从第 1 步的 3 次 list 操作中得到的每个响应,遍历每个
entityUserLink
:- 如果
userRef
属性与用户匹配,并且设置了local
权限,则对该资源执行delete
- 如果
请参阅 API 参考,详细了解“帐号用户关联”“网络媒体资源用户关联”和“数据视图(配置文件)用户关联”资源的 delete
方法。
更新单个用户
您还可以使用 Management API 更新用户权限。例如,在您不知道数据视图(配置文件)名称或 ID 的情况下,将用户的权限级别从 READ_AND_ANALYZE
更改为 EDIT
的步骤如下:
获取每个实体级别的所有用户关联 对帐号执行 3 次
list
请求:查找并更新具有本地权限的用户。对于从第 1 步的 3 次 list 操作中得到的每个响应,遍历每个
entityUserLink
:- 如果
userRef
属性与用户匹配,并且用户拥有local
权限和READ_AND_ANALYZE
访问权限,则对该资源执行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 googleapiclient.errors import HttpError from googleapiclient.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 来配置各种数据资源。