統合カタログエンティティの変更¶
POST /api/v1/unified_catalog/entity/modify
概要¶
タイプと名前を指定して、カタログエンティティとその関係、タグ、テレメトリ関連付けを作成または更新します。
呼び出し前の準備と使用手順¶
変更時は、まず get でバックアップし、元の urn、entityType、name、および保持する必要がある完全な属性をバックフィルする必要があります。このエンドポイントと作成はどちらも ingest/upsert を呼び出し、厳密な存在性更新ではありません。見つからない場合でも作成される可能性があり、urn を省略したまま名前を変更すると、新しいエンティティが形成される可能性があります。
関係は attributes.depends_on/component_of/components にのみ格納し、本ページの方向に従って links/contains を生成します。関係 URN は短縮表記でき、正規化されます。components オブジェクトの追加キーは保持されます。関係をクリアするには明示的に [] を指定する必要があり、省略でクリアを表さないでください。owner はアクティブなチーム名で解決され、存在しないタグは自動的に作成されます。属性/テレメトリ構造はビジネス Schema に従って項目ごとに検証されません。任意の拡張設定の保存成功を実行成功と見なさないでください。telemetrySelectors は非空の場合のみ転送され、[] は既存値のクリアを保証できません。
返される urn は今回の書き込み呼び出しで取得した識別子のみを表し、完全なエンティティや非同期処理のすべての完了を示すものではありません。公開チェーンには、AIAPI 専用アダプターによる読み取りマージ/下流完了検証の保証がありません。必ず get/list で読み戻してください。タグデータベース、エンティティ/関係の書き込み、ヘルスリセットはサービス間のアトミックトランザクションではありません。失敗すると部分的に成功した状態が残る可能性があります。ヘルスが disabled の書き込み後、同期的に結果のリセットを試行し、失敗すると補償を配信してエラーを報告します。計算関数はこのインターフェースでは即時実行されません。
すべてのエンティティタイプは有効なヘルス設定に従って処理され、バックグラウンドの履歴クリーンアップの進行状況には依存しません。system でタイプポリシーが未設定の場合はデフォルトで default、その他のタイプで未設定の場合はデフォルトで disabled です。エンティティの inherit はタイプを継承し、custom は Func を指定し、disabled は無効化します。タイプを無効化すると healthScore=null、healthStatus=unknown、healthUpdateAt=null が返され、ヘルスフィルター/統計も履歴結果ではなく無効状態に従います。フィルター/ソート/統計でトップレベルのヘルスフィールドを使用する場合は、entityType を明示する必要があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| attributes.カスタムフィールド | JSON | 動的なビジネスフィールド。タイプ定義に従って送信します。Studio は DataSchema 検証を項目ごとに実行せず、200 レスポンスによって任意の拡張フィールドが正しく収集/クエリ可能であることを保証しません。 例: prod取得または入力方法: フィールド名、型、ソースは対応するタイプの DataSchema と既存エンティティの元の属性を参照してください。 |
|
| attributes.depends_on | array<string> | 任意。現在のエンティティから対象を指す links 関係を書き込みます。完全な URN またはタイプ:名前(default 名前空間を補完)をサポートします。明示的な [] はこの関係グループのクリアを要求します。省略した場合、他の履歴関係を上書きすることは保証されません。 例: ["service:api"]取得または入力方法: このワークスペースのエンティティ一覧から依存対象の URN を取得します。 |
|
| attributes.depends_on[*] | string | 前後の空白を除去し、urn:タイプ:default:名前 に正規化します。表示名やワークスペース間の UUID は使用しないでください。 例: service:api取得または入力方法: 単一の依存対象 URN/タイプ:名前。 |
|
| attributes.component_of | array<string> | 任意。親エンティティから現在のエンティティへの contains 関係を書き込みます。[] はクリアを要求し、複数の親項目は関係ごとに重複排除されます。 例: ["system:payments"]取得または入力方法: このワークスペースのシステム/親エンティティ一覧から URN を取得します。 |
|
| attributes.component_of[*] | string | 方向は親→現在です。短縮表記では default 名前空間を補完します。 例: system:payments取得または入力方法: 単一の親エンティティ/システム URN。 |
|
| attributes.components | array<string または object> | 任意。方向は現在→子エンティティの contains です。[] はクリアを要求します。文字列項目または entity を含むオブジェクトです。オブジェクトの追加フィールドは attributes に保持され、詳細関連の contains 関係にこれらの設定を付帯できます。 例: ["database:demo"]取得または入力方法: 現在のエンティティの構成メンバー一覧から子エンティティ URN を取得します。元の詳細属性からオブジェクトの拡張設定をバックフィルできます。 |
|
| attributes.components[*] | string または object | オブジェクト項目は entity で対象を特定し、その他の設定は顧客定義/対応する計算機能によって消費されます。任意のフィールドを厳密に検証済みと見なさないでください。 例: {"entity": "database:demo", "required": true}取得または入力方法: 単一の構成エンティティ URN、または元のコンポーネント設定オブジェクト。 |
|
| attributes.components[*].entity | string | オブジェクト形式では業務上必須です。短縮表記は属性および関係の保存時に正規化されます。 例: database:demo取得または入力方法: 単一の子エンティティ URN。 |
|
| attributes.components[*].拡張設定 | JSON | 動的な追加設定は保持されます。統一されたサーバー側のデフォルト/列挙は存在しません。依存重みなどのフィールドを手動で考案しないでください。 例: true取得または入力方法: 元のコンポーネント設定、または実際のヘルス計算/ビューの要件から取得します。 |
|
| attributes.custom_tags | array<string> | 文字列名の配列を推奨します。カンマ区切り文字列/オブジェクトキーとも互換性があります。空白を除去して重複排除します。存在しないタグは自動的に作成され、クエリのみではありません。[] は今回作成するタグがないことを意味します。エンティティ属性の保持ロジックでは、事前に元の値をバックアップする必要があります。 例: ["mysql"]取得または入力方法: タグ一覧から名前を選択するか、業務側が新しい名前を提供します。 |
|
| attributes.custom_tags[*] | string | 新しい名前は対応するタグを作成でき、タグ名およびスコープ規則の制約を受けます。 例: mysql取得または入力方法: 単一のこのワークスペースのタグ名であり、tag_ UUID ではありません。 |
|
| attributes.owner | string または array<string> | 書き込み時はチーム名で正確に解決されます。すべての非空名が存在する必要があり、存在しない場合は 404 チームが存在しませんとなり、チームは自動作成されません。空文字列/[] はクリアします。個人メールアドレス/アカウント UUID ではありません。履歴読み取りでは group_ 参照と互換性があります。 例: ["DBA"]取得または入力方法: チーム一覧から現在のワークスペースのアクティブなチームの name を取得します。 |
|
| attributes.owner[*] | string | 名前は空白を除去し、最初の出現に基づいて重複排除します。大文字/小文字は実際の名前の比較に従います。 例: DBA取得または入力方法: 単一の既存のアクティブなチーム名。 |
|
| attributes.health_calculation | string | 任意。inherit/custom/disabled。inherit はタイプを継承し、custom は同時に func_id が必要で、disabled はこのエンティティを無効化します。func_id のみを指定した場合は custom として互換処理されます。いずれかのヘルスフィールドが出現すると業務検証/ロックを実行します。どちらも渡さない場合は新たな必須制約を追加しません。タイプが disabled の場合はエンティティの有効状態を上書きします。 例: inherit取得または入力方法: 呼び出し元がエンティティの上書きポリシーを選択します。タイプのデフォルトポリシーはタイプ詳細の healthConfig から確認できます。 |
|
| attributes.func_id | string | custom の場合は必須で、削除されていない関数が存在する必要があります。inherit/disabled では空文字列を書き込みます。関数の表示名、スクリプトソース、リモート URL ではありません。このインターフェースは関数を即時実行して出力を検証しません。 例: func_example取得または入力方法: このワークスペースの Func 関数管理からアクティブな関数 UUID を取得し、関数がヘルススコアの入力/出力規約を満たすことを確認します。 |
|
| telemetrySelectors[*] | JSON | 動的な関連付け項目。公開エンドポイントでは統一された厳密検証のサブ構造を定義していません。source/query は既存の利用例を示すものにすぎず、唯一の必須基準と見なすことはできません。 例: {"source": "logging", "query": "service:api"}取得または入力方法: 検証済みのテレメトリ関連付け元設定から全体をコピーします。フィールドは消費側によって異なります。 |
|
| telemetrySelectors[*].source | string | 拡張キーの例示であり、公開された統一必須項目ではありません。実際の関連付けを消費する機能がサポートする値に従います。 例: logging取得または入力方法: 既存設定のテレメトリカテゴリ/ソース。 |
|
| telemetrySelectors[*].query | string | 拡張キーの例示であり、形式は消費側によって異なります。保存時にクエリを実行したり、実行可能であることを検証したりしません。 例: service:api取得または入力方法: 既存設定のクエリ/選択式。 |
|
| attributes | json | 任意の動的オブジェクト。省略時は {} を ingest に渡します。公開フローは現在のオブジェクトを直接送信し、元の属性を読み取って安全にディープマージする保証はありません。変更時はまず get し、保持が必要な属性をバックフィルする必要があります。healthScore などの読み取り専用の計算結果はバックフィルしないでください。 null を許可: False 例: {"project": "demo", "env": "prod", "custom_tags": ["mysql"]}取得または入力方法: エンティティタイプの schemaDefine/effectiveSchemaDefine に従って実際の属性値を提供するか、元の詳細 attributes からバックアップします。 |
|
| entityType | string | Y | 一覧/統計では任意。トップレベルのヘルスフィールドでフィルター、統計、ソートを行う場合は業務上必須です。作成/変更では必須で、空白除去後に非空である必要があります。エクスポートでは必須です。 null を許可: False 例: database取得または入力方法: エンティティタイプ一覧の items[].entityType からコードを取得します。タイプ UUID/表示名ではありません。 |
| name | string | Y | 作成/変更では必須で、前後の空白除去後に非空である必要があります。URN ではありません。名前変更時は同時に元の urn をバックフィルします。urn を渡さない書き込みでは、下流がアイデンティティに基づいてロケーションを生成します。 null を許可: False 例: demo取得または入力方法: 呼び出し元がエンティティの業務名を提供し、既存の詳細 name からバックフィルして変更します。 |
| telemetrySelectors | array | 任意の配列。要素は関連付けを消費する側の設定規約に従って保持されます。非空の場合のみ ingest に転送します。省略と [] のどちらも telemetry_selectors を渡さないため、[] で古い関連付けのクリアを約束することはできません。 null を許可: False 例: []取得または入力方法: 現在のエンティティのテレメトリ関連付け設定、または関連タイプの extraConfig にある既存設定から取得します。このインターフェースから DQL を新規生成しないでください。 |
|
| urn | string | 読み取り/削除では必須で、前後の空白除去後に非空である必要があります。一覧/統計では任意の精密フィルターです。変更時は元の URN を明示的に入力し、名前変更時に別のエンティティが作成されるのを避けることを推奨します。 null を許可: False 例: urn:database:default:demo取得または入力方法: このワークスペースのエンティティ一覧 items[].urn から取得し、完全な URN をそのまま使用することを優先します。 |
パラメータ補足説明¶
リクエストパラメータ説明
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| urn | string | 任意 | エンティティ URN。正確にエンティティを特定するために指定を推奨します |
| entityType | string | 必須 | エンティティタイプコード |
| name | string | 必須 | エンティティ名 |
| attributes | json | 任意 | 更新するエンティティ属性オブジェクト |
| telemetrySelectors | array | 任意 | 更新するエンティティ関連付けクエリ設定 |
関係フィールドの使用説明
attributes.depends_onはlinksとして書き込まれます。attributes.component_ofはcontainsとして書き込まれ、方向は parent/system -> 現在のエンティティです。attributes.componentsもcontainsとして書き込まれ、方向は現在のエンティティ -> component です。- 関係をクリアする場合は、明示的に空配列を渡してください。例:
{"component_of":[]}または{"components":[]}。
呼び出し時の注意事項
urn、entityType、nameを同時に渡すことを推奨します。- 変更成功後、対象エンティティの
urnを返します。 - タグフィールドに新しいタグ名を渡した場合も、対応するタグが自動的に作成されます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"entityType":"database","name":"demo","attributes":{"env":"prod","project":"demo","custom_tags":["mysql"]},"urn":"urn:database:default:demo"}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.urn | string | ingest が返すエンティティ URN。異常な成功形状では空文字列の可能性があるため、必ず読み戻して受け入れ確認を行う必要があります。 |
| content.declaration | object | 共通宣言。 |
{
"code": 200,
"content": {
"urn": "urn:database:default:demo",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
下流エラーは Kodo の共有マッピングに従い、4xx は実際の HTTP および ft.KodoCommonApiErr またはマッピング済みの業務コードを返す場合があります。すべての失敗が 406 に変換されるわけではありません。パススルーされない 5xx/接続例外/成功結果の構造不一致は最終的に 500 ft.InternalServerError になります。errorCode/message/traceId を保持し、読み取りまたは書き込みフェーズに応じて処理してください。成功 HTTP はエンティティの実際の可視性の受け入れ確認に代わるものではありません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | Body のトップレベルが JSON オブジェクトではない | 一部の json ファイル形式エラー | 配列/文字列ではなく、例に従ってオブジェクトを送信してください。 |
| 406 | ft.ExceedMaxCharacterLimit | 自動作成されるタグ名が重み付き文字長制限を超えている | {}が最大文字長制限を超えています | タグ仕様に適合する短い名前を使用し、長すぎるタグを避けてください。まずエンティティが既に書き込まれているか確認してください。 |
| 406 | ft.InvalidParameter | entityType/name が空白除去後に空、またはヘルス上書きモード/Func が無効 | パラメータ{}が無効 |
既存のタイプ、非空の名前を使用してください。custom はこのワークスペースの削除されていない Func をバインドし、inherit/disabled では古い func_id を残さないでください。 |
| 404 | ft.NotFound | owner にこのワークスペースに存在しない/非アクティブなチーム名が含まれている | チームが存在しません: {チーム名} |
チーム一覧からアクティブなチーム名を取得してください。ここでは個人メールアドレス/アカウント UUID は受け付けません。 |
| 429 | ft.OperationTooFrequently | ヘルス上書きフィールドを伴う並行書き込みがミューテックスロックを取得できなかった | 操作が頻繁すぎます。しばらくしてから再試行してください | しばらくしてから限定的なバックオフで再試行し、先に対象を読み戻して、重複作成を避けてください。 |
| 500 | ft.InternalServerError | 下流の書き込み/書き込み後読み取り、タグ永続化、ヘルスリセット/補償、キャッシュロック、または形式処理の失敗 | 内部エラー | 書き込みが既に発生している可能性があります。元の URN で属性と関係を読み戻し、タグおよび有効なヘルス状態を確認してから再試行を判断してください。むやみに名前を変えて再作成しないでください。 |