配置企业微信数据源

如果您正在使用企业微信开展办公，可通过将其配置为数据源，将您的组织架构快速导入到腾讯统一身份（后续简称OneID）中，同时进行后续的同步。

本文档将指引您完成配置流程。开始前，请确保您拥有企业微信管理后台的管理员权限。

第一步：企业微信侧应用创建及配置

1. 创建应用

若已有稳定可用的已发布应用，此处也可不新建，直接点击需选用的应用进入详情页进行操作即可，为确保应用稳定可用，此处建议新建应用（以下操作需要登录企业微信管理平台，请先确保已经注册企业微信管理员账号，企业微信管理员账号注册流程请参见企业微信官网，此处不再赘述）。

登录企业微信管理平台。（若链接无法直达，可如下图操作，通过进入企业微信官网，点击右上角「企业登录」进入后台管理登录页）
登录成功后，点击「应用管理」按钮，进入应用管理页面。
如图找到【自建】区域，点击「创建应用」按钮，进入【创建应用】页面。
填写「应用Logo」「应用名称」「应用描述」并选择「可见范围」。 💡 提示：「可见范围」决定从企微同步到OneID的数据范围，请根据业务需要进行数据范围选择。后期根据业务变化也可以再次修改。
创建成功后，进入应用详情页面并提示「应用创建成功，可继续配置应用属性」，此时我们所需应用已经创建成功。

2. 查询企业微信凭证信息

企业微信凭证信息主要包含：企业ID、Agentid、Secret三个信息，主要用于后面One ID侧企业微信数据源配置使用。

在【企业微信管理后台-应用管理-自建】区域找到上一步骤新创建应用，点击应用，进入应用详情页面。查看Agentid和Secret。（注意：Secret需要点击「查看」后，使用管理员账号在移动端企业微信App中进行确认，确认通过后，会将Secret放发送到企业微信App上）

进入【企业微信管理后台-我的企业】页面，在我的企业页面查看「企业ID」信息。

3. 配置可信域名及可信IP

配置须知： 根据企业微信开发管理规则，自建应用获取企业内部数据前，必须完成可信域名与可信 IP 的配置。若省略此步，将导致接口调用失败。

操作准备：

域名：提前准备已备案的企业可信域名。
IP 信息：部署OneID Agent的服务器IP，需要可对外访问公网 IP。

以下为您详细说明配置步骤。

在【企业微信管理后台-应用管理-自建】区域找到上一步骤新创建应用，找到开发者接口区域，点击「设置可信域名」，进入可信域名配置页面。

在「可信域名」处填写公司官网可信的域名信息，点击「确定」。（注意：填写时，企业微信方会校验域名的真实性以及所有权。）

域名配置成功后，返回应用详情页面，在应用详情页面下方，找到开发者接口区域-企业可信IP，点击「配置」，进入可信IP配置页面。

在「企业可信IP」地址框中，填写部署OneID Agent的服务器IP。（注意：如果是集群配置可配置多个，中间用英文；隔开）

4. 范围及权限管理

企业微信创建应用时会对应用所能访问的数据（包括：用户数据和组织机构数据）进行权限控制，此步骤描述如何控制同步至OneID的数据范围。

在应用详情页找到「可见范围」，显示的是当前应用可以访问数据的范围，也就是可以同步到OneID的数据。点击「编辑」进入编辑页面。

进入可见范围编辑页面，可对当前范围进行删除、添加等操作，点击「添加」按钮，进入添加页面。

可见范围控制支持三种：「根据部门」「根据成员」「根据标签」，三种方式可以同时使用，也可以只使用其中一种或两种，具体可根据业务需要进行选择，选择完成点击「确认」。

回到可见范围编辑页面，点击「完成」，完成权限变更操作。

第二步：OneID侧数据源配置

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

登录OneID管理后台，在通讯录模块下点击「数据源」，进入页面后，选择企业微信数据源。

进入企业微信配置中，选择agent并填写在中获得的企业微信应用「AgentId」、「Secret」和「企业ID」并且复制平台提供的「授权回调域」。请注意：因大多数企业微信无法直接与外网进行链接，所以需要通过agent进行代理链接，具体可参考：Agent配置。配置agent成功后，通过选择运行中agent完成对企业微信的通信连接。安装Agent的服务器已经要保证能和企微网络互通。

若已经完成企微认证源配置，并且企微数据源和企微认证源使用的是同一台企微服务器时，系统会自动获取您在认证源配置的企微信息，你可以点击选择企微认证源选项，自动拉取企微配置信息。

数据源功能详情配置 需注意，此处OneID暂不支持设置部门或人员范围，若同步过程有指定范围的要求，可在第一步创建企业微信应用时在「可见范围」中进行数据权限设置

字段映射配置

有关字段映射的更多问题可查看字段映射说明文档 1）部门映射字段对应关系固定，不可修改； 2）人员字段对应关系中，用户id、用户登录名、用户姓名字段对应关系固定，不可修改。其他字段可自行添加对应关系。

⚠️注意：受企业微信个人隐私保护规则影响，企业微信部分数据不可直接获取。具体可获取字段明细请参考字段映射说明文档“企业微信获取数据说明”章节）

配置定时同步

定时器可以让同步任务定时触发，以保企微中的组织架构的变更能周期性地同步到腾讯统一身份中，对该配置项的具体说明可以参考文档同步方式。定时器可以设置触发时间和触发间隔。

删除保护配置此处为了防止您误删除操作，我们设置了删除保护条件，系统执行同步任务之前将识别本次操作是否会触发保护条件，若满足保护条件，则本次同步任务将不会进行，我们会给您留下的联系方式发送通知，删除保护条件可支持修改（为了避免误删除操作带来的影响，若非频繁触发导致日常同步难以进行，不建议修改保护条件）。注意：触发删除保护时，仅会自动停止您的删除操作请求，如果同一次同步中同时发起了新建、修改请求，新增、修改等请求会继续执行，不会受到影响。

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

第三步：启动同步

为您提供了两种导入/同步的执行方式方式：手动同步、定时同步。

手动同步

当您配置好企微作为数据源后，您会在「数据源」页面下，看到「手动同步」按钮。

通过点击「手动同步」按钮，系统会立即执行一次导入/同步任务，手动同步的特点是即点即执行。

定时同步

当您需要经常维护您的目录数据，但希望避免 “每一次维护后都进入腾讯统一身份后台去手动点击进行同步” 这样的繁琐操作时，您可以设置一个定时器来周期性地自动进行目录数据同步。

在第三步的「设置同步策略」模块，您可以打开定时同步开关，在弹出的时间设定选项中，设置定时同步的频率。

例如: 设置每1小时进行一次自动同步，每天的同步从零点开始，可以做如下设置：

第四步：查看同步日志

在同步运行完毕后，可进入账号同步的页面查看同步日志，展示了在什么时间，以手动或者自动的方式进行了同步，并且可以查看同步的成功数据和失败数据。

点击具体某条同步日志，可以查看具体同步详情。

进入日志详情页面，可查看同步数据具体详情信息。

其他：数据源更换（非必要不建议更换）

点击「数据源更换」按钮，二次确认更换后可更换数据源类型（此处若只需要更换应用凭证而非更换数据源类型，可直接编辑数据源并更新凭证）；
需注意，更换数据源操作后，原有数据源的所有配置和同步记录将清空，已同步至OneID侧的人员会保留。

常见问题（FAQ）

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

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

问：需要开通些什么额外权限，如何在钉钉侧开通？

答：权限开通操作流程请参考本文档中第一步-第3点「范围及权限管理」模块相关描述，额外开通【根据手机号获取成员基本信息】权限。

问：如何在企业微信侧获取user_id？

答：登录企业微信管理平台，进入「通讯录-成员管理」模块，查看成员列表，选定需要查看的成员，在弹出的人员信息浮层顶部，员工名称后括号内容中存在员工UserID字段，即为该员工的user_id。

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

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