MDM API 参考

本页用于规划 DFS MDM 集成和自动化验证。精确请求与响应字段应以部署环境中的实时 API 规格为准。

访问前提

• 已确认认证方式。
• 已确认 tenant scope。
• 查看需要 dfs:read。
• 创建、更新和审阅动作需要 dfs:write。
• merge 和 split 等结构性动作只应授予有治理责任的用户。
• 需要时确认 DFS Pro package gate。

请求约定

精确 schema 以部署环境中的 OpenAPI 或 API console 为准。做集成规划时，先对齐以下约定：

约定	建议
Tenant scope	每次读写都应在正确 tenant 或项目边界内执行。
Source system key	使用稳定的业务域 key，例如 bms、cmms、inspection，让集成共享同一 namespace。
External ID	保留源系统的 durable ID，便于重复解析 alias。
Idempotency	Reference sets、entity types 和 source aliases 应使用确定性 key，避免重试产生重复。
Audit reason	部署环境支持时，结构性写入应包含 requester、reason 或 change note。
Time validity	当 source ID 可能复用或设备可能替换时，传入 valid-from 和 valid-to。

List endpoint 应规划分页，并按 entity type、status、source system、updated time 和 steward decision state 过滤。大规模集成应增量读取，而不是反复拉取整个 MDM store。

Reference data APIs

区域	Endpoint family	用途
Reference sets	/api/v1/dfslite/mdm/reference-sets	列出和创建 reference sets。
Set detail	/api/v1/dfslite/mdm/reference-sets/{key}	按 key 读取 set。
Version bump	/api/v1/dfslite/mdm/reference-sets/{key}/bump-version	重要变更后提升版本。
Values	/api/v1/dfslite/mdm/reference-sets/{key}/values	列出和新增 values。
Value detail	/api/v1/dfslite/mdm/reference-sets/{key}/values/{valueId}	更新或删除单个 value。

Entity and alias APIs

区域	Endpoint family	用途
Entity types	/api/v1/dfslite/mdm/entity-types	列出或创建 entity types。
Entity type detail	/api/v1/dfslite/mdm/entity-types/{typeKey}	读取一个 entity type。
Entities	/api/v1/dfslite/mdm/entities	列出或创建 golden records。
Entity detail	/api/v1/dfslite/mdm/entities/{id}	读取一个 golden record。
Aliases	/api/v1/dfslite/mdm/entities/{id}/aliases	查看某个实体的 source aliases。
Resolve	/api/v1/dfslite/mdm/xref/resolve	将 source-system ID 解析为 entity ID。
Upsert alias	/api/v1/dfslite/mdm/xref	创建或 re-point source alias。

安全写入 alias

自动写入 alias 前：

1. 先 resolve source-system ID。
2. 检查 active mapping 是否已经指向预期 entity。
3. 对冲突映射使用批准后的 re-point 工作流。
4. 当 alias 因设备替换、split 或 merge 发生变化时，保留旧映射历史。
5. 重新验证依赖 master entity ID 的下游数据集。

Alias 写入是受治理的身份变更，不应被当作普通数据清洗捷径。

Steward APIs

区域	Endpoint family	用途
Fuzzy candidates	/api/v1/dfslite/mdm/fuzzy-candidates	按 type 和 status 查询候选。
Approve	/api/v1/dfslite/mdm/fuzzy-candidates/{id}/approve	确认候选并创建 alias。
Reject	/api/v1/dfslite/mdm/fuzzy-candidates/{id}/reject	拒绝候选并记录 negative decision。
Merge	/api/v1/dfslite/mdm/entities/{loserId}/merge-into/{survivorId}	将重复实体合并到 survivor。
Split	/api/v1/dfslite/mdm/entities/{entityId}/split	将选中 aliases 移动到新实体。

Steward 自动化边界

自动化可以查询候选、预筛队列，并为审阅人附加证据。批准和拒绝应遵循客户治理策略。对高影响 entity type，保留人工决策步骤，并记录足够审计证据。

查询候选时，优先使用 entity type、status、source system、score range、created time 和 updated time 等过滤条件，避免把无关 entity type 混在一个 steward queue 中。

集成检查清单

• 使用稳定 source-system names。
• entity type key 使用跨环境稳定的业务域命名。
• entity resolution 前先验证 reference sets。
• 先用小范围 source slice 测试。
• 明确 steward queue owner。
• 写操作记录 requester、reason 和 downstream impact。
• 不绕过 fuzzy match 审阅。
• 结构性动作后重新验证融合和报表。
• 读操作可以安全重试，写操作重试前要确认幂等性。
• 对重复 alias conflict 或 fuzzy candidates 突增设置告警。
• 当 MDM output 进入 AI Agent、Inspector、BI 或工单集成时，附带 run ID 或 task name。

常见错误

现象	可能原因	处理
403 或操作不可见	权限或 package gate 缺失。	确认 dfs:read、dfs:write、dfs:delete 和 DFS Pro access。
Unknown entity type	tenant 中尚未创建该类型。	创建或选择正确 type。
Alias conflict	source ID 已有 active mapping。	使用批准流程 re-point 或关闭旧映射。
Steward queue 为空	没有候选、filter 错误或未生成 fuzzy matches。	检查 resolver run result 和筛选条件。
Merge blocked	源或目标实体不适合结构性变更。	确认记录存在、tenant 一致且状态符合预期。
实体数量异常增长	源 key 不稳定或 deterministic matching 太弱。	重新审阅源映射、必填字段和 resolver configuration。
误报候选反复出现	Resolver context 中缺少 rejected-pair memory。	在下一次 resolver run 中纳入既有 steward decisions。
下游报表意外变化	Alias、merge 或 split 改变了 fusion task 使用的 master entity ID。	比较变更前后的 row movement，审阅后再刷新。

响应处理

生产集成中：

• 将 4xx 视为配置、权限、校验或治理问题，需要人工检查；
• 将 5xx 视为服务或依赖的临时故障，安全请求可采用 backoff 重试；
• 结构性写入重试前，先确认第一次请求是否已经提交；
• 客户端日志应包含 request ID、tenant、endpoint family、entity type、source system 和 operation result；
• 上线期间将 retry 与 failure counts 暴露给运营团队。

下一步

继续阅读 DFS API Surface。