配置飞书数据源

如果您已经在使用飞书作为您的办公IM软件，您可以通过配置飞书作为数据源，将您的组织架构快速导入到腾讯统一身份平台（以下简称One ID）中，同时进行后续的同步。

本文档将指导您如何配置飞书数据源，完成配置之后，通过自动同步或手动同步您可以将飞书组织架构数据同步至One ID目录中。在此之前，您需要拥有飞书管理后台和飞书开放平台的权限。

第一步：飞书侧应用创建及配置

1、创建应用

若已有稳定可用的已发布应用，此处也可不新建，直接点击需选用的应用进入详情页进行操作即可，为确保应用稳定可用，此处建议新建应用

登录飞书开放平台，点击「开发者后台」。

在飞书开发者后台点击「创建企业自建应用」按钮。

在弹出的“创建企业自建应用”弹窗中，填写必要的信息。点击「创建」按钮后进入新创建应用的详情页。

在应用详情页的左侧菜单栏中找到「凭证与基础信息」，

点击进入后在应用凭证模块中获取APP ID和APP Secret，请您复制并做好记录，用于后续在One ID中配置。

2、应用权限开通

在应用详情页的左侧菜单栏中找到「权限管理」。

在应用权限管理页面，点击「开通权限」。

通过逐一搜索以下权限名称，为应用开通以下权限： 注意：以下权限一定要全部开通

通讯录（8个）
- 获取通讯录基本信息
- 获取部门基础信息
- 获取通讯录部门组织架构信息
- 获取用户基本信息
- 获取用户组织架构信息
- 获取用户邮箱信息
- 获取用户受雇信息
- 获取用户手机号
应用信息（2个）
- 获取应用信息
- 管理应用自身资源
企业信息（1个）
- 获取企业信息

查询之后，勾选权限，并点击「确认开通权限」；
配置完成后，回到权限管理页面，确保以上权限全部开通；

3、配置应用权限范围

如果您需要选择部分指定成员数据同步到OneID可以执行此步骤配置，如不需要请忽略！

开通权限后，在权限管理页面，点击「配置」，进入可访问的数据范围页面。
在可访问的数据范围页面，点击「配置」，进入配置环节。
选择按需选择您要配置的数据范围。
配置完成后，点击「保存」。

4、版本发布

注意：配置完成后一定要发布，否则以上配置不会生效

在应用详情页的左侧菜单栏中找到「版本管理与发布」。
进入页面后点击「创建版本」按钮进行版本创建。
填写版本号、更新说明，并点击「保存」。
点击「确认发布」。
常规发布飞书是自动审核的，部分场景下发布会进入手动审核，如需手动可参考此步骤，自动审核请忽略。应用审核：进入飞书管理后台，左侧菜单栏中点击「工作台」-「应用审核」，进入页面后，将刚刚自建的应用的发布进行审核通过。
在版本发布页面检查当前版本审核状态，确定为「已发布」。

第二步：One ID侧数据源配置

1、数据源选择&应用凭证绑定

1）登录One ID管理后台，在通讯录模块下点击「数据源」，进入页面后，选择飞书数据源。

2）若认证源已绑定飞书应用凭证，此处可选择直接引用已有凭证，不需重新手动输入，若认证源未绑定或已绑定中无想要选择的凭证，可选择自行输入凭证进行绑定。自行输入的内容为上一步从飞书开发者平台获取到的APP ID和APP Secret。

手动输入
自动获取

2、数据源功能详情配置

2.1 数据范围配置

需注意，此处One ID暂不支持设置部门或人员范围，若同步过程有指定范围的要求，可在第一步创建飞书应用时在「配置应用权限范围」中进行设置。

2.2 字段映射配置

有关字段映射的更多问题可查看字段映射说明文档

1）部门字段对应关系固定，不可修改；

2）人员字段对应关系中，姓名字段为One ID侧固有字段，必须设置对应关系，邮箱/手机号/登录名字段为三选一必填字段，至少有一个对应关系存在才可正常保存；

3）飞书侧字段选择时，下拉选框仅提供基础字段选择，若需要的字段不在已有的下拉选框中可选，可以选择“自定义脚本”选项，选择后将自动弹出脚本输入弹窗，在弹窗中输入自定义的字段或脚本；

4）「映射配置数据测试」按钮为高级调试功能按钮，大多数情况为映射关系中存在自定义脚本时会用到，点击后弹出调试弹窗，可使用模拟数据或搜索真实人员数据，查看当前的映射关系下，One ID侧同步后的数据形式。

2.3 删除保护配置

此处为了防止您误删除操作，我们设置了删除保护条件，系统执行同步任务之前将识别本次操作是否会触发保护条件，若满足保护条件，则本次同步任务将不会进行，我们会给您留下的联系方式发送通知，删除保护条件可支持修改（为了避免误删除操作带来的影响，若非频繁触发导致日常同步难以进行，不建议修改保护条件）。

2.4 定时器配置

定时器默认关闭，关闭时可通过手动点击「手动同步」按钮，进行数据同步。建议开启定时器功能，开启后可以根据您实际的诉求，让同步任务定时触发，让飞书中的组织架构的变更能周期性地同步到One ID中。

2.5 保存页面配置

点击「保存」按钮，对页面全局改动进行保存，即完成了整体飞书数据源配置流程。

3. 数据源同步记录查看

1）上一步数据源功能详情配置操作完成之后，如果需要进行一次导入和同步，可点击「手动同步」按钮（需注意，如果详情配置未完成时，手动同步按钮是不可点击的），若已开启定时器功能，也可等到定时器触发自动同步，同步任务完成后可在同步记录列表中查看同步结果。

2）同步记录列表中，可点击进入结果详情页查看本次同步的详情记录：

详情页右侧为整体情况概览，包括人员/部门的成功变更条数及失败记录条数（需注意，本页面只记录变更记录，若本次同步无变更内容，将不会在本页面进行记录）；
详情页左侧可选择查看人员/部门的具体变更记录情况，可通过筛选条件筛选出需要查看的内容（需注意，一个部门/人员由于变更行动中操作内容不同，会产生多条记录，每条记录的操作行为不同，请注意查看备注中的操作行为）。

4.数据源更换（非必要不建议更换）

1）点击「数据源更换」按钮，二次确认更换后可更换数据源类型（此处若只需要更换应用凭证而非更换数据源类型，可参考上一步中修改凭证操作）；

2）需注意，更换数据源操作后，原有数据源的所有配置和同步记录将清空，但是已同步至One ID侧的人员将保留。

FAQ

1）Q：字段映射测试功能必须要开通额外权限吗？

A：额外权限开通场景为：需要通过手机号/邮箱搜索真实人员做映射实例时才需要开通，若直接用默认实例查看映射关系或通过userid搜索真实人员的情况，则不需要开通额外权限。

2）Q：需要开通些什么额外权限，如何在飞书侧开通？

A：权限开通操作流程请参考本文档中第一步-第2点「应用权限开通」模块相关描述，额外开通【根据手机号或邮箱获取用户ID】权限。

3）Q：如何在飞书侧获取user_id？

A：登录飞书管理后台，进入「组织架构-成员与部门」模块，查看成员列表，选定需要查看的成员，在弹出的人员信息浮层中找到【用户ID】字段，字段下方的内容即为该员工的user_id。

4）Q：映射结果中预览处提示字段缺失怎么办？

A：此处的【字段】指的是您在字段映射模块设置的映射关系中飞书侧选择的字段，【缺失】指的是在脚本编辑框中未找到对应的被选字段。若此处测试时您选择的搜索真实人员数据做映射，则出现该报错的原因可能是因为飞书侧应用创建时未开通对应字段的权限，请检查权限。