这个接口解决什么问题

道一云·七巧的「查询用户」接口用于从企业组织架构中拉取用户列表,典型用途包括 CRM 与协同办公系统的账号关联、组织架构对照、通讯录同步以及按部门筛选人员。在小满 OKKICRM 与道一云集成的多个客户项目里,该接口都是用户主数据同步的第一站,属于纯查询策略。

接口能力总览

接口路径:/plus/cgi-bin/open/users(查询用户列表)
认证方式:采用企业级 OpenAPI 凭证,通常以 access_token 或应用级签名接入,具体由道一云开放平台分配
请求方式:HTTP GET(部分场景支持 POST)
核心请求参数:
- departmentId:根部门 ID 列表(逗号分隔),用于限定查询部门范围
- page:页码,默认 1
- pageSize:每页条数,默认 100
响应结构:JSON 数组,每条记录为一个用户对象,字段详见后文
分页模式:基于 page + pageSize 的传统分页;增量模式一般按 updateTime 字段在调用方侧做游标过滤
限流特性:开放平台有调用频率限制,大批量拉取需做节流

字段名	类型	含义	实战注意事项
id	string	道一云用户唯一主键	强烈建议作为跨系统关联键,稳定性高于 account
account	string	登录账号(手机号/邮箱)	可用于匹配 CRM 用户,但离职后可能复用,慎作主键
name	string	真实姓名或昵称	展示用,业务字段映射时常配置为 `user_name`
gender	string	性别	部分租户未填写,需做空值兜底
telephone	string	手机号	涉及隐私,落地 CRM 前确认脱敏策略
defaultDepartmentId	string	默认部门主键	与 `defaultDepartmentName` 配合做组织对照
defaultDepartmentName	string	默认部门名称	部门更名后历史值不会回溯,谨慎用于关联
wxUserId	string	关联的企微/微信用户 ID	做企微集成时的关键映射字段
extend	object	自定义扩展属性	结构随租户配置变化,字段映射器最好配置成「透传 + 按需取值」

在轻易云数据集成平台里,这类查询接口通常以「查询适配器」形式封装:

适配器选择:选择「道一云·七巧 / 用户查询」适配器,填入应用凭证与部门范围(departmentId 多值用逗号分隔)
分页设置:在轻易云的「分页参数」面板里将 pageSize 调至 100(平台允许的最大值),减少请求次数
字段映射器:轻易云的字段映射器会自动把 id、account、name 等标准化为通用概念(user_id、user_account、user_name),extend 对象可展开后按路径取值
目标侧:Target 配置为「写入空操作」,表示这是纯查询策略,结果用于下游用户匹配或缓存
调度策略:结合 updateTime 增量游标,轻易云的「增量拉取」开关可避免重复全量

id 优先于 account 做关联键:在多个客户项目里我们观察到,account(手机号/邮箱)存在回收复用风险,而 id 在租户内长期稳定。
departmentId 多值传好不传满:传 1~3 个核心根部门通常足够,传入过多会拖慢响应并易触发限流。
extend 不要硬编码字段:不同租户扩展结构差异很大,稳妥做法是「先透传到目标,再按需解析」。
增量必须基于 updateTime 而非 id:id 不保证单调递增,按 id 增量会漏数。
手机号与企微 ID 同步脱敏:telephone 与 wxUserId 写入 CRM 前,务必按客户合规要求做脱敏或哈希处理。
分页拉完要做一致性校验:最后一页往往不满,需要在轻易云的「尾部去重」开关里配置 id 去重,避免边界丢数。

departmentId 为空却返回全员:请求里如果完全省略 departmentId,部分接口版本会返回组织内所有用户,造成数据爆炸。稳妥做法是显式传值,哪怕只传一个根部门。
pageSize 超限被截断:道一云对单次返回条数有限制,传超过上限时不会报错而是直接截断,容易让人误以为已拉完。配置时先确认文档上限,轻易云里默认 100 通常安全。
extend 字段被强类型化失败:JSON 解析器对 object 字段做严格类型校验,租户偶发返回 null 或数组会导致整批失败。建议在轻易云里把 extend 声明为弱类型或字符串透传。
updateTime 时区不一致:API 返回的时间字符串若不带时区,跨时区增量会重复或漏数。集成时统一按 UTC 解析,本地化显示在展示层做。
限流未做退避导致任务中断:全量同步时连续高频调用容易撞上限流。建议轻易云里开启「失败重试 + 指数退避」,并错峰调度。

适合「需要从道一云组织架构拉取用户做同步、匹配、权限映射」的场景,尤其在 CRM、HR、企微一体化集成中作为基础数据来源。不适合实时性要求低于 1 分钟、或需要双向写入用户变更到道一云的场景——后者请改用「用户变更回调」或专门的写入接口。