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 前：
- 先 resolve source-system ID。
- 檢查 active mapping 是否已經指向預期 entity。
- 對衝突對應使用批准後的 re-point 工作流。
- 當 alias 因設備替換、split 或 merge 發生變化時，保留舊對應歷史。
- 重新驗證依賴 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。