統合カタログのエンティティタイプ詳細¶
GET /api/v1/unified_catalog/entity_type_cfg/get
概要¶
単一タイプの元の定義、ワークスペースオーバーライド、有効なDataSchemaを読み取ります。
呼び出し前の確認と使用手順¶
entityTypeUUID と entityType は少なくとも一方を指定します。空でない UUID を優先し、両者が一致しない場合も UUID に従います。相互検証には使用しません。entityTypeUUID=default は非表示の作成テンプレート(status=3)を読み取ります。作成アクションではなく、カウントは 0 です。通常の詳細では現在のワークスペースのエンティティ数を常に照会します。Front の withEntityCount パラメータで無効化することはできません。
元の schemaDefine/viewDefine/customProperties と、マージ後の effectiveSchemaDefine を返します。公開APIでは Front 専用の effectiveViewDefine/ヘルス保持フォームフィールド/entityStatusConfig を補完しません。以降の編集では元のテキストを使用し、effective 定義を書き戻すことはできません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| entityType | string | 作成時に必須です。空白を除去した後、^[a-zA-Z][0-9a-zA-Z_-]{0,63}$ に一致する必要があります。先頭文字の後には数字/英字/_/- を使用でき、大文字と小文字は区別されます。一意のコードを選択してください。少なくとも、現在参照可能な公式/カスタムで同名のものが存在する場合は拒否されます。作成後に変更操作でコードを変更することはできません。詳細取得時に UUID が省略された場合の代替指定です。 null を許可: False 例: demo_service取得または入力方法: 呼び出し元がタイプコードを選択します。読み取り時は一覧の entityType からそのまま取得します。 |
|
| entityTypeUUID | string | 詳細取得と entityType は少なくとも一方を指定します。UUID が空でない場合は優先し、両者の一致は検証しません。default は非表示の status=3 作成テンプレートを返し、エンティティ数は照会しません。削除時は実際のタイプ UUID が必須で、コードは使用しません。 null を許可: False 例: enty_example取得または入力方法: タイプ一覧の items[].uuid から enty_ 識別子を取得するか、default で作成テンプレートを取得します。 |
パラメータ補足説明¶
リクエストパラメータの説明
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| entityTypeUUID | string | 否 | エンティティタイプ UUID |
| entityType | string | 否 | エンティティタイプコード |
呼び出し時の注意事項
entityTypeUUIDとentityTypeは少なくとも一方を指定します。entityTypeUUID=defaultの場合はカスタムエンティティタイプの作成テンプレートを返します。このテンプレートはstatus=3のデータであり、エンティティタイプ一覧には表示されません。- 両方のパラメータを指定する場合は、同じエンティティタイプを指していることを確認することを推奨します。
- 返回結果には
schemaDefine、viewDefine、extraConfigが含まれます。 - 現在のワークスペースの
customPropertiesと、マージ後のeffectiveSchemaDefineを返します。 - OpenAPI の互換性を維持します。一覧と詳細ではデフォルトで
entityCountを照会して返します。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/unified_catalog/entity_type_cfg/get' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode entityTypeUUID=enty_example
レスポンス¶
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 | 作成者 ID の UUID/システム識別子。 |
| content.updator | string | 更新者 ID。 |
| 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 | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 406 | ft.MissingParameters | 2つのロケーションパラメータが両方とも空/欠落 | パラメータ欠落 | タイプ UUID またはコードを指定し、テンプレートの場合は entityTypeUUID=default を指定してください。 |
| 404 | ft.NotFoundCatalogEntityType | 対象タイプが現在の可視範囲に存在しない/削除済み、または default テンプレートが未設定 | 指定されたエンティティタイプが見つかりません | このワークスペースのタイプ一覧から再選択してください。テンプレートがない場合は管理者に連絡してください。エンティティ URN で代用することはできません。 |
| 500 | ft.InternalServerError | タイプの読み取り、エンティティ数カウント、履歴設定/元のSchemaの解析またはフォーマットに失敗 | 内部エラー | traceId とタイプ/フィルター条件を保持し、履歴定義とクエリサービスを確認してください。これは読み取り失敗であり、今回設定が保存されたことを意味しません。 |
| 406 | ft.InvalidParameter | 既存の customProperties YAML/フィールド名/型/機能構造が不正で、有効な Schema の生成時に失敗 | パラメータ {} が無効 |
管理者が現在のタイプの base Schema と customProperties の原文を確認し、フィールドの競合/構造を修正してください。リクエストのロケーションが正しい場合、UUID を繰り返し変更しないでください。 |