統合カタログ エンティティタイプ作成¶
POST /api/v1/unified_catalog/entity_type_cfg/create
概要¶
ワークスペースのカスタムエンティティタイプおよびワークスペース拡張フィールドを作成します。
呼び出し前の準備と使用手順¶
最小リクエストは有効な entityType で、name/description は任意です。省略された Schema/View は default の非表示テンプレートから補完されます。テンプレートが存在しない場合はリクエストのテキスト/空文字列が保持され、完全なフォームが自動的に得られることは保証されません。作成レスポンスの id は null になる可能性があり、entityCount は常に 0 で、既存エンティティをクエリした結果ではありません。
extraConfig/customProperties を同時に保存できます。作成時は healthConfig を処理しません。先に作成してから変更 API を呼び出して設定してください。system 以外のタイプはヘルスを設定しない場合デフォルトで disabled です。作成は公式の基本定義をコピーするものではなく、廃止されたタイプグループのパラメータも受け付けません。
以下のパスはフィールド値内の 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[].その他のフィールド | DataSchema に既存の拡張(allowed_values、items など)に従って保持します。保存に成功したからといって、すべての消費側がサポートしていると判断することはできません。 |
リクエストでは上記の YAML を文字列としてエンコードします。以下の例の改行は curl JSON 内でエスケープされ、サーバーはテキストとして解析します。ローカルファイルパスを送信したり、YAML を JSON オブジェクトに展開したりしないでください。
リクエストヘッダ¶
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| 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 | 動的な拡張値は保持されます。統一的なデフォルトや列挙はありません。 例: {}取得または入力方法: 現在のタイプ詳細/消費機能の設定説明から取得します。 |
|
| 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 例: 业务服务目录取得または入力方法: ビジネス側が提供するタイプ用途の説明。 |
|
| entityType | string | Y | 作成時必須。空白除去後に ^[a-zA-Z][0-9a-zA-Z_-]{0,63}$ に一致し、先頭文字の後は数字/英字/_/- を使用でき、大文字小文字は区別されます。一意なコードを選択してください。少なくとも現在参照可能な公式/カスタムの同名は拒否されます。作成後に変更でコードを変更することはできません。詳細で UUID が省略された場合の特定の代替手段です。 null 許可: False 最大長: 64 例: demo_service取得または入力方法: 呼び出し側がタイプコードを選択します。読み取り時はリストの entityType からそのまま取得します。 |
| extend | json | 任意の動的オブジェクト。作成で省略時は {}、カスタム変更で省略時は保持、{} でクリア、非空は全体置換です。公式の基本タイプではこのフィールドは無視され、統一的なスイッチとして扱われません。 null 許可: False 例: {}取得または入力方法: 現在のカスタムタイプの extend から全体をコピーするか、ビジネス側が提供する拡張設定。 |
|
| extraConfig | json | 任意の動的ワークスペース上書きオブジェクト。作成で省略時は {}、変更で省略時は保持、{} で全体クリア、非空は深いマージではなく全体置換です。公式タイプでもサポートされ、他のワークスペースの公式基本定義は変更されません。サーバーはすべての動的キーの意味を一律には検証しません。 null 許可: False 例: {"telemetrySelectors": [], "disabledBuiltInViews": []}取得または入力方法: まずこのワークスペースの同タイプ詳細の extraConfig から全体をバックアップし、実際のフロントエンドのビュー/テレメトリ設定要件に応じて調整します。 |
|
| 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 から取得します。 |
パラメータ補足説明¶
リクエストパラメータ説明
| パラメータ名 | type | 必須 | 説明 |
|---|---|---|---|
| entityType | string | はい | エンティティタイプコード。グローバルに一意です |
| name | string | いいえ | エンティティタイプの表示名 |
| description | string | いいえ | エンティティタイプの説明 |
| extraConfig | json | いいえ | 現在のワークスペースにおける追加設定 |
| healthConfig | json | いいえ | 作成 API ではこのフィールドを処理しません。作成成功後にエンティティタイプ変更 API でヘルスを設定します |
| customProperties | string | いいえ | 現在のワークスペース下でエンティティタイプに追加する DataSchema カスタムフィールドの YAML テキスト。トップレベルは custom_properties を推奨します |
| schemaDefine | string | いいえ | DataSchema YAML テキスト |
| viewDefine | string | いいえ | UIView YAML テキスト |
| extend | json | いいえ | 拡張フィールド |
テンプレートの使用説明
schemaDefineまたはviewDefineを渡さない場合、システムはデフォルトテンプレートから自動的に補完します。- デフォルトテンプレート内の
{entity_type}は、現在のリクエストのentityTypeに置換されます。 - 呼び出し側がテンプレートを完全にカスタマイズしたい場合は、完全な YAML テキストを直接渡すことができます。
- 作成時に
extraConfigとcustomPropertiesを同時に渡すことができ、両方は現在のワークスペースのエンティティタイプ設定に書き込まれます。
呼び出し時の注意事項
- OpenAPI は廃止されたエンティティタイプグループのパラメータをサポートしません。
- 最小限のエンティティタイプのみを作成したい場合は、
entityTypeのみを渡すことができます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity_type_cfg/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"entityType":"demo_service","name":"示例服务","description":"业务服务目录","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","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","extraConfig":{}}'
レスポンス¶
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.customProperties | string | 現在のワークスペースの元のカスタムフィールド YAML。コメントを保持します。 |
| content.effectiveSchemaDefine | string | base schema に現在のワークスペースで解決された custom_properties をマージした YAML。コメントの保持は保証されません。公開の詳細/作成/変更には含まれ、リストには含まれません。書き戻し可能な元の Schema ではありません。 |
| content.declaration | object | 共通宣言。 |
{
"code": 200,
"content": {
"id": null,
"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": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"status": 0,
"groupInfo": {},
"entityCount": 0,
"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",
"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 を保持し、むやみに作成を繰り返さないでください。 |
| 400 | ft.InvalidCatalogEntityType | コードが先頭文字および最大 64 文字のルールに適合しない | 無効なエンティティタイプ {} |
英字で始まり、数字/英字/_/- のみを使用するコードを使用してください。 |
| 406 | ft.CatalogEntityTypeExists | 現在参照可能な公式/カスタムタイプに同じコードがすでに存在する | エンティティタイプ {} はすでに存在します |
既存の UUID を取得して変更するか、別のビジネス上一意なコードを選択してください。 |
| 429 | ft.OperationTooFrequently | 同時に同じコードの作成/テンプレートタスクがロックを保持しており、作成ロックを取得できない | 您的操作太频繁, 请稍后重试 | しばらく待ってバックオフ再試行する前に、リストを読み取ってすでに作成されているか確認してください。 |