通讯录同步-企业微信
适用版本与验收边界
概述
适用场景
重要：由于企业微信通讯录集成规则限制了集成的 IP 地址及域名与企业微信组织是否一致，所以仅在私有化版本中使用，不建议在 SaaS 平台配置多个企业微信组织的通讯录同步。如 SaaS 平台需要配置，请提交工单获取专业支持。
准备工作
企业微信应用配置步骤
1.
2.
3.
4.
5.
操作步骤
步骤 1：创建同步任务
1.
2.
3.
4.
5.
在通讯录同步的新建页面选择“企业微信”，进入同步连接器配置。
步骤 2：配置目标连接
| 参数 | 说明 | 是否必填 |
|---|---|---|
| 名称 | 当前通讯录同步任务的名称，例如“总部企业微信同步” | 是 |
| 企业应用选择 | 选择已在连接中心配置并 验证的企业微信应用 | 是 |
填写同步任务名称，并选择已在连接中心配置完成的企业微信应用。
未找到可选企业应用
步骤 3：配置字段映射
用户属性映射
在用户映射中重点核对成员 UserID、姓名、手机号、邮箱和所属部门等字段。
| 平台属性 | 企业微信字段 | 数据类型 | 必填 | 建议映射方式 |
|---|---|---|---|---|
| sub（用户ID） | userid | String | 是 | 创建且更新 |
| name（姓名） | name | String | 是 | 创建且更新 |
| mobile（手机号） | mobile | String | 否 | 创建且更新 |
| email（邮箱） | String | 否 | 创建且更新 | |
| department_ids（部门） | department | Array | 是 | 创建且更新 |
| position（职位） | position | String | 否 | 创建且更新 |
| address（地址） | address | String | 否 | 创建且更新 |
| avatar（头像） | avatar | String | 否 | 创建且更新 |
注意：企业微信中手机号获取需要应用具有敏感信息权限，如平台用户手机号为空或权限不足，企业微信端手机号将不会更新。
部门属性映射
在部门映射中重点核对部门 ID、部门名称、父部门 ID 和排序值。
| 平台属性 | 企业微信字段 | 数据类型 | 必填 | 建议映射方式 |
|---|---|---|---|---|
| id（部门ID） | id | String | 是 | 创建且更新 |
| name（部门名称） | name | String | 是 | 创建且更新 |
| parent_id（父部门ID） | parentid | String | 是 | 创建且更新 |
| order（排序值） | order | Integer | 否 | 创建且更新 |
步骤 4：配置同步规则
先确认同步范围、下游根组织、强制创建以及组织同步白名单或黑名单。
| 参数 | 说明 | 建议配置 |
|---|---|---|
| 同步范围 | 同步内容类型：用户和部门 / 仅同步用户 | 选择「用户和部门」 |
| 根组织ID | 组织架构同步起始节点 | 全量填"1"，部分填具体部门 ID |
| 强制创建 | 是否强制在下游创建不存在的对象 | 首次建设且确认映射正确时开启 |
| 组织架构同步模式 | 控制全量组织或部分组织参与同步 | 按实际同步范围选择「全量」或「部分」 |
| 组织同步白名单/黑名单 | 限定允许或排除同步的组织 | 部分同步时显式选择目标组织，避免范围过大 |
| 同 步方式 | 当前版本下拉框提供的同步执行方式 | 日常运行按实际变更策略选择，首次或定期校验可使用全量同步 |
| 删除用户阈值 | 触发批量删除保护的阈值 | 先按测试租户验证，再按组织规模设置保护阈值 |
| 同步周期 | 执行同步的频率 | 建议"每小时"，稳定后"每6小时" |
| 开始时间 | 同步执行的起始时间 | 建议业务低峰期 |
| 筛选规则 | 是否使用额外条件过滤待同步对象 | 没有明确过滤条件时保持关闭 |
再配置同步方式、删除用户阈值、同步周期、开始时间和筛选规则。
注意：企业微信 API 有调用频率限制（每分钟最多 300 次），大型组织请合理设置同步周期，避免触发限流。
步骤 5：执行同步并验证
1.
2.
3.
验证结果
企业应用可用性
1.
2.
3.
同步结果验证清单
| 验证项 | 验证方法 | 预期结果 |
|---|---|---|
| 用户数量 | 对比平台与企业微信的用户数量 | 数量一致（排除不在同步范围） |
| 用户信息 | 抽查用户姓名、手机号、部门 | 与平台一致 |
| 组织结构 | 对比部门层级和数量 | 层级关系一致 |
| 增量变更 | 在平台修改用户信息后触发同 步 | 变更在企业微信端生效 |
| 删除保护 | 删除超过阈值用户 | 用户进入待删除列表，非直接删除 |
同步日志查看
1.
2.
常见问题
Q1：测试连接报错"访问 IP 不在白名单中"
Q2：同步后用户在企业微信中无手机号
1.
2.
3.
Q3：同步后组织架构层级不正确
1.
2.
3.
Q4：API 调用频率超限
1.
2.
3.
停用或回滚
修改于 2026-09-14 10:20:56