統合カタログエンティティ一覧¶
POST /api/v1/unified_catalog/entity/list
概要¶
タイプ、ソース、属性、有効なヘルスステータスで、現在のワークスペースのエンティティをページ単位で読み取ります。
呼び出し前の準備と使用手順¶
まずエンティティタイプ一覧でコードを取得し、次にフィールド統計で有効な候補値を取得して、必要に応じて filters を指定します。フィルターと並べ替えを固定してページごとに走査することを推奨します。items が空の場合はそのページに結果がないことを示します。このページでは Front 専用の障害数や子エンティティ数は返しません。providers が空でない場合は provider より優先されます。
すべてのエンティティタイプは有効なヘルス設定に従って処理され、バックエンドの履歴クリーンアップ進捗には依存しません。system でタイプポリシーが未設定の場合はデフォルトで default、その他のタイプで未設定の場合はデフォルトで disabled になります。エンティティは inherit でタイプを継承し、custom で Func を指定し、disabled で無効化します。タイプを無効化すると healthScore=null、healthStatus=unknown、healthUpdateAt=null が返され、ヘルスフィルター/統計も履歴結果ではなく無効状態に従います。フィルター/並べ替え/統計でトップレベルのヘルスフィールドを使用する場合は、entityType を明示する必要があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| providers[*] | string | 配列内の 1 つのソース。親配列を省略した場合はフィルターしません。 例: manual取得または入力方法: 既存エンティティの provider 値 1 つ。 |
|
| filters.属性フィールド名 | array または JSON | 動的キー。スカラー候補値の配列を推奨します。任意の DQL 式をフィールド名として扱うことはできません。urn/provider/entityType や healthStatus などのトップレベル組み込みフィールド、および snake_case エイリアスはトップレベルのまま保持され、attributes/sourceMetadata/telemetrySelectors オブジェクト内のキーはフラット化されます。 例: ["prod"]取得または入力方法: 現在のエンティティの attributes の実際のフィールド名を使用します。複雑な値のフィルターセマンティクスは、保存済みフィールドタイプとクエリサービスの機能に依存します。 |
|
| filters.属性フィールド名[*] | JSON | 同一フィールドの候補値 1 つ。数値/ブール値は元の JSON 型を保持し、null と文字列の null を混同しないでください。 例: prod取得または入力方法: 現在のフィールド候補値/既存エンティティの値から取得します。 |
|
| entityType | string | 一覧/統計では任意。トップレベルのヘルスフィールドでフィルター、統計、並べ替えを行う場合は業務上必須です。作成/変更では必須で、空白除去後に空でない必要があります。エクスポートでは必須です。 null を許可: False 例: database取得または入力方法: エンティティタイプ一覧 の items[].entityType からコードを取得します。タイプ UUID/表示名ではありません。 |
|
| filters | json | 任意のオブジェクト。{} は追加フィルターなしです。裸の属性キー env は attributes.env に変換され、明示的な attributes.entityType はトップレベルの entityType として扱われません。同じフィールドの複数の候補値は配列に入れます。異なるフィールドの組み合わせはクエリサービスに委ねます。ヘルスフィールドには個別の有効な無効状態があります。使用方法を参照してください。 null を許可: False 例: {"env": ["prod"]}取得または入力方法: フィールド名はタイプの DataSchema/属性、またはトポロジーフィールド一覧から取得し、値はフィールド統計/既存エンティティから取得します。 |
|
| order | string | 任意。デフォルトは desc です。asc/desc のみを渡すことを推奨します。公開宣言には列挙が追加されていないため、任意の文字列を保存できることを他の方向のサポートと見なすべきではありません。 null を許可: False 例: desc取得または入力方法: 呼び出し元が asc または desc を選択します。 |
|
| orderBy | string | 任意。デフォルトの並べ替えはクエリサービスが updatedAt に従って処理します。ヘルスで並べ替える場合は entityType が必須です。タイプでヘルスが無効化されている場合、ヘルス並べ替えは updatedAt desc に切り替わり、履歴のヘルス値では並べ替えません。 null を許可: False 例: updatedAt取得または入力方法: タイプビュー/フィールドインターフェースから並べ替え可能なフィールドを選択します。組み込みフィールドは updatedAt/name/healthScore などで、属性には attributes.env を使用します。 |
|
| pageIndex | integer | 任意。デフォルトは 1 です。公開一覧では 1..10000 です。1 ページをリクエストするとそのページのみ取得され、自動的に全件を収集しません。 null を許可: False $maxValue: 10000 $minValue: 1 例: 1取得または入力方法: 呼び出し元が 1 からページごとに走査します。 |
|
| pageSize | integer | 任意。デフォルトは 20 です。公開一覧では 1..200 です。エクスポートには別途実際の上限があり、このパラメータでエクスポートを制御しません。 null を許可: False $maxValue: 200 $minValue: 1 例: 20取得または入力方法: 呼び出し元が表示/走査の必要に応じて設定します。 |
|
| provider | string | 任意。渡さない場合はソースでフィルターしません。複数のソースには providers を使用し、その非空値は provider より優先されます。エンティティのソースは変更されません。 null を許可: False 例: manual取得または入力方法: 既存エンティティの provider またはフィールド値統計の provider バケットから取得します。具体的な値は収集/レポートのソースによって決まります。 |
|
| providers | array | 任意のソース配列。非空の場合は provider より優先されます。[] はソースフィルターを追加せず、空のソースのみを選択するわけではありません。公開配列では項目ごとの文字列検証が宣言されていないため、実際の文字列のみを使用することを推奨します。 null を許可: False 例: ["manual"]取得または入力方法: field_value/count の provider 候補バケットから実際のソース値を取得します。 |
|
| search | string | 任意。省略/空文字列の場合はあいまい検索を行いません。エンティティ集合に作用し、fieldValue の候補値フィルターとは異なります。 null を許可: False 例: demo取得または入力方法: 呼び出し元がエンティティ名/URN/表示名に含まれる検索語を入力します。 |
|
| urn | string | 読み取り/削除では必須で、先頭と末尾の空白を除去した後に空でない必要があります。一覧/統計では任意の完全一致フィルターです。変更時は元の URN を明示的に入力し、名前変更時に別のエンティティが作成されるのを避けることを推奨します。 null を許可: False 例: urn:database:default:demo取得または入力方法: このワークスペースのエンティティ一覧の items[].urn から取得し、完全な URN をそのまま使用することを優先します。 |
パラメータ補足説明¶
リクエストパラメータの説明
| パラメータ名 | type | 必須 | 説明 |
|---|---|---|---|
| pageIndex | integer | 否 | ページ番号。デフォルトは 1 |
| pageSize | integer | 否 | 1 ページあたりの件数。デフォルトは 20、最大 200 |
| urn | string | 否 | エンティティ URN による完全一致フィルター |
| entityType | string | 否 | エンティティタイプコード。ヘルスフィールドでフィルターまたは並べ替えを行う場合に必須 |
| provider | string | 否 | 単一のソースタイプ |
| providers | array[string] | 否 | 複数のソースタイプのリスト |
| search | string | 否 | あいまい検索。urn、name、display_name にマッチします |
| filters | json | 否 | attributes フィールドのフィルター。トップレベルのヘルスフィールドもサポートします。ヘルスフィルターでは同時に entityType を渡す必要があります |
| orderBy | string | 否 | 並べ替えフィールド。デフォルトは updatedAt。ヘルスフィールドで並べ替える場合は同時に entityType を渡す必要があります |
| order | string | 否 | 並べ替え方向。asc / desc をサポートし、デフォルトは desc |
filters の使用説明
- 通常の key はエンティティの
attributesにマッチします。healthStatus/healthScore/healthUpdateAt/brokenComponentsおよび snake_case エイリアスは、エンティティのトップレベル有効ヘルスフィールドにマッチします。 - 例:
{"env":["prod"],"project":["demo"]}。ヘルスフィルターの例:{"healthStatus":["warning"]}。 - ある属性で複数の値をマッチさせる必要がある場合は、統一して配列に入れて渡してください。
呼び出し時の注意事項
- これはページングインターフェースです。常に
pageIndexとpageSizeを明示的に渡すことを推奨します。 providerとprovidersはどちらか一方を使用することを推奨します。複数のソース値にはprovidersを優先して使用してください。- 返却結果の
pagination.totalCountは、現在のフィルター条件に一致したエンティティの総数を表します。 - 各エンティティは固定で
healthConfig/healthEnabled/healthScore/healthStatus/healthUpdateAtを返します。すべてのタイプは常に有効な設定に従って返され、バックエンドの readiness クリーンアップ進捗には依存しません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"pageIndex":1,"pageSize":20,"entityType":"database","filters":{"env":["prod"]},"orderBy":"updatedAt","order":"desc"}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | items、pagination、および共通 declaration のコンテナ。 |
| content.items | array<object> | 現在のページのエンティティ。 |
| content.items[].id | integer または string または null | 基盤となるエンティティレコードの識別子。値がない場合があります。顧客による特定には urn を使用します。 |
| content.items[].workspaceUUID | string | 認証ワークスペースの UUID。 |
| content.items[].urn | string | エンティティの正規 URN。以降の読み取り/変更/削除で使用します。 |
| content.items[].entityType | string | エンティティタイプコード。 |
| content.items[].provider | string | 収集/手動などの実際のソース。値はエンティティのレポートによって決まります。 |
| content.items[].name | string | エンティティ名。 |
| content.items[].displayName | string | エンティティの表示名。空値を許可します。 |
| content.items[].attributes | object | エンティティの動的属性。一覧ではクエリサービスが投影し、詳細では利用可能な属性を完全に読み取ります。 |
| content.items[].attributes.フィールド名 | JSON | 対応するタイプの DataSchema およびレポートされた実際のフィールド。env/project/owner/custom_tags/関係設定/ヘルス上書きフィールドなどがあり、すべてのエンティティに必ず存在するわけではありません。 |
| content.items[].telemetrySelectors | array または object | 既存のテレメトリ関連付け JSON。基盤の空値は正規化により {} になる場合があり、常に配列であることは保証されません。 |
| content.items[].telemetrySelectors[] | JSON | 各テレメトリ関連付けの動的項目。元の設定どおりに保持され、クエリ結果ではありません。 |
| content.items[].sourceMetadata | object | ソースの元メタデータ。一覧では空オブジェクトになる場合があります。詳細ではこのデータを明示的にリクエストし、具体的なキーはソースによって異なります。 |
| content.items[].sourceMetadata.フィールド名 | JSON | ソースシステムのカスタムメタ情報。汎用的な必須プロトコルとして扱うべきではありません。 |
| content.items[].healthScore | integer または null | 有効なヘルススコア。負値/値なしは null に正規化されます。ヘルス無効時は null であり、直接 0 と等しくありません。 |
| content.items[].healthStatus | string | healthy/warning/critical/unknown。ヘルス無効時は unknown です。 |
| content.items[].healthUpdateAt | string または null | ヘルス更新時刻。通常は YYYY-MM-DD HH:mm:ss です。無効/値なしの場合は null です。 |
| content.items[].createdAt | string または null | 作成時刻。通常は YYYY-MM-DD HH:mm:ss で、サービスの形式に従って返されます。 |
| content.items[].updatedAt | string または null | 最終更新時刻。作成時刻と同じ形式です。 |
| content.items[].healthConfig | object | エンティティの上書きポリシー。タイプポリシーのコピーではありません。 |
| content.items[].healthConfig.mode | string | inherit/func/disabled。履歴で func_id のみの場合は func に正規化されます。 |
| content.items[].healthConfig.funcId | string | func モードでのみ出現する関数 UUID。 |
| content.items[].healthEnabled | boolean | タイプとエンティティ設定を総合した有効スイッチ。タイプが disabled の場合、エンティティが custom であっても有効化できません。 |
| content.items[].entityStatus | string | online/offline。旧データではデフォルトで online です。ステータスはヘルスレベルと等しくありません。 |
| content.items[].lifecycleManaged | boolean | エンティティのライフサイクル管理対象かどうか。デフォルトは false です。 |
| content.items[].lastReportedAt | integer または null | 最新レポートの Unix 秒。値なしの場合は null です。 |
| content.items[].offlineAt | integer または null | オフラインの Unix 秒。未オフラインの場合は null です。 |
| content.items[].deleteAt | integer または null | ライフサイクルクリーンアップ予定の Unix 秒。未スケジュールの場合は null です。今回の API 削除時刻ではありません。 |
| content.items[].statusUpdatedAt | integer または null | エンティティステータスの更新時刻(Unix 秒)。値なしの場合は null です。 |
| content.items[].teamInfo | array<object> | owner に基づいて解決されたチーム概要。履歴参照が見つからない場合は偽のチームを構築しません。 |
| content.items[].teamInfo[].uuid | string | チームの group_ UUID。 |
| content.items[].teamInfo[].type | string | 通常は team。 |
| content.items[].teamInfo[].name | string | 現在のチーム名。 |
| content.items[].teamInfo[].members | array | チームメンバーの元 JSON。具体的なメンバーフィールドはチーム管理の契約に従い、このページのために追加で全メンバー詳細を照会しません。 |
| content.items[].teamInfo[].members[] | JSON | チームに保存されたメンバー要素。アカウント識別子/オブジェクトの場合があり、チーム詳細を基準とします。 |
| content.items[].tagsInfo | array<object> | 現在のワークスペースに存在するタグ概要。未解決の場合は [] です。 |
| content.items[].tagsInfo[].name | string | タグ名。 |
| content.items[].tagsInfo[].uuid | string | タグ UUID。 |
| content.items[].tagsInfo[].colour | string | 色。値なしの場合は空文字列です。 |
| content.items[].tagsInfo[].scope | array<string> | 有効なスコープ配列。履歴値が欠落している場合は [all] に正規化され、all は他のスコープと混用できません。 |
| content.items[].tagsInfo[].scope[] | string | all/scene/monitor/dialing/security/infrastructure/catalog。タグの現在の設定に従って返されます。 |
| content.pagination | object | ページング情報。content 内に保持され、pageInfo として上位に持ち上げられる構造ではありません。 |
| content.pagination.pageIndex | integer | 現在のページ。1 から始まります。 |
| content.pagination.pageSize | integer | 実際の 1 ページあたりのサイズ。 |
| content.pagination.count | integer | このページの件数。 |
| content.pagination.totalCount | integer | 現在のフィルター条件におけるエンティティの総数。ワークスペース全体の無条件総数ではありません。 |
| content.declaration | object | 共通宣言。items の各要素に個別に挿入されるものではありません。 |
{
"code": 200,
"content": {
"items": [
{
"id": null,
"workspaceUUID": "wksp_example",
"urn": "urn:database:default:demo",
"entityType": "database",
"provider": "manual",
"name": "demo",
"displayName": "Demo database",
"attributes": {
"env": "prod",
"project": "demo"
},
"telemetrySelectors": {},
"sourceMetadata": {},
"healthScore": null,
"healthStatus": "unknown",
"healthUpdateAt": null,
"createdAt": "2026-11-18 10:00:00",
"updatedAt": "2026-11-18 10:00:00",
"healthConfig": {
"mode": "inherit"
},
"healthEnabled": false,
"entityStatus": "online",
"lifecycleManaged": false,
"lastReportedAt": null,
"offlineAt": null,
"deleteAt": null,
"statusUpdatedAt": null,
"teamInfo": [],
"tagsInfo": []
}
],
"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 ファイル形式エラー | 配列/文字列ではなく、例に従ってオブジェクトを送信してください。 |
| 406 | ft.InvalidParameter | ヘルスフィルター/並べ替えを使用しているが entityType が欠落 | パラメータ {} が無効 |
対象のエンティティタイプコードを明示的に入力してください。属性の同名フィールドは attributes. プレフィックスで曖昧さを排除します。 |
| 500 | ft.InternalServerError | ダウンストリームクエリの失敗/タイムアウト、成功データの形状異常、またはタグ/チーム/時刻のフォーマット失敗 | 内部エラー | クエリ範囲を絞ってから適切に再試行してください。継続的に失敗する場合は traceId とフィルター条件を保持して調査し、今回の書き込みに起因すると決めつけないでください。 |
| 406 | ft.ParameterValidationFailed | 保存済みタグの scope が不正で、タグ概要の読み取り時に検証が失敗 | invalid scope | message=invalid scope の場合は、管理者が関連タグの履歴スコープ(all または有効なスコープ配列)を修正します。エンティティのクエリパラメータを繰り返し変更するものではありません。 |