权限范围资源介绍
通过本文你可以了解什么是通讯录权限范围，以及权限相关的概念、生效规则、接口与事件。
什么是通讯录权限范围
通讯录权限范围定义了应用在调用通讯录 API 时可获取的部门、用户的数据范围。应用无法访问不在通讯录权限范围内的数据。
例如，通讯录中有 A、B、C 三个部门，若一个应用只有 B 和 C 两个部门的通讯录权限，那么该应用就只能通过接口获取到 B 和 C 两个部门的数据，获取 A 部门就会报出没有权限的错误。
通讯录权限范围可以由应用开发者管理维护，同时企业管理员也可以在管理后台管理维护。具体说明如下：
| 人员类型 | 配置场景 |
|---|---|
| 应用开发者 | 应用开发者可以在开发者后台的应用详情页内，配置应用的通讯录权限范围。以企业自建应用为例，需要进入应用详情页的 开发配置 > 权限管理 页面。添加方式分为以下两种： - 方式一：点击 开通权限，开通通讯录权限时，页面会自动跳转到通讯录权限范围的配置页面，点击 配置 即可自定义配置。配置完成后需要点击右下角 确定。  - 方式二：如果 API 权限列表已经添加了通讯录权限，则可以点击 可访问的数据范围 列字段右侧的 配置，跳转到通讯录权限范围的配置页面进行配置。  > Tip: - 商店应用无法修改用户所在企业的通讯录信息。 > - 默认情况下，通讯录权限范围与应用的可用范围一致。 > - 修改通讯录权限范围后，需要创建应用版本，由管理员审核通过后才可生效。 > - 通讯录数据访问范围需要配合通讯录权限才可生效，请注意在应用的 权限配置 > API 权限 中申请通讯录相关的 API 权限。  |
| 企业管理员 | 企业管理员可以在管理后台 > 工作台 > 应用管理 页面，进入指定应用管理页，然后管理应用的 通讯录设置。  |
相关概念
在调用通讯录 API 时，涉及应用身份（tenant_access_token）和用户身份（user_access_token）的区分。为不同身份配置通讯录权限范围时，可能涉及到的功能概念说明如下。
应用可用范围
当你在为应用设置通讯录权限范围时，有一个选项是 与应用的可用范围一致。应用可用范围定义了可以使用该应用的成员范围。详细介绍可参见配置应用可用范围。
用户组织架构可见范围
当你使用用户身份调用通讯录 API 时，可操作的权限范围不受应用的通讯录权限范围影响，而是受当前用户的组织架构可见范围影响，该范围限制了用户在企业内可见的组织架构数据范围，由企业管理员在管理后台 > 安全 > 成员权限 页面中，点击 组织架构可见范围 进行管理。
权限生效规则
| 类型 | 规则说明 |
|---|---|
| 用户通讯录范围的权限 | 调用 API 的应用或者用户身份，只要有一个部门的通讯录范围权限，那么就拥有该部门下所有用户的权限。需要配置用户通讯录范围权限的接口有： - 用户： - 获取单个用户信息 - 批量获取用户信息 - 搜索用户 - 恢复已删除用户 - 修改用户部分信息 - 删除用户 - 用户组成员： - 添加用户组成员 - 批量添加用户组成员 - 移除用户组成员 - 批量移除用户组成员 |
| 部门通讯录范围的权限 | 通讯录将部门的通讯录权限细化为父部门权限和部门权限两种。调用 API 的应用或者用户身份，只要有一个部门的通讯录范围权限，那么就拥有这个部门下所有子部门的权限。 - 需要父部门通讯录范围权限的接口有： - 创建部门 - 获取单个部门信息 - 批量获取部门信息 - 获取子部门列表 - 获取父部门信息 - 修改部门部分信息 - 更新部门所有信息 - 删除部门 - 需要部门通讯录范围权限的接口有： - 部门： - 获取单个部门信息 - 批量获取部门信息 - 获取子部门列表 - 获取父部门信息 - 修改部门部分信息 - 更新部门所有信息 - 删除部门 - 用户： - 创建用户 - 获取部门直属用户列表 - 恢复已删除用户 - 修改用户部分信息 - 删除用户 |
| 全员权限 | 全员权限是指拥有通讯录下所有数据的权限。需要拥有全员权限的场景，可参见下文 全员权限说明表。 |
全员权限说明表
| 资源 | 接口 | 场景说明 |
|---|---|---|
| 部门 | - 创建部门 | 在根部门下创建子部门 |
| 部门 | - 获取单个部门信息 - 批量获取部门信息 - 获取子部门列表 | 获取根部门下的子部门列表 |
| 部门 | - 获取父部门信息 | 获取根部门的信息 |
| 部门 | - 修改部门部分信息 - 更新部门所有信息 | 将部门的父部门更改为根部门 |
| 部门 | - 删除部门 | 删除根部门下的子部门 |
| 用户 | - 创建用户 | 在根部门下创建用户 |
| 用户 | - 获取部门直属用户列表 | 获取根部门下的用户列表 |
| 用户 | - 修改用户部分信息 - 恢复已删除用户 | 将用户所属部门配置为根部门 |
| 用户 | - 删除用户 | 删除根部门下的用户 |
| 用户组 | - 创建用户组 | 创建用户组时，应用需要有全员通讯录权限。 |
典型案例
小王开发了一个人力管理相关的自建应用。出于数据保密的要求，这个应用只能被 HR 同事使用，但由于应用需要管理全公司的人事信息，所以需要获取全公司的通讯录数据。该案例中，小王可以按照以下规则开发应用。
- 应用可见范围：设置为仅 HR 部门内的成员。
- 应用的通讯录权限范围：设置为全部成员。
待应用管理员审核通过应用的发布申请后，该人力管理应用就可以实现仅 HR 同事使用，且能够获得全公司的通讯录数据。
方法列表
通讯录 API 提供了如下接口与事件，供你管理查询通讯录权限范围相关数据。