钉钉用户同步
把钉钉作为用户数据源后，千问办公按所选范围读取部门和成员，并根据字段映射创建或更新用户。后续的入职、调岗和离职处理也由这份数据源配置控制。
一次性申请清单
将下表交给钉钉企业应用管理员，在「权限管理」中按名称查找并开通。先确定需要将哪些成员资料同步到千问办公，再申请对应权限。
| 权限或配置 | 是否需要 | 对应数据 |
|---|---|---|
| 通讯录部门信息读权限 | 必需 | 部门 ID、名称、上级关系 |
| 通讯录部门成员读权限 | 必需 | 部门中的成员列表 |
| 成员信息读权限 | 必需 | 成员标识、姓名、部门关系等基础资料 |
| 企业员工手机号信息 | 需要将手机号同步到千问办公时申请 | mobile |
| 邮箱等个人信息 | 需要将邮箱同步到千问办公时申请 | 核验成员详情中 org_email 等实际返回字段 |
| 成员信息读权限、通讯录部门成员读权限 | 工号随成员资料读取 | 钉钉成员接口返回 job_number，配置页对应 jobNumber；先确认成员档案已填写工号 |
| 通讯录权限范围、应用可见范围及发布 | 必需 | 覆盖目标部门、成员和必要的上级部门 |
请一次准备好以下信息：
- 企业与应用：企业名称、Corp ID、应用名称。
- 应用凭据：Client ID（AppKey）、Client Secret（AppSecret）。
- 权限与范围：权限开通结果、准备同步的完整组织范围；若平台要求，还需提供服务出口 IP。
- 核验资料：一名普通成员的
userid，以及预期同步的姓名、企业邮箱、手机号和工号。
Corp ID 用于核对企业；本向导填写 Client ID 和 Client Secret。
钉钉应用的通讯录权限范围应覆盖准备同步的完整组织结构和必要上级部门。同一应用承担 SSO 时，一并申请钉钉登录权限。
在钉钉开通通讯录读取
- 登录钉钉开放平台，进入
应用开发 → 企业内部开发，创建或打开企业内部应用。 - 打开
权限管理 → 通讯录管理。在搜索框依次查找并勾选 通讯录部门信息读权限、通讯录部门成员读权限、成员信息读权限。 - 若需要将钉钉成员的手机号同步到千问办公，则勾选 企业员工手机号信息。
- 若需要将钉钉成员的邮箱同步到千问办公，则勾选 邮箱等个人信息。
- 勾选所需权限后，点击【批量申请】。若同时同步手机号和邮箱，则应勾选第 2 步的三项基础权限，以及第 3、4 步的两项资料权限，共五项。
- 若需要将钉钉成员的工号同步到千问办公，则请通讯录管理员先在成员档案中填写工号，再在千问办公将
jobNumber对应「工号」。工号随成员资料读取，使用第 2 步申请的权限。 - 在「权限范围」中确保应用能够读取准备同步的全部部门、成员和必要上级部门。若选择【部分员工】，其范围也必须完整覆盖千问办公将同步的组织，不能只选择一个测试部门。
- 在「应用信息」取得 AppKey / Client ID 和 AppSecret / Client Secret。确认它们属于同一个应用。
- 服务器出口 IP 为可选项：在钉钉开发者后台 → 目标应用 → 安全设置中查看「服务器出口 IP」。若为空且组织无强制要求，无需填写，直接进入下一步。
权限开通后，请让一名普通成员填好需要同步的资料，再执行一次同步。在千问办公「用户」页核对邮箱、手机号或工号是否与钉钉一致；若需要同步的资料为空，按下表处理。
| 缺少的资料 | 必须检查的项目 |
|---|---|
| 邮箱 | 「邮箱等个人信息」已获授权；核验成员的企业邮箱已填写；映射来源为 org_email |
| 手机号 | 「企业员工手机号信息」已获授权；成员档案有手机号；映射来源为 mobile |
| 工号 | 成员档案有工号；成员读取权限已获授权；映射来源为 jobNumber |
若三项均为空或成员没有导入，先检查应用权限范围是否包含该成员，再查看本次同步详情。不要只根据凭据测试成功判断资料授权完成。
本接入向导提供手动和定时同步。无需为这两种方式配置钉钉事件订阅回调。
第一步：填写应用凭证
- 进入
用户与体验 → 用户管理 → 用户同步，点击【新增数据源】。 - 选择「钉钉」，点击【开始配置】。已有钉钉数据源时，点击该行【修改配置】。
- 将钉钉应用的 Client ID 和 Client Secret 填入同名字段。
- 点击【测试并下一步】。新建时，成功后保存当前配置草稿并进入映射设置；编辑已有数据源时，仍需完成最后一步保存。该测试只交换访问令牌，不读取部门或成员，也不能证明通讯录权限和字段已经正确。修改已有密钥时，只有输入新值才会替换原凭据。
第二步：核对部门和成员映射
先检查部门，再检查成员。部门映射通常使用预设来源；成员的来源字段可从钉钉支持的字段中选择，右侧目标固定。需要补充可选项时，从对应区域的【添加映射】下拉选择目标，页面带入钉钉预设字段，右侧目标字段加入后固定。下表用于核对钉钉返回的数据。
| 配置页预设的来源字段 | 千问办公字段 |
|---|---|
部门 id、name、parentId | 第三方部门 ID、部门名称、上级第三方部门 ID |
成员 userid、name | 第三方用户 ID、用户姓名 |
org_email、mobile、jobNumber | 邮箱、手机号、工号 |
staffId、departmentId、active | 账号、所属部门的第三方部门 ID、用户状态 |
新建钉钉数据源时，页面默认把 userid 映射到第三方用户 ID。账号默认来源 staffId 是为兼容已有配置保留的同一企业用户 ID 别名，不是员工工号；工号使用 jobNumber。如果 SSO 同样使用钉钉，登录侧 user.userid 应与同步侧 userid 对应同一人。成员所属部门的 ID 必须能在部门映射结果中找到。
第三步：选择策略并执行同步
- 点击【下一步】，选择「全部」或「指定部门」。这里是千问办公实际应用的同步范围；钉钉应用本身仍须提供完整的可读取组织。
- 注意，指定部门仅在已全量同步后编辑时可生效；
- 如需控制初次和后续同步时，控制数据范围，请在钉钉应用内，修改应用权限范围，同步任务仅会同步可见范围内的用户数据
- 设置「新用户默认申请席位」。若希望先核对账号再分配席位，可保持关闭。
- 选择“仅手动”；需要自动执行时，选择“定时同步”，再选“每天”并设置北京时间。通常先采用手动同步核对结果。
- 设置 删除处理。通常先采用「停用账号并回收席位」，便于检查离职结果；是否直接删除应按企业账号保留要求决定。
- 设置删除告警阈值和告警邮箱，点击【保存配置】。
- 在数据源列表开启钉钉。企业同一时间只启用一个数据源；切换前核对提示中的原数据源。
- 点击【立即同步】，完成后在「同步记录」点击本次任务【详情】，核对新增、更新、停用、删除及席位变化。
- 在「用户」页核对普通成员和部门。结果正确后，再调整千问办公中的同步范围或改为每天执行。
常见问题
| 现象 | 处理方法 |
|---|---|
| 连接正常但少了成员 | 检查钉钉应用的通讯录权限范围和千问办公同步范围，两者都须覆盖该成员 |
| 邮箱为空 | 检查 org_email 等实际资料字段及读取权限，不要用个人邮箱字段替代企业邮箱而不核对 |
| 同步部分成功 | 打开记录详情，根据失败对象和原因修正，再发起同步 |
| 大量成员被判定离职 | 先停用数据源，检查权限范围、映射和部门范围是否被缩小，再决定恢复与重试 |
删除告警用于提醒和记录，不等同于执行前审批。调整范围或删除策略前，应先估算会受影响的成员数量。
与已有用户衔接
同步前，先核对来源中的三方 ID 与已有用户一致。
- 匹配用户： 只通过三方 ID 查找。账号、邮箱、手机号和工号用于冲突校验；三方 ID 未命中，但其中任一值已被占用时，本条同步失败。
- 更新成功： 保留原 QID，并将当前维护来源设为这份数据源。
- 锁定资料： 来源开启期间，该来源用户的姓名、邮箱、账号、手机号、三方 ID、工号均不可手动修改；部门和状态按映射锁定。
- 删除后再出现： 不恢复旧 QID。系统按当前钉钉资料创建新用户和新 QID，计为“创建”；旧历史保留，三方 ID 改为关联新用户。新用户不继承旧角色、密码、用户组、管理员权限、席位或部门，默认席位按当前数据源设置处理。
修改映射、切换来源和删除后新建的完整规则见用户同步。
返回：用户同步-概述