MDM API 参考
本页用于规划 DFS MDM 集成和自动化验证。精确请求与响应字段应以部署环境中的实时 API 规格为准。
访问前提
- 已确认认证方式。
- 已确认 tenant scope。
- 查看需要
dfs:read。 - 创建、更新和审阅动作需要
dfs:write。 - merge 和 split 等结构性动作只应授予有治理责任的用户。
- 需要时确认 DFS Pro package gate。
请求约定
精确 schema 以部署环境中的 OpenAPI 或 API console 为准。做集成规划时，先对齐以下约定：
| 约定 | 建议 |
|---|---|
| 租户范围 | 每次读写都应在正确租户或项目边界内执行。 |
| 源系统标识 | 使用稳定的业务域标识，例如 bms、cmms、inspection，让多个集成共享同一命名空间。 |
| 外部 ID | 保留源系统中可长期追踪的 ID，便于重复解析别名。 |
| 幂等性 | 参考集、实体类型和源系统别名应使用确定性标识，避免重试产生重复记录。 |
| 审计原因 | 部署环境支持时，结构性写入应包含请求人、原因或变更说明。 |
| 时间有效性 | 当源系统 ID 可能复用或设备可能替换时，传入有效起止时间。 |
上线前应先确认列表接口的分页和筛选能力。大规模集成应增量读取，而不是反复拉取整个 MDM 存储。
当前已暴露的筛选项：
| 接口族 | 当前筛选项 |
|---|---|
/api/v1/dfslite/mdm/entities | type 必填；page 和 size 控制分页。 |
/api/v1/dfslite/mdm/fuzzy-candidates | type、status、page、size。 |
/api/v1/dfslite/fault-fusion/candidates | status、page、size。 |
/api/v1/dfslite/mdm/reference-sets | 列出租户内全部参考集。 |
解析器与队列交接边界
MDM 解析器运行和故障事件融合运行可以使用后台或 staged handoff。此时面向客户端的运行响应是摘要，受治理结果通过 MDM、人工审阅、数据集或运行历史 API 查看。
| 工作流 | 写入边界 | 读取或审阅边界 |
|---|---|---|
| 实体解析 | 平台通过 MDM 服务持久化主记录、源系统别名、模糊候选和审计记录。 | 通过 MDM 与运行历史 API 查看实体、别名、模糊候选和运行数量。 |
| 故障事件融合 | 融合工作流创建重复事件候选，并记录 persisted 或 skipped candidate 数量。 | 通过故障融合候选 API 查询和处理候选。 |
| 审阅后下游输出 | 已审阅身份或事件分组可以被数据集、BI、Inspector、AI Agent 或其他运营工作流消费。 | 使用审阅后的数据集、entity ID、event group ID 和血缘。 |
大规模实施中，客户端逻辑应围绕分页读取、队列审阅、血缘和运行指标设计，以保持重试、审计和权限行为与平台一致。
参考数据 APIs
| 区域 | 接口族 | 用途 |
|---|---|---|
| 参考集 | /api/v1/dfslite/mdm/reference-sets | 列出和创建参考集。 |
| 参考集详情 | /api/v1/dfslite/mdm/reference-sets/{key} | 按 key 读取参考集。 |
| 版本提升 | /api/v1/dfslite/mdm/reference-sets/{key}/bump-version | 重要变更后提升版本。 |
| 参考值 | /api/v1/dfslite/mdm/reference-sets/{key}/values | 列出和新增参考值。 |
| 参考值详情 | /api/v1/dfslite/mdm/reference-sets/{key}/values/{valueId} | 更新或删除单个参考值。 |
实体与别名 APIs
| 区域 | 接口族 | 用途 |
|---|---|---|
| 实体类型 | /api/v1/dfslite/mdm/entity-types | 列出或创建实体类型。 |
| 实体类型详情 | /api/v1/dfslite/mdm/entity-types/{typeKey} | 读取一个实体类型。 |
| 主数据实体 | /api/v1/dfslite/mdm/entities | 列出或创建主记录。 |
| 实体详情 | /api/v1/dfslite/mdm/entities/{id} | 读取一条主记录。 |
| 源系统别名 | /api/v1/dfslite/mdm/entities/{id}/aliases | 查看某个实体的源系统别名。 |
| 解析 | /api/v1/dfslite/mdm/xref/resolve | 将源系统 ID 解析为实体 ID。 |
| 写入别名 | /api/v1/dfslite/mdm/xref | 创建别名或把别名指向新的实体。 |
公开解析接口处理当前生效的精确 (实体类型、源系统、源 ID) 查询。按时间点解析、批量解析和归一化别名解析用于 DFS 融合路径或模块桥接；除非实时 API 规格明确暴露，不应把这些能力当作公开 REST 字段使用。
安全写入别名
自动写入别名前：
- 先解析源系统 ID。
- 检查当前生效映射是否已经指向预期实体。
- 对冲突映射使用批准后的重定向工作流。
- 当别名因设备替换、拆分或合并发生变化时，保留旧映射历史。
- 重新验证依赖主数据实体 ID 的下游数据集。
别名写入是受治理的身份变更，不应被当作普通数据清洗捷径。
人工审阅 APIs
| 区域 | 接口族 | 用途 |
|---|---|---|
| 模糊候选 | /api/v1/dfslite/mdm/fuzzy-candidates | 按类型和状态查询候选。 |
| 批准候选 | /api/v1/dfslite/mdm/fuzzy-candidates/{id}/approve | 确认候选并创建别名。 |
| 拒绝候选 | /api/v1/dfslite/mdm/fuzzy-candidates/{id}/reject | 拒绝候选并记录负向决策。 |
| 合并 | /api/v1/dfslite/mdm/entities/{loserId}/merge-into/{survivorId} | 将重复实体合并到保留实体。 |
| 拆分 | /api/v1/dfslite/mdm/entities/{entityId}/split | 将选中的源系统别名移动到新实体。 |
故障事件融合 APIs
故障事件融合使用独立的审阅接口处理重复故障事件候选：
| 区域 | 接口族 | 用途 |
|---|---|---|
| 故障候选 | /api/v1/dfslite/fault-fusion/candidates | 按状态查询重复事件候选。 |
| 批准候选 | /api/v1/dfslite/fault-fusion/candidates/{id}/approve | 确认候选记录描述同一事件。 |
| 拒绝候选 | /api/v1/dfslite/fault-fusion/candidates/{id}/reject | 拒绝重复关系，保留为独立事件。 |
事件去重审阅使用这组 API；主数据实体身份审阅使用 MDM 模糊候选 API。
人工审阅自动化边界
自动化可以查询候选、预筛队列，并为审阅人附加证据。批准和拒绝应遵循客户治理策略。对高影响实体类型，保留人工决策步骤，并记录足够审计证据。
查询候选时，优先使用类型、状态和分页等已暴露筛选项，避免把无关实体类型混在一个审阅队列中。
集成检查清单
- 使用稳定的源系统名称。
- 实体类型 key 使用跨环境稳定的业务域命名。
- 实体解析前先验证参考集。
- 先用小范围源数据切片测试。
- 明确人工审阅队列 owner。
- 写操作记录请求人、原因和下游影响。
- 不绕过模糊匹配审阅。
- 结构性动作后重新验证融合和报表。
- 读操作可以安全重试，写操作重试前要确认幂等性。
- 对重复别名冲突或模糊候选突增设置告警。
- 当 MDM 输出进入 AI Agent、Inspector、BI 或工单集成时，附带运行 ID 或任务名。
常见错误
| 现象 | 可能原因 | 处理 |
|---|---|---|
403 或操作不可见 | 权限或 package gate 缺失。 | 确认 dfs:read、dfs:write、dfs:delete 和 DFS Pro 访问权限。 |
| 未知实体类型 | 租户中尚未创建该类型。 | 创建或选择正确类型。 |
| 别名冲突 | 源 ID 已有生效映射。 | 使用批准流程重定向或关闭旧映射。 |
| 人工审阅队列为空 | 没有候选、筛选条件错误或未生成模糊候选。 | 检查解析任务运行结果和筛选条件。 |
| 合并被阻止 | 源或目标实体不适合结构性变更。 | 确认记录存在、租户一致且状态符合预期。 |
| 实体数量异常增长 | 源 key 不稳定或确定性匹配太弱。 | 重新审阅源映射、必填字段和解析配置。 |
| 误报候选反复出现 | 解析上下文中缺少已拒绝关系记忆。 | 在下一次解析任务中纳入既有人工审阅决策。 |
| 下游报表意外变化 | 别名、合并或拆分改变了融合任务使用的主数据实体 ID。 | 比较变更前后的下游行变动，审阅后再刷新。 |
响应处理
生产集成中：
- 将
4xx视为配置、权限、校验或治理问题，需要人工检查； - 将
5xx视为服务或依赖的临时故障，安全请求可采用退避策略重试； - 结构性写入重试前，先确认第一次请求是否已经提交；
- 客户端日志应包含 request ID、租户、接口族、实体类型、源系统和操作结果；
- 上线期间将重试和失败次数暴露给运营团队。
下一步
继续阅读 DFS API Surface。