コンテンツにスキップ

統合カタログのエンティティタイプ変更



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 タイプ変更またはヘルス書き込みの相互排他ロック競合 操作が頻繁すぎます。しばらくしてから再試行してください 限定的なバックオフを行い、現在の設定を読み戻してから送信します。

フィードバック

このページは役に立ちましたか?