統合カタログのエンティティ詳細¶
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 または有効な範囲配列)を修正します。エンティティのクエリパラメータを繰り返し変更するのではありません。 |