統合カタログのエンティティタイプ変更¶
POST /api/v1/unified_catalog/entity_type_cfg/{entity_type_uuid}/modify
概要¶
カスタム基本定義、および現在のワークスペースのタイプ上書き設定/ヘルスポリシーを変更します。
呼び出し前の準備と使用手順¶
まず get で元の定義と現在のワークスペースの上書き設定をバックアップし、返された uuid を使用します。entityType コードは変更できません。カスタムタイプでは名前/説明/Schema/View/extend を変更できます。公式タイプではこれらの基本フィールドは有効になりませんが、ワークスペースの extraConfig/customProperties/healthConfig をサポートします。省略したフィールドは保持され、extraConfig/extend は非空の場合に全体を置換し、{} でクリアします。customProperties は空文字列でクリアします。
healthConfig では mode を明示する必要があります。system では default/func/disabled を許可し、それ以外では func/disabled のみを許可します。funcId は現在のワークスペースに存在する未削除の関数である必要があり、保存時に関数は実行されません。ヘルスポリシーを変更すると、古い計算世代は無効になります。無効化後、クエリは直ちに有効な無効状態に従い、過去の結果は非同期でリセットされます。設定トランザクションと後続の世代/補償スケジューリングは完全にはアトミックではないため、500 の場合はまず get で確認してから処理してください。公開 API はフロントエンドの entityStatusConfig をサポートせず、その effectiveViewDefine も返しません。
以下のパスは、フィールド値内の YAML テキストに存在するものであり、追加の JSON Body フィールドではありません。まず default から作成テンプレートを取得するか、既存の元の設定から値を取得し、必要な部分だけを変更してください。
| YAML パス | 値・デフォルト・取得元 |
|---|---|
| schemaDefine.properties[] | base フィールドオブジェクトの配列です。一般的には name、type、required、title を含みます。名前/型はそのエンティティの業務 Schema から取得し、エンティティ属性値で定義を代替することはできません。type は実際のデータと一致させる必要があります。Studio のメタデータ処理ではデフォルトで string になります。追加の Schema 拡張は元のテンプレートに従って保持してください。 |
| schemaDefine.properties[].name/type/required/title | name はフィールドコードです。type は実際の DataSchema 型です。required はブール値(デフォルト false)です。title は文字列または言語からテキストへのオブジェクトにできます。この宣言は、すべてのエンティティ書き込み時のフィールド単位の業務検証を置き換えるものではありません。 |
| viewDefine.layout[] | 表示レイアウト項目の配列です。一般的には group オブジェクト(display_name、fields)または直接の bind/title ノードです。エクスポートもこれに基づいて列を選択します。 |
| viewDefine.layout[].group.fields[] | フィールドコントロールの配列です。bind は実際の Schema フィールドを参照し、title は文字列/ローカライズオブジェクトです。ui_type およびその他の属性は元のテンプレート/UI の機能に従います。fields は元の定義に従ってネストできます。サーバー側では各コントロールの効果を一律に検証しません。 |
| customProperties.custom_properties[] | カスタムフィールドオブジェクトです。トップレベルの配列にも対応します。空のテキストはフィールドなしを表します。原文を保存し、デフォルト値を元の YAML に自動で書き戻しません。 |
| custom_properties[].name | 業務フィールド名です。必須で非空であり、使用できる文字は数字/英字/_/- のみです。base properties および同じ配列内で重複してはならず、ドットや空白を含めることはできません。 |
| custom_properties[].type | 必須の非空型名です。実際のフィールドに応じて string などを選択します。保存時に統一的な列挙を強制せず、任意の型が UI でサポートされることを意味しません。 |
| custom_properties[].title | 任意の表示タイトルです。文字列または zh-CN/en-US などの言語テキストオブジェクトです。省略した場合、表示はフィールド名にフォールバックできます。 |
| custom_properties[].required | 任意で、デフォルトは false です。ブール値、または true/1/yes/y/on などのブール文字列は有効層で正規化されます。 |
| custom_properties[].extension_scope | 任意です。省略/空値の場合、有効層では custom になります。元の Schema 拡張の用途に従って使用します。 |
| custom_properties[].writable_sources[] | 任意の配列です。各項目は manual/gitops などの実際の書き込み元識別子です。空白を除去し、空の項目はスキップし、省略時は生成しません。これは Schema 機能の宣言であり、現在の API 認可を拡大するものではありません。 |
| custom_properties[].capabilities | 任意のオブジェクトです。display/edit/filter/sort は表示、編集、フィルター、ソート機能のブール値で、存在する場合は正規化されます。指定されていないキーは自動的に一律補完されません。その他の拡張値は元の定義に従って保持されます。 |
| custom_properties[].その他のフィールド | allowed_values、items など、DataSchema の既存拡張に従って保持します。保存に成功したからといって、すべての消費側がサポートしていると見なすことはできません。 |
リクエストでは上記の YAML を文字列としてエンコードします。以下の例の改行は curl JSON 内でエスケープされ、サーバー側ではテキストとして解析されます。ローカルファイルパスを送信したり、YAML を JSON オブジェクトに展開したりしないでください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| entity_type_uuid | string | Y | パス必須。タイプは enty_ UUID であり、コードやエンティティ URN ではありません。 例: enty_example取得または入力方法: 現在のワークスペースのタイプ一覧 items[].uuid から対象を取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| extraConfig.telemetrySelectors | array | 既存の拡張例キーです。消費側が定義する構造に従い、エンティティのリアルタイムクエリ結果ではありません。キーを省略すると全体置換により古い設定が失われるため、先に get してください。 例: []取得または入力方法: このタイプに既存のテレメトリ関連設定から完全な項目をコピーします。 |
|
| extraConfig.telemetrySelectors[*] | JSON | 動的オブジェクトは元の消費設定に従って保持します。例は、すべてのシナリオで source/query プロトコルを強制的に統一するものではありません。 例: {"source": "logging", "query": "service:api"}取得または入力方法: 現在の業務で検証済みのテレメトリ関連項目。 |
|
| extraConfig.disabledBuiltInViews | array | 既存の拡張例キーです。要素には実際のビュー識別子を使用し、統一的な列挙を捏造しません。[] はこのオブジェクトがこれらのビューを無効化しないことを表します。 例: []取得または入力方法: 既存タイプの extraConfig または UI がサポートする内蔵ビュー識別子から選択します。 |
|
| extraConfig.disabledBuiltInViews[*] | string | 個々の無効化項目です。有効かどうかは対応する UI の消費に依存し、この API の権限設定ではありません。 例: view_example取得または入力方法: 既存の内蔵ビューの実際の識別子。 |
|
| extraConfig.その他の設定キー | JSON | 動的拡張値を保持します。統一的なデフォルトや列挙はありません。 例: {}取得または入力方法: 現在のタイプ詳細/消費機能の設定説明から取得します。 |
|
| healthConfig.mode | string | healthConfig を提供する場合は業務上必須です。default は system のみ許可します。disabled に切り替えると直ちに無効状態として読み取られ、同時に過去の結果が非同期でリセットされます。すべての関数が同期的に実行されるわけではありません。 例: disabled取得または入力方法: system のデフォルト計算には default、独自計算には func、無効化には disabled を使用します。 |
|
| healthConfig.funcId | string | func モードでは業務上必須です。その他のモードでは無視され、保存時の正規化構造から削除されます。表示名/ソースコードは入力しません。保存時は存在確認のみを行い、受け入れ関数を直ちに実行しません。 例: func_example取得または入力方法: 現在のワークスペースの Func 関数管理から未削除の関数 UUID を取得し、ヘルススコアの規約に適合することを確認します。 |
|
| extend.拡張フィールド | JSON | 動的に保持され、統一的なデフォルト/列挙はありません。任意の値が機能によって消費されることを保証しません。 例: value取得または入力方法: 対応するカスタム機能の実際の規約または既存レコードに従います。 |
|
| customProperties | string | 任意の YAML テキスト文字列です。原文/コメントを保持します。作成時に省略すると空文字列、変更時に省略すると保持、空文字列でクリアします。custom_properties 配列を推奨し、トップレベルの配列にも対応します。フィールド名は base properties またはこの配列内で重複できません。展開したオブジェクトをそのまま Body 値として指定しないでください。 null を許可: False 例: "# 保留原文与注释\ncustom_properties:\n - name: business_owner\n title: 业务负责人\n type: string\n required: false\n extension_scope: custom\n writable_sources: [manual, gitops]\n capabilities: {display: true, edit: true, filter: false, sort: false}\n"取得または入力方法: 現在のワークスペース詳細の元の customProperties バックアップから取得するか、以下の埋め込み YAML 形式に従ってフィールドを追加します。 |
|
| description | string | 任意で、最大 512 重み付き文字です。作成時に省略すると空文字列、変更時に省略すると保持、空文字列でクリアします。公式タイプではこの変更は無視されます。 null を許可: False 最大長: 512 例: 业务服务目录取得または入力方法: 業務側からタイプの用途説明を提供します。 |
|
| extend | json | 任意の動的オブジェクトです。作成時のデフォルトは {} です。カスタム変更時に省略すると保持し、{} でクリアし、非空の場合は全体を置換します。公式の基本タイプではこのフィールドを無視し、統一スイッチとして扱いません。 null を許可: False 例: {}取得または入力方法: 現在のカスタムタイプの extend から全体をコピーするか、業務側から拡張設定の提供を受けます。 |
|
| extraConfig | json | 任意の動的ワークスペース上書きオブジェクトです。作成時のデフォルトは {} です。変更時に省略すると保持し、{} で全体をクリアし、非空の場合は深いマージではなく全体を置換します。公式タイプでもサポートされ、他のワークスペースの公式基本定義は変更しません。サーバー側ではすべての動的キーの意味を一律に検証しません。 null を許可: False 例: {"telemetrySelectors": [], "disabledBuiltInViews": []}取得または入力方法: 現在のワークスペースの同じタイプ詳細の extraConfig から全体をバックアップすることを優先し、実際のフロントエンドビュー/テレメトリ設定要件に応じて調整します。 |
|
| healthConfig | json | 変更時のみサポートされます。省略すると保持します。system では default/func/disabled、その他のタイプでは func/disabled のみです。{} は保持ではなく無効なモードです。すべてのタイプで機能は常に有効であり、履歴クリーンアップの完了を待ちません。 null を許可: False 例: {"mode": "disabled"}取得または入力方法: タイプの業務に応じて計算ポリシーを選択し、詳細の healthConfig から現在の有効値を確認します。 |
|
| name | string | 任意で、最大 128 重み付き文字です。作成時に省略すると空文字列になります。変更時は空白を除去して渡し、空文字列でクリアし、省略すると保持します。公式タイプでこのフィールドを渡しても公式名は上書きされません。 null を許可: False 最大長: 128 例: 示例服务取得または入力方法: 業務側からタイプの表示名を提供します。entityType コードを置き換えるものではありません。 |
|
| schemaDefine | string | 任意の YAML オブジェクトテキストです。properties は配列である必要があります。作成時に省略/空文字列の場合はテンプレートから補完し、{entity_type} をリクエストコードで置換します。カスタムタイプの変更時のみ有効で、省略すると保持し、空文字列で元の定義をクリアします。effectiveSchemaDefine を元の schema に書き戻すことはできません。 null を許可: False 例: "kind: DataSchema\nentity_type: demo_service\nproperties:\n - name: env\n type: string\n required: false\n"取得または入力方法: まず entityTypeUUID=default でテンプレートを取得するか、get で対象の元の DataSchema YAML をバックアップします。 |
|
| viewDefine | string | 任意の YAML オブジェクトテキストです。layout/各階層の fields は配列である必要があります。作成時に省略/空文字列の場合はテンプレートから補完し、{entity_type} を置換します。変更時に有効になるのはカスタムタイプのみで、省略すると保持し、空文字列でクリアします。effectiveViewDefine ではありません。列/コントロールの追加拡張は元のテンプレート構造を保持してください。 null を許可: False 例: "kind: UIView\nlayout:\n - group:\n display_name: 基础信息\n fields:\n - bind: env\n title: 环境\n ui_type: input\n"取得または入力方法: 作成テンプレートまたは現在のタイプの元の UIView YAML から取得します。 |
パラメータ補足説明¶
パスパラメータの説明
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| entity_type_uuid | string | はい | 対象エンティティタイプの UUID |
リクエストボディパラメータの説明
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| name | string | いいえ | エンティティタイプの表示名 |
| description | string | いいえ | エンティティタイプの説明 |
| extraConfig | json | いいえ | 現在のワークスペースにおける追加設定 |
| customProperties | string | いいえ | エンティティタイプが現在のワークスペースで追加する DataSchema カスタムフィールドの YAML テキスト。トップレベルは custom_properties を推奨します。 |
| schemaDefine | string | いいえ | DataSchema YAML テキスト |
| viewDefine | string | いいえ | UIView YAML テキスト |
| extend | json | いいえ | 拡張フィールド |
呼び出し時の注意事項
- デフォルトタイプでは extraConfig と customProperties の変更をサポートします。
- すべてのエンティティタイプで常に healthConfig の変更をサポートします。system は default/func/disabled、その他のタイプは func/disabled をサポートします。バックエンドの readiness クリーンアップ進捗に依存しません。
- カスタムタイプでは name、description、schemaDefine、viewDefine、extend を変更でき、同時に extraConfig と customProperties も変更できます。
- extraConfig は完全なオブジェクトを渡すことを推奨し、部分 patch の考え方で値を渡すことは推奨しません。
- customProperties はトップレベルに custom_properties 配列を含む YAML テキストを渡すことを推奨します。旧来の呼び出しとの互換性のため、トップレベルの YAML 配列も受け付けます。
- customProperties のフィールド名は、現在のエンティティタイプの DataSchema properties 内のフィールドと重複できません。フィールドは YAML テキストとして保存され、コメントはそのまま保持されます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity_type_cfg/enty_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"示例服务","extraConfig":{},"customProperties":"# 保留原文与注释\ncustom_properties:\n - name: business_owner\n title: 业务负责人\n type: string\n required: false\n extension_scope: custom\n writable_sources: [manual, gitops]\n capabilities: {display: true, edit: true, filter: false, sort: false}\n","healthConfig":{"mode":"disabled"}}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | タイプレコード番号。新規作成の送信前は null の可能性があります。 |
| content.uuid | string | enty_ タイプ UUID。作成テンプレートは default です。 |
| content.workspaceUUID | string | タイプが属するワークスペース。公式タイプでは空にできます。ワークスペース上書き設定は引き続き現在のワークスペースごとに個別に処理されます。 |
| content.entityType | string | 安定したタイプコードであり、表示名ではありません。 |
| content.name | string | 表示名。 |
| content.description | string | 説明。 |
| content.sourceType | string | default は公式/デフォルト、custom はカスタムです。 |
| content.isSystem | integer | システムレベルフラグ。sourceType と単純に等価ではありません。 |
| content.isHidden | integer | 非表示フラグ。通常の一覧では非表示のシステムタイプは除外されます。 |
| content.showRank | integer または null | システムタイプの表示順の重み。値がない場合は null です。 |
| content.entityTypeGroupUUID | string | 履歴グループ識別子。空にできます。公開 API は廃止されたグループ書き込みパラメータを受け付けません。 |
| content.groupInfo | object または null | グループ要約。欠落時は {} にでき、デフォルトタイプの変更時は null にできます。 |
| content.groupInfo.uuid | string | 履歴グループが存在する場合の UUID。 |
| content.groupInfo.name | string | 履歴グループが存在する場合の名前。 |
| content.schemaDefine | string | 元の DataSchema YAML。summaryOnly 一覧では省略されます。 |
| content.viewDefine | string | 元の UIView YAML。summaryOnly 一覧では省略されます。 |
| content.extend | object | 動的タイプ拡張。 |
| content.extend.拡張キー | JSON | 具体的なキーは元のタイプ定義に従います。 |
| content.status | integer | 正常は 0。default 作成テンプレートは 3 で、一覧内のアクティブリソースではありません。 |
| content.creator | string | 作成主体の UUID/システム識別子。 |
| content.updator | string | 更新主体。 |
| content.createAt | integer | 作成 Unix 秒。 |
| content.updateAt | integer | 更新 Unix 秒。未更新の場合は -1 にできます。 |
| content.deleteAt | integer | 削除 Unix 秒。未削除の場合は -1。 |
| content.entityCount | integer | 現在のワークスペースのエンティティ数。一覧で withEntityCount=false の場合は省略されます。新規/変更で 0 が返っても、実際の数がクエリ済みであることを意味しません。 |
| content.extraConfig | object | 現在のワークスペースの追加設定。デフォルトは {}。 |
| content.extraConfig.telemetrySelectors | array | 条件付きで存在するテレメトリ関連設定。エンティティのクエリ結果と同等ではありません。 |
| content.extraConfig.telemetrySelectors[] | JSON | 対応する設定の動的項目。 |
| content.extraConfig.disabledBuiltInViews | array<string> | 条件付きで存在する無効化された内蔵ビュー識別子。 |
| content.extraConfig.disabledBuiltInViews[] | string | 個々のビュー識別子。 |
| content.extraConfig.その他のキー | JSON | 動的拡張。実際の値を保持します。 |
| content.healthConfig | object | 現在のワークスペースのタイプで有効なヘルスポリシー。作成レスポンスに必ず含まれるフィールドではありません。 |
| content.healthConfig.mode | string | system のデフォルトは default、その他は未設定の場合 disabled。設定後は func/disabled にできます。 |
| content.healthConfig.funcId | string | func の場合のみ存在する関数 UUID。 |
| content.customProperties | string | 現在のワークスペースの元のカスタムフィールド YAML。コメントを保持します。 |
| content.effectiveSchemaDefine | string | base schema に現在のワークスペースで解析済みの custom_properties をマージした YAML。コメントの保持は保証されません。公開詳細/作成/変更には含まれ、一覧には含まれません。書き戻し可能な元の Schema ではありません。 |
| content.declaration | object | 共通宣言。 |
{
"code": 200,
"content": {
"id": 100,
"uuid": "enty_example",
"workspaceUUID": "wksp_example",
"entityType": "demo_service",
"name": "示例服务",
"description": "业务服务目录",
"sourceType": "custom",
"isSystem": 0,
"isHidden": 0,
"showRank": null,
"entityTypeGroupUUID": "",
"schemaDefine": "kind: DataSchema\nentity_type: demo_service\nproperties:\n - name: env\n type: string\n required: false\n",
"viewDefine": "kind: UIView\nlayout:\n - group:\n display_name: 基础信息\n fields:\n - bind: env\n title: 环境\n ui_type: input\n",
"extend": {},
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427200,
"deleteAt": -1,
"status": 0,
"groupInfo": {},
"entityCount": 0,
"extraConfig": {},
"healthConfig": {
"mode": "disabled"
},
"customProperties": "# 保留原文与注释\ncustom_properties:\n - name: business_owner\n title: 业务负责人\n type: string\n required: false\n extension_scope: custom\n writable_sources: [manual, gitops]\n capabilities: {display: true, edit: true, filter: false, sort: false}\n",
"effectiveSchemaDefine": "kind: DataSchema\nentity_type: demo_service\nproperties:\n- name: env\n type: string\n required: false\ncustom_properties:\n- name: business_owner\n title: 业务负责人\n type: string\n required: false\n extension_scope: custom\n writable_sources:\n - manual\n - gitops\n capabilities:\n display: true\n edit: true\n filter: false\n sort: false\n",
"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.InvalidParameter | カスタムフィールドの YAML/名前/型/機能構造が不正、または Schema/View 構造からメタデータを生成できない。healthConfig.mode が不正、非 system で default を使用、func モードで funcId が欠落、または現在のワークスペースの未削除関数ではない | パラメータ {} が無効 |
以下の YAML フィールド表と元のテンプレートに従って修正し、base フィールドの重複名、ルートオブジェクト/配列、有効な型を確認します。まずタイプで許可されるヘルス mode を確認し、現在のワークスペースの Func 管理から未削除の関数 UUID を取得します。名前や他のワークスペースの関数を入力しないでください。 |
| 500 | ft.InternalServerError | 設定の読み書き、元の履歴 YAML の処理、カウントクエリ、ロック/ヘルス世代または補償タスクの未捕捉失敗 | 内部エラー | まず UUID で現在の状態を読み戻します。エラーが送信後に発生した場合、設定はすでに有効になっている可能性があります。traceId を保持し、むやみに重複作成しないでください。 |
| 404 | ft.NotFoundCatalogEntityType | タイプ UUID が存在しない/削除済み、または不可視 | 指定されたエンティティタイプが見つかりません | タイプ一覧から現在可視の UUID を取得します。 |
| 429 | ft.OperationTooFrequently | タイプ変更またはヘルス書き込みの相互排他ロック競合 | 操作が頻繁すぎます。しばらくしてから再試行してください | 限定的なバックオフを行い、現在の設定を読み戻してから送信します。 |