用户权限 - 开发者指南

本文介绍有关使用 Management API 查看和管理用户针对 Google Analytics（分析）帐户、媒体资源和数据视图（配置文件）的权限。

简介

利用 Management API 中的用户权限，您可以列出、创建、编辑和删除您的 Google Analytics（分析）帐户的用户。如果您希望向 Google Analytics（分析）自动添加新用户或移除一组用户，这就非常有用。

开始之前

所有 Google Analytics（分析）API 的访问方法都基本相同。在开始使用 Management API 之前，您应该：

• 阅读客户端库页面，查看与该 API 配合使用的编程语言客户端库的完整列表。
• 阅读参考指南，熟悉该 API 的界面，并了解如何在没有客户端库的情况下访问数据。

每个客户端库提供单个 Analytics 服务对象来访问所有的 Management API 数据。要创建服务对象，您通常需要完成以下步骤：

1. 在 Google Developers Console 中注册您的应用。
2. 授予访问 Google Analytics（分析）数据的权限。
3. 创建一个 Analytics 服务对象。

如果您未能完成上述步骤，请停止操作，并阅读了解 Google Analytics（分析）API 教程。该教程将为您详细介绍构建 Google Analytics（分析）API 应用的最初几个步骤。完成这些步骤后，您将了解如何访问 Google Analytics（分析）API 以执行实际任务。

概念

帐户层级结构

Google Analytics（分析）拥有帐户层级结构，其中授权用户可以拥有多个帐户，每个帐户可以有多个媒体资源，每个媒体资源又可以有多个数据视图（配置文件）。

图 1：帐户层级

权限级别

一个 Google 帐户代表一个用户，用户可以被授予对于 Google Analytics（分析）帐户、媒体资源或数据视图（配置文件）的不同级别的访问权限。

访问权限级别有：

• MANAGE_USERS
• EDIT
• COLLABORATE
• READ_AND_ANALYZE

要了解每个访问层级的更多详情，请参阅用户权限。

继承权限

如果用户被授予对于某个帐户的 EDIT 权限，该帐户下的所有配置文件和媒体资源都将继承这一权限。同样，如果用户被授予对于某个媒体资源的 COLLABORATE 权限，该媒体资源下的所有配置文件也都将继承这一权限。

使用权限

API 提供两种类型的权限：local 和 effective。Local 权限适用于实际的帐户、媒体资源或数据视图（配置文件）。只有 local 权限才可以进行配置。Effective 权限表示从父级资源继承下来的权限。

获取授权用户的权限信息

您可以通过执行 list 或 get 操作（针对帐户、网络媒体资源或数据视图（配置文件）资源），获取当前授权用户的权限信息。

要执行这些操作，用户必须对下列其中一个范围进行授权：

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

管理用户权限

以下资源可用来查看和管理对于 Google Analytics（分析）帐户、媒体资源和数据视图（配置文件）的用户权限。

• 帐户用户关联 — 删除、列出、创建和更新帐户权限。
• 网络媒体资源用户关联 — 删除、列出、创建和更新媒体资源权限。
• 配置文件用户关联 — 删除、列出、创建和更新数据视图（配置文件）权限。

只有拥有 MANAGE_USERS 级别权限并且对以下范围进行了授权的用户才可以执行上述这些操作：

• https://www.googleapis.com/auth/analytics.manage.users 范围。

帐户用户关联限制

对于该 API，上限是每个用户 100 个帐户。

• 如果试图为某个已经拥有 100 个或更多帐户的用户调用 insert 方法，系统将返回错误。
• 请参阅限制和配额，了解一般的限制有哪些。

使用情形

Management API 中的用户权限可用来解决以下使用情形：

• 列出帐户的所有用户
• 从帐户层级结构中删除某个用户
• 更新单个用户
• 添加单个用户

列出帐户的所有用户

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

注意：对于某些用户而言，如果他们被授予的访问权限针对的是帐户层级结构中的深层级别，而不是直接针对帐户，则他们的 local 权限属性可能为空。

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

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

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

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

更新单个用户

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

1. 获取每个实体级别的所有用户关联。
   对帐户执行 3 次 list 请求：
   1. list 所有 accountUserLinks。
   2. 通过将 webpropertyId 参数设置为 ~all， list 所有 webpropertyUserLinks。
   3. 通过将 webpropertyId 和 profileId 参数设置为 ~all， list 所有 profileUserLinks。
2. 查找并更新有 local 权限的用户。
   对于从第 1 步的 3 次 list 操作中得到的每个响应，遍历每个 entityUserLink：
   • 如果 userRef 属性与用户匹配，并且用户拥有带 READ_AND_ANALYZE 访问权限的 local 权限，则对该资源执行 update。

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

添加单个用户

要向帐户层级结构添加用户，例如向某个数据视图（配置文件）添加用户，需要完成以下步骤：

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

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

批量处理

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

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

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

• 将您的 API 请求按用户分组。
• 在批量请求中仅包含针对同一帐户的请求。使用多个 Google Analytics（分析）帐户的批量用户权限请求会导致出错，错误信息为：所有批处理请求必须使用相同帐户。

批处理示例 - Python

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