基础说明
适用版本与验收边界
概述
集成价值
| 价值 | 说明 |
|---|---|
| 数据一致性 | 确保企业内部身份数据的一致性，消除信息孤岛 |
| 自动化同步 | 减少手动维护工作，降低人为错误风险 |
| 提高效率 | 简化用户管理流程，提高 IT 管理效率 |
| 身份统一管理 | 集中管理企业内各系统的用户身份 |
| 降低管理成本 | 减少多系统账号维护的人力投入和时间成本 |
适用场景
| 场景 | 说明 |
|---|---|
| 钉钉作为组织主数据源 | 企业使用钉钉作为组织架构和人员信息的主数据源 |
| 多系统身份打通 | 需要将钉钉的用户数据同步至多个业务系统 |
| 员工生命周期管理 | 员工入职、转岗、离职等状态变更需自动同步至相关系统 |
| 组织架构变更自动化 | 组织架构调整后，自动同步至各集成系统，确保数据一致性 |
准备工作
钉钉开放平台要求
| 要求 | 说明 |
|---|---|
| 钉钉企业管理员权限 | 需要具备钉钉企业管理员权限 |
| 钉钉开放平台应用 | 需要在钉钉开放平台创建企业内部应用，并获取 AppKey 和 AppSecret |
| 接口权限 | 通讯录管理权限、部门管理权限、角色管理权限（如需同步角色信息） |
专属集成平台要求
| 要求 | 说明 |
|---|---|
| 管理员账号 | 拥有专属集成平台的管理员权限 |
| 通讯录集成权限 | 具备创建和管理通讯录集成连接器的权限 |
| 系统版本 | 专属集成平台 v3.2.0 及以上版本 |
钉钉开放平台应用配置
操作步骤
步骤 1：创建钉钉集成连接器
1.
2.
3.
4.
步骤 2：配置基本连接信息
| 参数名称 | 说明 | 填写指南 |
|---|---|---|
| 企业选择 | 选择已配置的钉钉企业 | 选择之前在平台中添加的钉钉企业名称 |
| 名称 | 连接器显示名称 | 自定义名称，建议使用有业务含义的名称，如“钉钉-总部” |
提示：企业选择必须选择已在平台中添加的钉钉企业，如未添加请先完成企业添加。
步骤 3：配置同步策略
| 参数名称 | 说明 | 建议配置 | 适用场景 |
|---|---|---|---|
| 上游根组织 ID | 需要从钉钉同步的起始部门 ID | 默认为 1（同步全部组织）；特定部门 ID（部分同步） | 全部同步填“1”，部分同步填特定部门 ID |
| 同步范围 | 同步的数据类型 | 用户和部门 | 需要完整组织架构选“用户和部门”，仅需用户数据选“仅用户” |
| 数据在本地挂载节点 | 同步数据在平台中的挂载位置 | SAAS 认证 | 标准集成场景 |
| 挂载方式 | 组织架构挂载方式 | 视情况选择 | “与选择节点合并”：合并到现有组织；“在选择节点下新建”：作为独立组织 |
| 角色集成类型 | 用户职位的集成方式 | 视需求选择 | “不集成”：不同步角色；“按角色组集成”：同步角色组；“按角色集成”：同步具体角色 |
| 同步方式 | 数据同步策略 | 初次配置建议“手动全量同步”，验证后改为“自动增量同步” | 初次配置验证用“手动全量”，日常运行用“自动增量” |
| 同步周期 | 自动同步的频率 | 建议 6 小时 | 变更频繁选较短周期（30min–1h），变更不频繁选较长周期（12h–24h） |
| 开始时间 | 自动同步起始时间 | 业务低峰期，如凌晨 | 避免业务高峰期执行同步 |
| 账号关联 | 用户映射关系 | 常用“钉钉用户名与平台用户名” | 详见下方账号关联说明 |
| 过滤器 | 筛选同步数据 | 默认关闭 | 需要筛选特定用户时启用 |
| 连接测试 | 验证配置有效性 | 输入钉钉中存在的用户信息 | 测试连接是否成功 |
账号关联说明
1.
2.
3.
提示：优先使用唯一标识字段（如用户 ID），辅以手机号或邮箱等作为备选规则，增加匹配成功率。
过滤器说明
注意：过滤器表达式需要返回布尔值，返回 true的数据将被同步。
步骤 4：配置属性映射
属性映射方式
| 映射方式 | 说明 | 适用场景 |
|---|---|---|
| 不映射 | 不同步该属性至平台 | 不需要同步的字段或敏感信息 |
| 仅创建 | 仅在创建用户时同步该属性 | 初始值设置，后续不再更新 |
| 创建和更新 | 创建和更新时均同步该属性 | 需要持续保持同步的核心属性 |
核心字段映射概览
| 钉钉属性 | 平台属性 | 映射方式 | 说明 |
|---|---|---|---|
| userid | sub | 创建且更新 | 用户唯一标识 |
| name | name | 创建且更新 | 用户姓名 |
| mobile | phone_number | 创建且更新 | 手机号码 |
| 创建且更新 | 电子邮箱 | ||
| department | primary_org_id | 创建且更新 | 部门 ID |
| active | active | 创建且更新 | 用户状态 |
| position | title | 创建且更新 | 职位名称 |
| job_number | user_job_number | 创建且更新 | 工号 |
| 钉钉属性 | 平台属性 | 映射方式 | 说明 |
|---|---|---|---|
| id | connector_org_id | 创建且更新 | 部门唯一标识 |
| name | name | 创建且更新 | 部门名称 |
| parentid | parentRefId | 创建且更新 | 父部门 ID |
| order | seq | 创建且更新 | 部门排序值 |
| dept_manager_userid | manager | 创建且更新 | 部门负责人 ID |
| 钉钉属性 | 平台属性 | 映射方式 | 说明 |
|---|---|---|---|
| id | connector_role_id | 创建且更新 | 角色唯一标识 |
| name | name | 创建且更新 | 角色名称 |
| groupid | parentRefId | 创建且更新 | 角色组 ID |
步骤 5：连接测试
1.
2.
3.
4.
5.
提示：选择确认存在且状态正常的用户账号进行测试，建议使用信息较完整的账号，便于验证字段映射。
验证结果
执行同步测试
1.
2.
3.
4.
5.
| 统计项 | 说明 |
|---|---|
| 成功同步的用户数量 | 验证与上游用户数是否一致 |
| 成功同步的部门数量 | 验证部门层级结构是否完整 |
| 失败记录数量及原因 | 逐条排查失败原因并修正 |
提示：首次同步建议选择非工作高峰期执行。大量数据首次同步可能需要较长时间，请耐心等待。
数据验证
| 验证步骤 | 操作方法 |
|---|---|
| 用户数据检查 | 导航至「用户管理 → 用户列表」，筛选钉钉连接器作为认证源，抽查用户信息完整性 |
| 部门关联验证 | 确认用户与部门的关联关系是否正确 |
| 用户状态验证 | 验证用户状态（启用/禁用）是否符合预期 |
| 组织架构验证 | 导航至「用户管理 → 组织管理」，检查部门层级、名称、排序、负责人设置 |
增量同步测试
1.
2.
3.
数据管理
查看同步用户
1.
2.
3.
4.
待删除用户处理
| 操作 | 说明 |
|---|---|
| 确认删除 | 点击用户行右侧的“确认”按钮，用户将被从系统中删除 |
| 批量确认 | 选择多个用户，点击“批量确认”按钮 |
| 拒绝删除 | 如确认某用户不应删除，可点击“拒绝”按钮，用户将保留在系统中 |
警告：在确认删除前，先核实这些用户在钉钉中的状态。批量删除操作建议先导出列表进行审核。
常见问题
连接问题
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 连接测试失败 | API 接口权限不足、AppKey/AppSecret 不正确、网络问题 | 检查接口权限、验证凭证、确认网络连通性 |
| API 调用频率限制 | 短时间内多次同步操作 | 调整同步周期，实施错峰同步 |
同步数据问题
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 数据同步不完整 | 根组织 ID 设置不正确、属性映射错误、过滤 器过滤 | 检查根组织 ID、验证映射、暂时禁用过滤器测试 |
| 组织架构错误 | 部门 ID 和父部门 ID 映射不正确 | 检查部门属性映射，调整挂载方式 |
| 同步超时 | 数据量过大、网络质量不佳 | 分批同步、优化服务器资源 |
钉钉 API 特别说明
| 特性 | 说明 |
|---|---|
| API 调用限制 | 每分钟约 5000 次，超出后返回限流错误 |
| 组织结构 | 最多支持 16 级部门层级，一个用户可属于多个部门 |
| 数据同步特点 | 仅支持增量回调，不支持全量回调；全量数据需主动拉取 |
停用或回滚
修改于 2026-09-14 10:20:56