統合カタログエンティティの作成¶
POST /api/v1/unified_catalog/entity/create
概要¶
タイプと名前を指定して、カタログエンティティとその関係、タグ、テレメトリ関連付けを作成または更新します。
呼び出し前の準備と使用手順¶
まずタイプ一覧からエンティティタイプコードを取得し、対応する DataSchema に従って属性を入力します。現在のエントリは 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 検証を項目ごとに実行せず、HTTP 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 を新規生成しません。 |
パラメータ補足説明¶
リクエストパラメータ説明
| パラメータ名 | type | 必須 | 説明 |
|---|---|---|---|
| entityType | string | 必須 | エンティティタイプコード |
| name | string | 必須 | エンティティ名 |
| attributes | json | 任意 | エンティティ属性オブジェクト |
| telemetrySelectors | array | 任意 | エンティティ関連クエリ設定 |
attributes のよく使用される拡張フィールド説明
| フィールド名 | type | 説明 |
|---|---|---|
| depends_on | array[string] | 依存関係。書き込み時に links に変換されます |
| component_of | array[string] | 帰属関係。書き込み時に contains に変換され、方向は parent/system -> 現在のエンティティです |
| components | array[json/string] | 構成エンティティ一覧。書き込み時にも contains に変換され、方向は現在のエンティティ -> component です |
| custom_tags | array/string | カスタムタグ。タグが存在しない場合は自動的に作成されます |
| owner | string/array | チーム名。バックエンドがチーム名に基づいてチーム情報を解決します |
呼び出し時の注意事項
- 関係フィールドはすべて
attributes内で渡します。relations を個別に渡す必要はありません。 attributes.componentsは文字列配列、またはentityを含むオブジェクト配列を渡せます。オブジェクト内のその他のフィールドはエンティティの attributes に保持されます。custom_tagsを渡す場合は、タグ名の配列を使用することを推奨します。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/create' \
-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"]}}'
レスポンス¶
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 で属性と関係を読み戻し、タグおよび有効なヘルス状態を確認してから再試行を判断してください。名前を変えて盲目的に再作成しないでください。 |