統合カタログのエンティティタイプ一覧¶
POST /api/v1/unified_catalog/entity_type_cfg/list
概要¶
現在のワークスペースで参照可能なエンティティタイプとそのオーバーライド設定をページ単位で読み取ります。
呼び出し前の準備と使用手順¶
一覧には、参照可能な公式タイプと現在のワークスペースのカスタムタイプが含まれます。withDefault=false の場合は後者のみです。非表示のシステムタイプおよび default 作成テンプレートは通常の一覧には含まれません。デフォルトタイプが優先され、システムタイプは表示ウェイトの降順、その後、作成時間/番号の昇順で並びます。
OpenAPI のデフォルトは withEntityCount=true で、エンティティクエリサービスにアクセスします。false の場合は数量を省略します。filters はカウントのみを制約し、ヒット数がゼロのタイプを除外しません。summaryOnly=true の場合は base Schema/View を省略しますが、customProperties などのオーバーライド値を含む場合があります。この公開エントリポイントは Front の有効なヘルスフォーム/effectiveViewDefine/entityStatusConfig を返しません。すべてのタイプのヘルス機能は常に参照可能で、system はデフォルトで default、その他はデフォルトで disabled です。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| filters.属性フィールド名 | JSON | 動的キーと値はエンティティクエリサービスによって解釈されます。空のオブジェクトはカウントを絞り込みません。スカラー候補値の配列を推奨します。 例: ["prod"]取得または入力方法: 既存のエンティティ属性フィールド名と候補値。 |
|
| filters | json | 任意のオブジェクト。現在は withEntityCount=true の場合にのみエンティティ数の集計に使用され、カウントが 0 のタイプは除外されず、これによってヒットするエンティティのあるタイプのみが返されることを保証するものではありません。withEntityCount=false の場合はこのフィルタによるカウントを実行しません。 null を許可: False 例: {"env": ["prod"]}取得または入力方法: エンティティの attributes フィールドと値を選択します。該当タイプの Schema およびエンティティフィールド統計から取得します。 |
|
| pageIndex | integer | 任意。デフォルトは 1、最小値は 1、コントローラでは最大 100000。 null を許可: False $minValue: 1 例: 1取得または入力方法: 呼び出し元が 1 からタイプ設定一覧を走査します。 |
|
| pageSize | integer | 任意。デフォルトは 20、1..200。 null を許可: False $maxValue: 200 $minValue: 1 例: 20取得または入力方法: クライアント表示または一括読み取りの必要に応じて設定します。 |
|
| search | string | 任意。先頭と末尾の空白を除去します。entityType/name に一致し、description/任意の属性値は検索しません。 null を許可: False 例: demo取得または入力方法: タイプコード/表示名のキーワードを入力します。 |
|
| summaryOnly | boolean | 任意。デフォルトは false。true の場合は schemaDefine/viewDefine/fieldMetadata を読み取らず/返しませんが、extraConfig/healthConfig/customProperties および任意のカウントは返します。YAML フィールドが完全に含まれないことを保証するものではありません。 null を許可: False 例: true取得または入力方法: カタログセレクターでは true を指定して軽量なタイプ要約を取得できます。 |
|
| withDefault | boolean | 任意。デフォルトは true。false の場合は現在のワークスペースのカスタムタイプのみを取得します。status=3 の default 作成テンプレートは返しません。 null を許可: False 例: true取得または入力方法: 現在参照可能な公式デフォルトタイプを含めるかどうか。 |
|
| withEntityCount | boolean | OpenAPI のデフォルトは true。false の場合は entityCount を省略し、下流のクエリを減らします。Front/AIAPI のデフォルト false を適用しないでください。 null を許可: False 例: true取得または入力方法: 各タイプのエンティティ数をクエリする必要があるかどうか。 |
パラメータ補足説明¶
リクエストパラメータ説明
| パラメータ名 | type | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | いいえ | ページ番号。デフォルトは 1 |
| pageSize | integer | いいえ | 1 ページあたりの件数。デフォルトは 20 |
| search | string | いいえ | エンティティタイプのコードまたは表示名で検索 |
| filters | json | いいえ | エンティティの attributes でフィルタし、エンティティタイプを逆方向に絞り込み |
| withDefault | boolean | いいえ | システムのデフォルトタイプを含めるかどうか。デフォルトは true |
| withEntityCount | boolean | いいえ | エンティティ数を返すかどうか。デフォルトは true |
| summaryOnly | boolean | いいえ | 軽量な要約を返すかどうか。true の場合は schema/view/effective 定義を読み取らず、返しません |
呼び出し時の注意事項
- これはページネーションインターフェースです。
pageIndexとpageSizeを明示的に指定することを推奨します。 - 返却結果の
extraConfigは、現在のワークスペース視点でのエンティティタイプ追加設定です。 - デフォルトタイプとカスタムタイプは結果に同時に含まれます。具体的な内容は
withDefaultに依存します。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity_type_cfg/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"pageIndex":1,"pageSize":20,"withDefault":true,"withEntityCount":false,"summaryOnly":true}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.items | array<object> | 現在のページのタイプ。 |
| content.items[].id | integer または null | タイプレコード番号。新規作成の送信前は null の場合があります。 |
| content.items[].uuid | string | enty_タイプUUID。作成テンプレートは default。 |
| content.items[].workspaceUUID | string | タイプが属するワークスペース。公式タイプでは空の場合があります。ワークスペースのオーバーライド設定は引き続き現在のワークスペースごとに個別に処理されます。 |
| content.items[].entityType | string | 安定したタイプコードであり、表示名ではありません。 |
| content.items[].name | string | 表示名。 |
| content.items[].description | string | 説明。 |
| content.items[].sourceType | string | default は公式/デフォルト、custom はカスタム。 |
| content.items[].isSystem | integer | システムレベルフラグ。sourceType と単純に等価ではありません。 |
| content.items[].isHidden | integer | 非表示フラグ。通常の一覧では非表示のシステムタイプは除外されます。 |
| content.items[].showRank | integer または null | システムタイプの表示順ウェイト。値がない場合は null。 |
| content.items[].entityTypeGroupUUID | string | 履歴グループ識別子。空の場合があります。公開インターフェースは廃止されたグループ書き込みパラメータを受け付けません。 |
| content.items[].groupInfo | object または null | グループ要約。欠落時は {} の場合があり、デフォルトタイプの変更時は null の場合があります。 |
| content.items[].groupInfo.uuid | string | 履歴グループが存在する場合の UUID。 |
| content.items[].groupInfo.name | string | 履歴グループが存在する場合の名前。 |
| content.items[].schemaDefine | string | 元の DataSchema YAML。summaryOnly の一覧では省略されます。 |
| content.items[].viewDefine | string | 元の UIView YAML。summaryOnly の一覧では省略されます。 |
| content.items[].extend | object | 動的タイプ拡張。 |
| content.items[].extend.拡張キー | JSON | 具体的なキーは元のタイプ定義に従います。 |
| content.items[].status | integer | 正常は 0。default 作成テンプレートは 3 で、一覧内のアクティブリソースではありません。 |
| content.items[].creator | string | 作成ID UUID/システム識別子。 |
| content.items[].updator | string | 更新ID。 |
| content.items[].createAt | integer | 作成 Unix 秒。 |
| content.items[].updateAt | integer | 更新 Unix 秒。未更新の場合は -1。 |
| content.items[].deleteAt | integer | 削除 Unix 秒。未削除の場合は -1。 |
| content.items[].entityCount | integer | 現在のワークスペースのエンティティ数。一覧で withEntityCount=false の場合は省略されます。新規作成/変更の返却値 0 は、実際の数量をクエリ済みであることを意味しません。 |
| content.items[].extraConfig | object | 現在のワークスペースの追加設定。省略時は {}。 |
| content.items[].extraConfig.telemetrySelectors | array | 条件付きで存在するテレメトリ関連設定。エンティティクエリ結果とは異なります。 |
| content.items[].extraConfig.telemetrySelectors[] | JSON | 対応する設定の動的項目。 |
| content.items[].extraConfig.disabledBuiltInViews | array<string> | 条件付きで存在する無効化された組み込みビュー識別子。 |
| content.items[].extraConfig.disabledBuiltInViews[] | string | 単一のビュー識別子。 |
| content.items[].extraConfig.その他のキー | JSON | 動的拡張。実際の値を保持します。 |
| content.items[].healthConfig | object | 現在のワークスペースにおけるタイプの有効なヘルスポリシー。作成レスポンスにこのフィールドが必ず含まれるわけではありません。 |
| content.items[].healthConfig.mode | string | system はデフォルトで default、その他は未設定時は disabled。設定後は func/disabled を取ります。 |
| content.items[].healthConfig.funcId | string | func の場合にのみ存在する関数 UUID。 |
| content.items[].customProperties | string | 現在のワークスペースの元のカスタムフィールド YAML。コメントを保持します。 |
| content.pagination | object | ページネーション情報。content 内に保持され、pageInfo として上位に持ち上げられる構造ではありません。 |
| content.pagination.pageIndex | integer | 現在のページ。1 から開始。 |
| content.pagination.pageSize | integer | 実際の 1 ページあたりのサイズ。 |
| content.pagination.count | integer | このページの件数。 |
| content.pagination.totalCount | integer | 現在参照可能なタイプ設定の総数であり、エンティティ数ではありません。カウント用 filters によってヒット数ゼロのタイプが除外されることはありません。 |
| content.declaration | object | 外側の宣言。 |
{
"code": 200,
"content": {
"items": [
{
"id": 100,
"uuid": "enty_example",
"workspaceUUID": "wksp_example",
"entityType": "demo_service",
"name": "示例服务",
"description": "业务服务目录",
"sourceType": "custom",
"isSystem": 0,
"isHidden": 0,
"showRank": null,
"entityTypeGroupUUID": "",
"extend": {},
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427200,
"deleteAt": -1,
"status": 0,
"groupInfo": {},
"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"
}
],
"pagination": {
"pageIndex": 1,
"pageSize": 20,
"count": 1,
"totalCount": 1
},
"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 ファイル形式エラー | 例に従ってオブジェクトを送信し、配列/文字列を使用しないでください。 |
| 500 | ft.InternalServerError | タイプ読み取り、エンティティカウント、履歴設定/元の Schema の解析またはフォーマットに失敗 | 内部エラー | traceId およびタイプ/フィルタ条件を保持し、履歴定義とクエリサービスを確認します。これは読み取り失敗であり、今回設定が保存されたことを意味しません。 |