• 简体中文

      • 从钉钉同步用户数据

      钉钉专业版+

      介绍

      钉钉插件支持将钉钉组织中的用户和部门同步到 NocoBase。除了手动执行全量同步，还可以通过 HTTP 回调或 Stream 长连接接收增量变更。

      准备工作

      1. 安装并启用 钉钉 和 用户数据同步 插件。
      2. 在钉钉开发者后台创建企业内部应用。
      3. 按照下文说明为应用开通通讯录权限并配置数据权限范围。
      4. 复制应用的 Client ID 和 Client Secret。凭据配置可以参考认证：钉钉。

      配置通讯录权限和数据权限范围

      在钉钉开发者后台进入应用的 权限管理，开通以下通讯录权限。

      权限权限标识是否必需用途
      通讯录部门信息读权限qyapi_get_department_list是读取部门列表、部门名称和上下级关系。
      通讯录部门成员读权限qyapi_get_department_member是读取部门下的成员列表。
      成员信息读权限qyapi_get_member是读取成员详情及所属部门。
      企业员工手机号信息fieldMobile使用手机号时必需同步手机号；当 用户唯一标识字段 选择 mobile 时必须开通。
      邮箱等个人信息fieldEmail否需要同步用户邮箱时开通。

      权限开通后，还需要在应用的 数据权限（部分版本显示为“通讯录权限范围”或“可见范围”）中选择允许同步的部门和员工。建议需要全量同步时选择全部员工；如果只选择部分部门或员工，NocoBase 只会同步该范围内的数据。

      Warning

      接口权限决定应用可以读取哪些字段，数据权限范围决定应用可以读取哪些部门和员工，两项都需要配置。事件订阅不能代替通讯录读取权限：NocoBase 收到事件后仍会调用钉钉接口读取对应用户或部门的最新信息。

      如果同一个钉钉应用还用于用户登录，请另外按照认证：钉钉开通登录所需的个人信息权限；这些登录权限不属于用户数据同步的必需权限。

      添加钉钉同步来源

      进入 用户和权限 > 同步，点击 添加，类型选择 钉钉。

      配置以下字段：

      字段说明
      来源名称当前同步来源的唯一名称。
      启用启动当前来源的事件接收，并允许执行同步任务。
      Client ID钉钉企业内部应用的 Client ID，支持使用环境变量和密钥。
      Client Secret钉钉企业内部应用的 Client Secret，支持使用环境变量和密钥。
      用户唯一标识字段可选择 mobile 或 unionId。首次同步后应保持该选项稳定；缺少所选字段的用户会被跳过。
      事件接收模式选择 HTTP 回调 或 Stream 模式，接收用户和部门的增量变更。

      保存并启用来源后，先点击 同步 完成首次全量同步，再使用事件订阅处理后续增量变更。

      选择事件接收模式

      Stream 模式

      Stream 模式由 NocoBase 服务端主动与钉钉建立持久连接，不需要公网回调地址、Token 或 EncodingAESKey。

      1. 在钉钉开发者后台进入应用的事件订阅设置，选择 Stream 模式。
      2. 订阅应用需要的用户和部门变更事件。
      3. 在 NocoBase 中选择 Stream 模式，保存并启用同步来源。

      同步来源启用后会启动 Stream 客户端。更新、停用或删除来源时，对应连接会刷新或关闭。

      Info

      NocoBase 服务端需要能够主动访问钉钉。Stream 模式不要求配置反向代理，也不需要提供公网入站回调地址。

      HTTP 回调

      HTTP 回调模式通过 NocoBase 的回调地址接收钉钉事件。

      1. 在 NocoBase 中选择 HTTP 回调。
      2. 填写钉钉事件订阅所配置的 Token 和 EncodingAESKey。
      3. 保存来源并复制生成的 事件回调 URL。
      4. 将该 URL 配置到钉钉开发者后台，并订阅需要的用户和部门事件。

      回调地址必须能够被钉钉访问。生产环境应通过 HTTPS 暴露该地址，并确保反向代理完整转发请求路径。

      支持的增量事件

      两种事件接收模式均支持以下钉钉事件：

      事件在 NocoBase 中的处理
      user_add_org创建或更新用户。
      user_modify_org更新用户。
      user_leave_org删除已同步用户。
      org_dept_create创建或更新部门。
      org_dept_modify更新部门并同步该部门的用户。
      org_dept_remove删除已同步部门。

      同步字段

      部门字段

      钉钉字段NocoBase 字段或用途
      dept_id部门的来源唯一标识。
      name部门名称。
      parent_id上级部门，用于建立部门层级。若上级部门不在数据权限范围内，当前部门会作为根部门同步。

      用户字段

      钉钉字段NocoBase 字段或用途
      mobile 或 unionid根据 用户唯一标识字段 的配置生成用户的来源唯一标识和用户名。缺少所选字段的用户会被跳过。
      name用户昵称。
      mobile手机号。需要开通 企业员工手机号信息 权限。
      email，为空时使用 org_email邮箱。需要开通 邮箱等个人信息 权限。
      dept_id_list用户所属部门；只保留数据权限范围内的部门。
      dept_order_list主部门。
      leader_in_dept用户是否为对应部门的负责人。

      部门负责人

      钉钉会通过用户详情中的 leader_in_dept 标记用户在各个所属部门中是否为负责人。NocoBase 按部门分别同步该标记：同一个用户可以是多个部门的负责人，负责人部门也不一定是用户的主部门。只有数据权限范围内的部门会参与同步。

      钉钉中的负责人标记被取消后，下次同步也会取消 NocoBase 中对应的负责人标记；在 NocoBase 中手动修改的负责人状态可能在下次同步时被钉钉数据覆盖。

      全量同步和增量同步使用相同的字段映射。目前不会同步头像、职位、工号等其他钉钉用户字段。

      故障排查

      • 同步结果为空或缺少整个部门时，检查三项必需的通讯录读取权限，以及该部门是否包含在数据权限范围内。
      • 用户存在但手机号或邮箱为空时，分别检查 企业员工手机号信息 或 邮箱等个人信息 权限。
      • 出现“部门/员工不在权限范围内”等错误时，扩大应用的数据权限范围，而不是只重新订阅事件。
      • 用户被跳过时，检查用户是否具有当前配置的唯一标识字段。
      • Stream 模式可以在应用日志中搜索 Dingtalk stream client starting、Dingtalk stream client started 或连接错误。
      • HTTP 回调模式需要确认回调地址可被公网访问，并检查 Token 和 EncodingAESKey 是否与钉钉配置一致。
      • 修改钉钉应用权限或可见范围后，重新执行一次手动全量同步。