コンテンツにスキップ

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



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 または有効なスコープ配列)を修正します。エンティティのクエリパラメータを繰り返し変更するものではありません。

フィードバック

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