基础说明
适用版本与验收边界
概述
适用场景
准备工作
钉钉应用配置步骤
1.
2.
3.
4.
5.
重要：请妥善保管 AppSecret，该信息仅在创建时显示一次。如忘记，可在应用详情页重新生成。
操作步骤
步骤 1：创建同步任务
1.
2.
3.
4.
5.
确认查看通讯录同步连接器列表中的关键配置
步骤 2：配置目标连接
| 参数 | 说明 | 是否必填 |
|---|---|---|
| AppKey | 钉钉应用的 AppKey，从钉钉开放平台获取 | 是 |
| AppSecret | 钉钉应用的 AppSecret，从钉钉开放平台获取 | 是 |
| 企业 CorpId | 钉钉企业的 CorpId，从钉钉管理后台获取 | 是 |
提示：测试连接成功表明 AppKey、AppSecret 和 CorpId 配置正确，且网络连通性良好。
步骤 3：配置字段映射
用户属性映射
| 平 台属性 | 钉钉字段 | 数据类型 | 必填 | 建议映射方式 |
|---|---|---|---|---|
| sub（用户ID） | userid | String | 是 | 创建且更新 |
| name（姓名） | name | String | 是 | 创建且更新 |
| mobile（手机号） | mobile | String | 是 | 创建且更新 |
| email（邮箱） | String | 是 | 创建且更新 | |
| department_ids（部门） | dept_id_list | Array | 是 | 创建且更新 |
| position（职位） | title | String | 否 | 创建且更新 |
| job_number（工号） | job_number | String | 否 | 创建且更新 |
| leader（直属上级） | senior | String | 否 | 创建且更新 |
注意：钉钉中 userid 支持字母、数字和下划线，长度 1~64 字符，且不可包含中文。如果平台用户 ID 不满足此格式，请使用转换规则进行格式化。
部门属性映射
| 平台属性 | 钉钉字段 | 数据类型 | 必填 | 建议映射方式 |
|---|---|---|---|---|
| id（部门ID） | dept_id | Number | 是 | 创建且更新 |
| name（部门名称） | name | String | 是 | 创建且更新 |
| parent_id（父部门ID） | parent_id | Number | 是 | 创建且更新 |
步骤 4：配置同步规则
| 参数 | 说明 | 建议配置 |
|---|---|---|
| 同步范围 | 指定同步内容类型 | 用户和部门 |
| 根组织ID | 组织架构同步起始节点 | 全量同步填"1"，部分同步填具体部门ID |
| 同步方式 | 同步执行的模式 | 日常运维选「自动增量」，定期校验选「自动全量」 |
| 同步周期 | 执行同步的频率 | 建议初始为"每小时"，稳定后调整为"每6小时"或"每天" |
| 开始时间 | 同步执行的起始时间 | 建议选择业务低峰期（如凌晨） |
| 强制创建 | 是否强制在下游创建用户/部门 | 建议开启 |
| 删除用户阈值 | 触发删除保护的阈值比例 | 小型企业 8 |
警告：删除用户阈值是重要的安全保护机制。当待删除用户比例超过阈值时，系统会暂停删除操作并将用户放入待删除列表，需管理员确认后才执行。请勿将阈值设置过低，以免正常离职流程被阻断。
步骤 5：执行同步并验证
1.
2.
3.
确认查看同步任务列表与结果中的关键配置
验证结果
连接测试
1.
2.
3.
同步结果验证
| 验证项 | 验证方法 | 预期结果 |
|---|---|---|
| 用户同步 | 对比平台用户列表与钉钉通讯录用户列表 | 用户数量和关键信息一致 |
| 部门同步 | 对比平台组织架构与钉钉部门结构 | 部门名称和层级关系一致 |
| 增量同步 | 在平台新增/修改/删除用户后触发同步 | 变更在钉钉端正确生效 |
| 字段映射 | 检查同步后用户在钉钉的属性值 | 字段值与平台一致 |
同步日志查看
1.
2.
常见问题
Q1：测试连接时报"AppKey 或 AppSecret 无效"
1.
2.
3.
Q2：同步后钉钉中用户手机号为空
1.
2.
3.
Q3：同步后部分用户未在钉钉中创建
1.
2.
3.
Q4：删除阈值触发后如何继续同步
1.
2.
3.
停用或回滚
修改于 2026-09-14 10:20:56