MDM API リファレンス
このページは DFS MDM の統合と自動検証を計画するための endpoint map です。正確なリクエストとレスポンスのフィールドは、導入環境の live API 仕様を基準にしてください。
アクセス前提
- 認証方式を確認します。
- tenant scope を確認します。
- 表示には
dfs:readが必要です。 - 作成、更新、レビュー操作には
dfs:writeが必要です。 - merge と split などの構造変更はガバナンス責任を持つユーザーに限定します。
- 必要に応じて DFS Pro package gate を確認します。
リクエスト規約
正確な schema は導入環境の OpenAPI または API console を基準にします。統合計画では、実装前に次の規約をそろえます。
| 規約 | ガイダンス |
|---|---|
| Tenant scope | すべての読み書きは対象 tenant またはプロジェクト境界内で実行します。 |
| Source system key | bms、cmms、inspection など安定した key を使い、環境名や一時プロジェクト名は使いません。 |
| External ID | alias を繰り返し解決できるよう、ソースシステムの durable ID を保持します。 |
| Idempotency | Reference sets、entity types、source aliases には deterministic key を使い、再試行で重複を作らないようにします。 |
| Audit reason | 導入環境が対応する場合、構造変更の書き込みには requester、reason、change note を含めます。 |
| Time validity | source ID が再利用される、または設備が交換される場合は valid-from と valid-to を送ります。 |
List endpoint では paging を前提にし、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 | 重要変更後に version を上げます。 |
| Values | /api/v1/dfslite/mdm/reference-sets/{key}/values | values を一覧、追加します。 |
| Value detail | /api/v1/dfslite/mdm/reference-sets/{key}/values/{valueId} | 1 つの 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} | 1 つの entity type を読み取ります。 |
| Entities | /api/v1/dfslite/mdm/entities | golden records を一覧または作成します。 |
| Entity detail | /api/v1/dfslite/mdm/entities/{id} | 1 つの 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 | source alias を作成または re-point します。 |
安全な alias 書き込み
alias を自動で書き込む前に確認します。
- 先に source-system ID を resolve します。
- active mapping が期待する entity を指しているか確認します。
- 競合する mapping は承認済みの re-point ワークフローで扱います。
- 交換、split、merge により alias が変わる場合は旧 mapping の履歴を保持します。
- master entity ID に依存する下流データセットを再検証します。
alias 書き込みは管理された ID 変更です。一般的なデータクリーニングの近道として使わないでください。
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 に merge します。 |
| 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 のレビューを迂回しません。
- 構造変更後に融合とレポートを再検証します。
- 読み取り操作は安全に再試行できますが、書き込み再試行は idempotency を確認してから実行します。
- 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 が弱い。 | ソース mapping、必須フィールド、resolver configuration を見直します。 |
| 誤候補が繰り返し出る | resolver context に rejected-pair memory が含まれていない。 | 次回 resolver run に既存の steward decisions を含めます。 |
| 下流レポートが予期せず変わる | alias、merge、split により fusion task が使う master entity ID が変わった。 | 変更前後の row movement を比較し、レビュー後に更新します。 |
レスポンス処理
本番統合では次の扱いにします。
4xxは設定、権限、検証、ガバナンスの問題としてレビューします。5xxはサービスまたは依存先の一時障害として扱い、安全なリクエストは backoff 付きで再試行します。- 構造変更の書き込みを再試行する前に、最初の試行が commit 済みか確認します。
- クライアントログには request ID、tenant、endpoint family、entity type、source system、operation result を含めます。
- 導入中は retry と failure counts を運用チームに見えるようにします。
次に読む
DFS API Surface を参照してください。