钉钉集成连接器如何配置属性映射

概述

本文档详细说明钉钉通讯录集成中属性映射的配置方法。属性映射决定了钉钉数据字段与专属集成平台字段之间的对应关系，是确保数据准确同步的关键环节。正确配置属性映射可保证用户、部门和角色数据在同步过程中的完整性和一致性。

前提条件

前提条件	说明
已完成连接器创建	已在专属集成平台中创建钉钉集成连接器
了解钉钉字段结构	熟悉钉钉开放平台返回的用户、部门、角色数据结构
了解平台字段结构	了解专属集成平台中用户、组织、角色的属性定义

操作步骤

步骤 1：了解属性映射方式

在配置具体映射之前，需要先理解三种映射方式的含义和使用场景：

映射方式	说明	适用场景
不映射	不同步该属性至平台	用于不需要同步的字段或包含敏感信息的字段
仅创建	仅在创建用户时同步该属性，后续更新不再同步	用于初始值设置，后续应在上游保持不变或由平台独立管理
创建且更新	创建和更新用户信息时均同步该属性	用于需要持续与上游保持同步的核心属性

重要：对于用户唯一标识、姓名、手机号等核心字段，强烈建议使用“创建且更新”映射方式，确保数据持续一致。

步骤 2：配置用户属性映射

在「用户」选项卡中，配置钉钉用户属性与平台用户属性的映射关系。

用户属性映射表

钉钉属性	专属集成平台属性	建议映射方式	说明
userid	sub	创建且更新	用户唯一标识，必须映射
name	name	创建且更新	用户姓名
mobile	phone_number	创建且更新	手机号码
email	email	创建且更新	电子邮箱
department	primary_org_id	创建且更新	部门 ID
active	active	创建且更新	用户状态（启用/禁用）
position	title	创建且更新	职位名称
job_number	user_job_number	创建且更新	工号

注意：钉钉的 department 字段包含用户所属部门 ID 列表，同步时会自动解析并关联到对应组织节点。

提示：如钉钉用户数据中包含其他业务字段（如入职日期、办公地点等），可根据需要添加额外映射。

步骤 3：配置部门属性映射

在「部门」选项卡中，配置钉钉部门属性与平台部门属性的映射关系。

部门属性映射表

钉钉属性	专属集成平台属性	建议映射方式	说明
id	connector_org_id	创建且更新	部门唯一标识，必须映射
name	name	创建且更新	部门名称
parentid	parentRefId	创建且更新	父部门 ID，用于构建部门层级关系
order	seq	创建且更新	部门排序值，决定同级部门的显示顺序
dept_manager_userid	manager	创建且更新	部门负责人 ID

重要：parentid 的映射至关重要，错误的映射会导致部门层级混乱或循环引用。

步骤 4：配置角色属性映射

如在前置步骤中选择了角色集成（角色集成类型设为“按角色集成”或“按角色组集成”），在「角色」选项卡中配置钉钉角色属性与平台角色属性的映射关系。

角色属性映射表

钉钉属性	专属集成平台属性	建议映射方式	说明
id	connector_role_id	创建且更新	角色唯一标识，必须映射
name	name	创建且更新	角色名称
groupid	parentRefId	创建且更新	角色组 ID，用于角色分组

提示：如不需要同步角色信息，可在同步策略中将「角色集成类型」设为“不集成”。

步骤 5：配置扩展字段映射

对于钉钉中的自定义字段，可以通过扩展字段映射进行配置：

配置方式：

在钉钉中定义的扩展字段可以通过 API 获取

在属性映射中，使用相应的字段名进行映射

映射格式通常为：appuser.extension.字段名

示例：

钉钉扩展字段	映射表达式	说明
护照	appuser.extension.护照	将钉钉自定义“护照”字段映射到平台扩展属性
入职日期	appuser.extension.入职日期	将钉钉自定义“入职日期”字段映射到平台扩展属性
工龄	appuser.extension.工龄	将钉钉自定义“工龄”字段映射到平台扩展属性

注意：扩展字段名称必须与钉钉中定义的字段名完全一致（包括大小写和字符）。

验证与测试

属性映射验证方法

验证步骤	操作方法
字段映射完整性检查	逐一核对各选项卡中的映射配置，确保核心字段已正确映射
连接测试验证	在连接测试中选择信息完整的用户账号，验证返回数据中各字段能否正常匹配
同步结果验证	执行手动全量同步后，在「用户管理」页面抽查用户信息的完整性和准确性
增量更新验证	在上游修改某用户属性后触发同步，确认修改能被正确捕获并更新

常见映射错误排查

错误现象	可能原因	解决方法
同步后用户名称为空	name 字段未映射或映射方式为“不映射”	将 name 字段映射方式设为“创建且更新”
同步后手机号为空	mobile 字段未映射或上游用户无手机号数据	检查映射配置，确保上游数据包含手机号
部门层级混乱	parentid 映射错误	检查 department 和 parentid 的映射是否正确
用户无法关联	sub 字段映射错误	确保 userid 正确映射到 sub 字段

注意事项

注意事项	说明
唯一标识字段必须映射	用户（userid → sub）和部门（id → connector_org_id）的唯一标识字段为必填映射
核心字段使用创建且更新	姓名、手机号、邮箱等核心字段建议使用“创建且更新”模式
自定义字段需精确匹配	扩展字段名称必须与钉钉中定义的字段名完全一致
避免敏感信息同步	对于包含敏感信息的字段，使用“不映射”方式
先测试后全量	配置完成后先进行小范围测试，验证无误后再执行全量同步

常见问题

问题	解决方案
属性映射保存后未生效	点击「保存」后需要重新执行一次同步，映射变更才会在后续同步中生效
新增自定义字段无法映射	确认自定义字段在钉钉开放平台中已正确配置并可正常获取
部门负责人显示异常	检查 dept_manager_userid 映射是否正确，确认负责人用户已同步至平台
角色数据未同步	确认同步策略中「角色集成类型」已选择“按角色集成”或“按角色组集成”

钉钉集成连接器如何配置属性映射

概述#

前提条件#

操作步骤#

步骤 1：了解属性映射方式#

步骤 2：配置用户属性映射#

用户属性映射表#

步骤 3：配置部门属性映射#

部门属性映射表#

步骤 4：配置角色属性映射#

角色属性映射表#

步骤 5：配置扩展字段映射#

验证与测试#

属性映射验证方法#

常见映射错误排查#

注意事项#

常见问题#

概述