コンテンツにスキップ

統合カタログのエンティティタイプ一覧



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 およびタイプ/フィルタ条件を保持し、履歴定義とクエリサービスを確認します。これは読み取り失敗であり、今回設定が保存されたことを意味しません。

フィードバック

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