コンテンツにスキップ

統合カタログのエンティティ詳細



POST /api/v1/unified_catalog/entity/get

概要

完全な URN でエンティティ詳細、ソースメタデータ、1ホップのシステム関係を読み取ります。

呼び出し前および使用手順

リストの items[].urn から対象を取得し、返された元の URN をそのまま後続の操作に使用します。存在しない場合は 404 を返し、{} でエンティティの存在を示すことはありません。詳細には teamInfo/tagsInfo と1ホップの systemRelationInfo が含まれます。関係エンドポイントのサマリーの attributes は完全に返されますが、エンドポイントのテレメトリ/ソースの大きなフィールドは追加で提供されません。

すべてのエンティティタイプは有効なヘルス設定に従って処理され、バックエンドの履歴クリーンアップの進行状況には依存しません。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 リクエストパラメータ

パラメータ名 型 必須 説明
urn string Y 読み取り/削除時は必須で、先頭と末尾の空白を除去した後に空でない必要があります。リスト/統計では任意の完全一致フィルタです。変更時は元の URN を明示的に入力し、名前変更時に別のエンティティが作成されるのを避けることを推奨します。
null を許可: False
例: urn:database:default:demo
取得または入力方法: このワークスペースのエンティティリストの items[].urn から取得し、完全な URN をそのまま使用することを優先します。

パラメータ補足説明

リクエストパラメータの説明

パラメータ名 型 必須 説明
urn string はい 対象エンティティの一意の URN

戻り値の説明

  • エンティティの基本情報、attributes、teamInfo、tagsInfo を返します。
  • systemRelationInfo は現在のエンティティの1ホップの直接システム関係リストです。
  • healthConfig/healthEnabled/healthScore/healthStatus/healthUpdateAt を固定で返します。すべてのタイプは常に有効な設定に従って返され、バックエンドの readiness クリーンアップの進行状況には依存しません。

呼び出し時の注意事項

  • systemRelationInfo は再帰的に展開されず、直接関係のみを返します。
  • systemRelationInfo 内の関係両端のエンティティサマリーの attributes は全量で返されます。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/entity/get' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"urn":"urn:database:default:demo"}'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。

フィールド 型 説明
content object 対象エンティティの詳細。
content.id integer または string または null 基盤となるエンティティレコードの識別子。値がない場合があります。顧客による特定には urn を使用します。
content.workspaceUUID string 認証されたワークスペースの UUID。
content.urn string エンティティの正規 URN。後続の読み取り/変更/削除で使用します。
content.entityType string エンティティタイプのコード。
content.provider string 収集/手動などの実際のソース。値はエンティティの報告によって決まります。
content.name string エンティティ名。
content.displayName string エンティティの表示名。空の場合があります。
content.attributes object エンティティの動的属性。リストではクエリサービスによる投影、詳細では完全に利用可能な属性を読み取ります。
content.attributes.字段名 JSON 対応するタイプの DataSchema および報告された実際のフィールド。env/project/owner/custom_tags/関係設定/ヘルス上書きフィールドなどがあり、すべてのエンティティに必ず存在するわけではありません。
content.telemetrySelectors array または object 既存のテレメトリ関連付け JSON。基盤の空値は正規化されて {} になる場合があり、常に配列であることは保証されません。
content.telemetrySelectors[] JSON 各テレメトリ関連付けの動的項目。元の設定のまま保持されます。クエリ結果ではありません。
content.sourceMetadata object ソースの元メタデータ。リストでは空オブジェクトの場合があります。詳細ではこのデータを明示的に要求し、具体的なキーはソースに依存します。
content.sourceMetadata.字段名 JSON ソースシステムのカスタムメタ情報。汎用的な必須プロトコルとして扱うべきではありません。
content.healthScore integer または null 有効なヘルススコア。負値/値なしは null に正規化されます。ヘルスが無効な場合は null であり、直接 0 と等しくなることはありません。
content.healthStatus string healthy/warning/critical/unknown。ヘルスが無効な場合は unknown です。
content.healthUpdateAt string または null ヘルスの更新時刻。通常は YYYY-MM-DD HH:mm:ss。無効/値なしの場合は null です。
content.createdAt string または null 作成時刻。通常は YYYY-MM-DD HH:mm:ss で、サービスの形式に従って返されます。
content.updatedAt string または null 最終更新時刻。作成時刻と同じ形式です。
content.healthConfig object エンティティの上書きポリシー。タイプポリシーのコピーではありません。
content.healthConfig.mode string inherit/func/disabled。履歴で func_id のみの場合は func に正規化されます。
content.healthConfig.funcId string func モードの場合にのみ現れる関数 UUID。
content.healthEnabled boolean タイプとエンティティ設定を総合した有効スイッチ。タイプが disabled の場合、エンティティの custom も有効にできません。
content.entityStatus string online/offline。古いデータでは省略時に online となります。ステータスはヘルスレベルとは異なります。
content.lifecycleManaged boolean エンティティのライフサイクル管理対象かどうか。省略時は false。
content.lastReportedAt integer または null 最新報告の Unix 秒。値なしの場合は null。
content.offlineAt integer または null オフラインの Unix 秒。未オフラインの場合は null。
content.deleteAt integer または null ライフサイクルによるクリーンアップ予定の Unix 秒。未スケジュールの場合は null。今回の API 削除時刻ではありません。
content.statusUpdatedAt integer または null エンティティステータスの更新時刻の Unix 秒。値なしの場合は null。
content.teamInfo array<object> owner に基づいて解決されたチームサマリー。履歴参照が見つからない場合は偽のチームを構築しません。
content.teamInfo[].uuid string チーム group_ UUID。
content.teamInfo[].type string 通常は team。
content.teamInfo[].name string 現在のチーム名。
content.teamInfo[].members array チームメンバーの元 JSON。具体的なメンバーフィールドはチーム管理の契約に従い、このページで追加で全メンバー詳細を照会することはありません。
content.teamInfo[].members[] JSON チームに保存されたメンバー要素。アカウント識別子/オブジェクトの場合があり、チーム詳細を優先します。
content.tagsInfo array<object> 現在のワークスペースに存在するタグサマリー。未解決の場合は []。
content.tagsInfo[].name string タグ名。
content.tagsInfo[].uuid string タグ UUID。
content.tagsInfo[].colour string 色。値なしの場合は空文字列。
content.tagsInfo[].scope array<string> 有効なスコープ配列。欠落した履歴値は [all] に正規化され、all は他の範囲と混在できません。
content.tagsInfo[].scope[] string all/scene/monitor/dialing/security/infrastructure/catalog。タグの現在の設定に従って返されます。
content.systemRelationInfo array<object> 1ホップの直接システム関係。再帰的には展開されません。
content.systemRelationInfo[].id integer または string または null 関係レコードの識別子。
content.systemRelationInfo[].workspaceUUID string 所属ワークスペース。
content.systemRelationInfo[].sourceUrn string ソースノードの URN。
content.systemRelationInfo[].targetUrn string ターゲットノードの URN。
content.systemRelationInfo[].relationType string 関係タイプ。例: contains/links。
content.systemRelationInfo[].组件配置键 JSON components 設定に一致する場合にその動的キーを追加し、既存の固定関係フィールドを保持します。
content.systemRelationInfo[].sourceUrnInfo object 関係エンドポイントのエンティティサマリー。利用可能な attributes を全量返します。エンドポイントが存在しない場合は {}。
content.systemRelationInfo[].sourceUrnInfo.id integer または string または null 基盤となるエンティティレコードの識別子。値がない場合があります。顧客による特定には urn を使用します。
content.systemRelationInfo[].sourceUrnInfo.workspaceUUID string 認証されたワークスペースの UUID。
content.systemRelationInfo[].sourceUrnInfo.urn string エンティティの正規 URN。後続の読み取り/変更/削除で使用します。
content.systemRelationInfo[].sourceUrnInfo.entityType string エンティティタイプのコード。
content.systemRelationInfo[].sourceUrnInfo.provider string 収集/手動などの実際のソース。値はエンティティの報告によって決まります。
content.systemRelationInfo[].sourceUrnInfo.name string エンティティ名。
content.systemRelationInfo[].sourceUrnInfo.displayName string エンティティの表示名。空の場合があります。
content.systemRelationInfo[].sourceUrnInfo.attributes object エンティティの動的属性。リストではクエリサービスによる投影、詳細では完全に利用可能な属性を読み取ります。
content.systemRelationInfo[].sourceUrnInfo.attributes.字段名 JSON 対応するタイプの DataSchema および報告された実際のフィールド。env/project/owner/custom_tags/関係設定/ヘルス上書きフィールドなどがあり、すべてのエンティティに必ず存在するわけではありません。
content.systemRelationInfo[].sourceUrnInfo.healthScore integer または null 有効なヘルススコア。負値/値なしは null に正規化されます。ヘルスが無効な場合は null であり、直接 0 と等しくなることはありません。
content.systemRelationInfo[].sourceUrnInfo.healthStatus string healthy/warning/critical/unknown。ヘルスが無効な場合は unknown です。
content.systemRelationInfo[].sourceUrnInfo.createdAt string または null 作成時刻。通常は YYYY-MM-DD HH:mm:ss で、サービスの形式に従って返されます。
content.systemRelationInfo[].sourceUrnInfo.updatedAt string または null 最終更新時刻。作成時刻と同じ形式です。
content.systemRelationInfo[].sourceUrnInfo.entityStatus string online/offline。古いデータでは省略時に online となります。ステータスはヘルスレベルとは異なります。
content.systemRelationInfo[].sourceUrnInfo.lifecycleManaged boolean エンティティのライフサイクル管理対象かどうか。省略時は false。
content.systemRelationInfo[].sourceUrnInfo.lastReportedAt integer または null 最新報告の Unix 秒。値なしの場合は null。
content.systemRelationInfo[].sourceUrnInfo.offlineAt integer または null オフラインの Unix 秒。未オフラインの場合は null。
content.systemRelationInfo[].sourceUrnInfo.deleteAt integer または null ライフサイクルによるクリーンアップ予定の Unix 秒。未スケジュールの場合は null。今回の API 削除時刻ではありません。
content.systemRelationInfo[].sourceUrnInfo.statusUpdatedAt integer または null エンティティステータスの更新時刻の Unix 秒。値なしの場合は null。
content.systemRelationInfo[].targetUrnInfo object 関係エンドポイントのエンティティサマリー。利用可能な attributes を全量返します。エンドポイントが存在しない場合は {}。
content.systemRelationInfo[].targetUrnInfo.id integer または string または null 基盤となるエンティティレコードの識別子。値がない場合があります。顧客による特定には urn を使用します。
content.systemRelationInfo[].targetUrnInfo.workspaceUUID string 認証されたワークスペースの UUID。
content.systemRelationInfo[].targetUrnInfo.urn string エンティティの正規 URN。後続の読み取り/変更/削除で使用します。
content.systemRelationInfo[].targetUrnInfo.entityType string エンティティタイプのコード。
content.systemRelationInfo[].targetUrnInfo.provider string 収集/手動などの実際のソース。値はエンティティの報告によって決まります。
content.systemRelationInfo[].targetUrnInfo.name string エンティティ名。
content.systemRelationInfo[].targetUrnInfo.displayName string エンティティの表示名。空の場合があります。
content.systemRelationInfo[].targetUrnInfo.attributes object エンティティの動的属性。リストではクエリサービスによる投影、詳細では完全に利用可能な属性を読み取ります。
content.systemRelationInfo[].targetUrnInfo.attributes.字段名 JSON 対応するタイプの DataSchema および報告された実際のフィールド。env/project/owner/custom_tags/関係設定/ヘルス上書きフィールドなどがあり、すべてのエンティティに必ず存在するわけではありません。
content.systemRelationInfo[].targetUrnInfo.healthScore integer または null 有効なヘルススコア。負値/値なしは null に正規化されます。ヘルスが無効な場合は null であり、直接 0 と等しくなることはありません。
content.systemRelationInfo[].targetUrnInfo.healthStatus string healthy/warning/critical/unknown。ヘルスが無効な場合は unknown です。
content.systemRelationInfo[].targetUrnInfo.createdAt string または null 作成時刻。通常は YYYY-MM-DD HH:mm:ss で、サービスの形式に従って返されます。
content.systemRelationInfo[].targetUrnInfo.updatedAt string または null 最終更新時刻。作成時刻と同じ形式です。
content.systemRelationInfo[].targetUrnInfo.entityStatus string online/offline。古いデータでは省略時に online となります。ステータスはヘルスレベルとは異なります。
content.systemRelationInfo[].targetUrnInfo.lifecycleManaged boolean エンティティのライフサイクル管理対象かどうか。省略時は false。
content.systemRelationInfo[].targetUrnInfo.lastReportedAt integer または null 最新報告の Unix 秒。値なしの場合は null。
content.systemRelationInfo[].targetUrnInfo.offlineAt integer または null オフラインの Unix 秒。未オフラインの場合は null。
content.systemRelationInfo[].targetUrnInfo.deleteAt integer または null ライフサイクルによるクリーンアップ予定の Unix 秒。未スケジュールの場合は null。今回の API 削除時刻ではありません。
content.systemRelationInfo[].targetUrnInfo.statusUpdatedAt integer または null エンティティステータスの更新時刻の Unix 秒。値なしの場合は null。
content.declaration object 共通宣言。
{
  "code": 200,
  "content": {
    "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": [],
    "systemRelationInfo": [],
    "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 urn が空白除去後に空 パラメータ {} が無効 現在のワークスペースのリストにある完全な URN を渡します。
404 ft.NotFoundEntity 現在のワークスペースで対象エンティティが見つからない 指定されたエンティティが見つかりません ワークスペース、URN、および収集/報告が完了しているかを確認します。タイプ UUID に置き換えないでください。
500 ft.InternalServerError ダウンストリームクエリの失敗/タイムアウト、成功データの形状異常、またはタグ/チーム/時刻のフォーマット失敗 内部エラー クエリ範囲を絞って適切に再試行します。継続的に失敗する場合は traceId とフィルタ条件を保持して調査し、今回の書き込みに起因すると決めつけないでください。
406 ft.ParameterValidationFailed 保存済みタグの scope が不正で、タグサマリーの読み取り時に検証に失敗 invalid scope message=invalid scope の場合は、管理者が関連タグの履歴スコープ(all または有効な範囲配列)を修正します。エンティティのクエリパラメータを繰り返し変更するのではありません。

フィードバック

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