統合カタログトポロジークエリ¶
POST /api/v1/unified_catalog/topology/query
概要¶
フィルターで指定した起点からカタログエンティティのトポロジーを展開し、ノード属性でグループ化します。
呼び出し前の準備と使用手順¶
entityType/urn/providers/search/filters/orderBy は起点エンティティの選択に作用します。展開後には他のタイプ/ソースのノードが現れることがあり、返却されるすべてのノードを再度フィルターするものではありません。relationTypes はリレーションの種類をフィルターします。公開 Body では maxDepth/nodeLimit が宣言されていません。現在のアダプターはデフォルトの最大深度 10 とノード上限 200 を使用しており、これらの未宣言フィールドを送信して結果の拡大を約束することはできません。本結果はワークスペース全体の完全なグラフや総数を保証するものではありません。
groupByFields は指定順に複数階層のノードグループ化を行います。entityType/entityStatus はトップレベルから読み取り、それ以外は attributes の生のキーから読み取ります。配列属性では 1 つのノードが複数のバケットに入る可能性があります。グループ内の data と再帰的な groupByLayers、noGroupData をすべて走査する必要があり、バケットの件数合計を一意なノード数として扱うことはできません。グループ化なしの場合、すべてのノードは noGroupData に入り、孤立ノードがグループ化データにのみ現れることもあります。リレーション端点の 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 を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| providers[*] | string | 配列内の 1 つのソースです。親配列を省略した場合はフィルターしません。 例: manual取得または入力方法: 既存エンティティの単一の provider 値。 |
|
| filters.属性フィールド名 | string | 動的キーです。スカラー候補値の配列を推奨します。任意の DQL 式をフィールド名として扱うことはできません。urn/provider/entityType や healthStatus などのトップレベル組み込みフィールド、および snake_case エイリアスはトップレベルのまま維持されます。attributes/sourceMetadata/telemetrySelectors オブジェクト内のキーはフラット化されます。 例: ["prod"]取得または入力方法: 現在のエンティティの attributes の実際のフィールド名を使用します。複雑な値のフィルターセマンティクスは、保存済みフィールドタイプとクエリサービスの機能に従います。 |
|
| filters.属性フィールド名[*] | string | 同じフィールドの 1 つの候補値です。数値/ブール値は元の JSON タイプを維持し、null と文字列の null を混同しないでください。 例: prod取得または入力方法: 現在のフィールド候補値/既存エンティティの値から取得します。 |
|
| relationTypes[*] | string | links は通常「依存」、contains は通常「包含」を表します。エンティティタイプ/表示名ではありません。公開仕様では列挙による厳格な検証は行われず、その他の値はクエリサービスのサポートに従います。 例: contains取得または入力方法: 既存のリレーションカテゴリ識別子。 |
|
| groupByFields[*] | string | 空白の項目はスキップされます。title/任意の DQL ではありません。配列値は非空のスカラーのみを重複排除して取得します。オブジェクト/ネストした配列はグループ値として使用できません。 例: project取得または入力方法: project/env などの生の属性キー、または entityType/entityStatus。 |
|
| entityType | string | 一覧/集計では任意です。トップレベルのヘルスフィールドでフィルター、集計、またはソートする場合は必須です。作成/変更時は必須で、空白を除去した後に空でない必要があります。エクスポート時は必須です。 null を許可: False 例: database取得または入力方法: エンティティタイプリスト の items[].entityType からコードを取得します。タイプ UUID/表示名ではありません。 |
|
| filters | json | 任意のオブジェクトです。{} は追加フィルターなしです。生の属性キー env は attributes.env に変換され、明示的な attributes.entityType はトップレベルの entityType として扱われません。同じフィールドの複数の候補値は配列に入れます。異なるフィールドはクエリサービスが組み合わせます。ヘルスフィールドには個別の有効な無効状態があり、使用方法を参照してください。 null を許可: False 例: {"env": ["prod"]}取得または入力方法: フィールド名はタイプの DataSchema/属性またはトポロジーフィールドリストから取得し、値はフィールド統計/既存エンティティから取得します。 |
|
| groupByFields | array | 任意です。配列の順序で複数階層のグループ化を決定します。[]/省略時は、返却されるすべてのノードが noGroupData に入ります。entityType/entityStatus はトップレベルから読み取り、それ以外は attributes の元のキーで読み取ります。attributes. プレフィックスは自動的に除去されません。配列属性では同じノードを複数のバケットに入れることができ、値が欠けている場合は後続の階層を試し、すべて欠けている場合は noGroupData に入ります。 null を許可: False 例: ["project", "env"]取得または入力方法: エンティティの attributes に既存のフィールド名からグループ化を選択します。組み込みで entityType/entityStatus をサポートします。 |
|
| orderBy | string | 任意です。デフォルトのソートはクエリサービスが updatedAt に従って処理します。ヘルスソートには entityType が必要です。タイプでヘルスが無効になっている場合、ヘルスソートは updatedAt desc に切り替わり、履歴のヘルス値ではソートしません。 null を許可: False 例: updatedAt取得または入力方法: タイプビュー/フィールドインターフェースからソート可能なフィールドを選択します。組み込みでは updatedAt/name/healthScore など、属性では attributes.env を使用します。 |
|
| providers | array | 任意のソース配列です。空でない場合は provider より優先されます。[] はソースフィルターを追加せず、空のソースのみを選択するわけではありません。公開配列では項目ごとの文字列検証は宣言されていないため、実際の文字列のみを使用することを推奨します。 null を許可: False 例: ["manual"]取得または入力方法: provider の field_value/count 候補バケットから実際のソース値を取得します。 |
|
| relationTypes | array | 任意です。省略/[] の場合は空リストを転送し、デフォルト範囲をクエリサービスが処理します。1 種類のリレーションのみを取得することは保証しません。複数の値はリレーションカテゴリの集合として扱われ、リレーションの方向は変更されません。 null を許可: False 例: ["links", "contains"]取得または入力方法: 既存のリレーションの relationType から値を取得します。本製品のエンティティ編集では links/contains が生成されます。 |
|
| search | string | トポロジークエリ時は起点エンティティの URN/name/display_name を検索します。filter_options では候補値キーワードの履歴互換パラメータであり、fieldValue が空でない場合に優先されます。2 つのシナリオを混同しないでください。 null を許可: False 例: demo取得または入力方法: 呼び出し元が検索キーワードを入力します。 |
|
| urn | string | 任意の起点エンティティ URN です。エンティティ一覧から取得します。指定しない場合は他の条件で起点を選択できます。厳密にそのノードのみを返すわけではなく、リレーションの展開により隣接するタイプ/ソースのノードが含まれます。 null を許可: False 例: urn:database:default:demo取得または入力方法: 本ワークスペースのエンティティ一覧 items[].urn から取得し、完全な URN をそのまま使用することを推奨します。 |
パラメータ補足説明¶
リクエストパラメータ説明
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| entityType | string | ヘルスクエリ時は必須 | 起点エンティティタイプのコード。filters/orderBy でヘルスフィールドを扱う場合は一意に指定する必要があります |
| urn | string | いいえ | 対象エンティティ URN |
| providers | array[string] | いいえ | 起点エンティティのソースタイプ一覧 |
| relationTypes | array[string] | いいえ | 返却が必要なリレーションタイプ一覧 |
| orderBy | string | いいえ | 起点エンティティのソートフィールド。ヘルスフィールドを使用する場合は entityType を渡す必要があります |
| filters | json | いいえ | 起点エンティティのフィルター条件。attributes の任意フィールドおよびトップレベルのヘルスフィールドをサポートします |
| groupByFields | array[string] | いいえ | トポロジーエンティティノードのグループ化フィールド一覧 |
| search | string | いいえ | 起点エンティティの検索キーワード |
groupByFields の使用説明
- 配列の順序に従って複数階層のグループ化を行います。例:
["project","env","serviceType"]。 entityTypeはエンティティのトップレベルフィールドから読み取り、その他のフィールドはエンティティのattributesから読み取ります。- グループ化はトポロジー結果内のエンティティノードに基づき、リレーションエッジに基づくものではありません。
groupInfo.groupByLayers[].groupByData.*.data[]とgroupInfo.noGroupData[]はhealthScore/healthStatusを返します。healthScoreは実際の0とnullを保持します。
呼び出し時の注意事項
entityType、providers、search、urn、filtersは起点エンティティの決定にのみ作用します。filtersがhealthStatus/healthScore/healthUpdateAt/brokenComponentsおよび snake_case エイリアスを扱う場合、またはorderByでヘルスフィールドを使用する場合は、entityTypeを渡す必要があります。Studio は有効な無効状態に従ってフィルター、ソートし、kodo 内で非同期クリーンアップ待ちの履歴ヘルス値を直接信頼しません。- 返却構造は
items + groupInfoに固定されています。 - プラットフォーム内のトポロジークエリ結果では、リレーション両端のエンティティサマリーの
attributesは全量返却されます。 - リレーション両端およびグループ化エンティティは、ヘルススイッチと結果を固定で返します。すべてのタイプは常にエンティティとタイプの有効な設定に従って計算され、バックグラウンドの readiness クリーンアップ進捗には依存しません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/topology/query' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"entityType":"service","filters":{"project":["demo"]},"relationTypes":["links","contains"],"groupByFields":["project"]}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.items | array<object> | トポロジーリレーションエッジの配列です。リレーションがない場合は [] です。ページネーションの totalCount は含みません。 |
| content.items[].id | integer または string または null | リレーションの識別情報に基づいて追加照会されるレコード識別子です。一致しない場合は null になることがあります。 |
| content.items[].workspaceUUID | string | 所属ワークスペース。 |
| content.items[].sourceUrn | string | ソースノード URN。 |
| content.items[].targetUrn | string | ターゲットノード URN。 |
| content.items[].relationType | string | リレーションカテゴリ。例: links/contains。 |
| content.items[].sourceUrnInfo | object | リレーション端点のサマリーです。見つからない場合は {} になることがあり、attributes は全量利用できます。teamInfo/tagsInfo/テレメトリ/ソースの大きなフィールドは付加されません。 |
| content.items[].sourceUrnInfo.id | integer または string または null | 基盤となるエンティティレコードの識別子です。値がない場合があります。顧客側の特定には urn を使用します。 |
| content.items[].sourceUrnInfo.workspaceUUID | string | 認証ワークスペース UUID。 |
| content.items[].sourceUrnInfo.urn | string | エンティティの正規 URN です。以降の読み取り/変更/削除に使用します。 |
| content.items[].sourceUrnInfo.entityType | string | エンティティタイプのコード。 |
| content.items[].sourceUrnInfo.provider | string | 収集/手動などの実際のソースです。値はエンティティのレポートによって決まります。 |
| content.items[].sourceUrnInfo.name | string | エンティティ名。 |
| content.items[].sourceUrnInfo.displayName | string | エンティティの表示名。空の場合があります。 |
| content.items[].sourceUrnInfo.attributes | object | エンティティの動的属性です。本トポロジーでは利用可能なすべての属性を返します。 |
| content.items[].sourceUrnInfo.attributes.フィールド名 | JSON | 対応するタイプの DataSchema およびレポートされる実際のフィールドです。env/project/owner/custom_tags/リレーション設定/ヘルスオーバーライドフィールドなどがあり、すべてのエンティティに必ず存在するわけではありません。 |
| content.items[].sourceUrnInfo.healthScore | integer または null | 有効なヘルススコアです。負値/値なしは null に正規化されます。ヘルスが無効な場合は null であり、直接 0 と等しくなるわけではありません。 |
| content.items[].sourceUrnInfo.healthStatus | string | healthy/warning/critical/unknown。ヘルスが無効な場合は unknown です。 |
| content.items[].sourceUrnInfo.healthUpdateAt | string または null | ヘルス更新日時です。通常は YYYY-MM-DD HH:mm:ss です。無効/値なしの場合は null です。 |
| content.items[].sourceUrnInfo.createdAt | string または null | 作成日時です。通常は YYYY-MM-DD HH:mm:ss で、サービスの形式に従って返されます。 |
| content.items[].sourceUrnInfo.updatedAt | string または null | 最終更新日時です。作成日時と同じ形式です。 |
| content.items[].sourceUrnInfo.healthConfig | object | エンティティのオーバーライドポリシーです。タイプポリシーのコピーではありません。 |
| content.items[].sourceUrnInfo.healthConfig.mode | string | inherit/func/disabled。履歴で func_id のみの場合は func に正規化されます。 |
| content.items[].sourceUrnInfo.healthConfig.funcId | string | func モードでのみ現れる関数 UUID。 |
| content.items[].sourceUrnInfo.healthEnabled | boolean | タイプとエンティティ設定を総合した有効スイッチです。タイプが disabled の場合、エンティティが custom でも有効にできません。 |
| content.items[].sourceUrnInfo.entityStatus | string | online/offline。古いデータではデフォルトで online です。ステータスはヘルスレベルと等しくありません。 |
| content.items[].sourceUrnInfo.lifecycleManaged | boolean | エンティティのライフサイクル管理対象かどうか。デフォルトは false です。 |
| content.items[].sourceUrnInfo.lastReportedAt | integer または null | 最終レポートの Unix 秒です。値なしの場合は null です。 |
| content.items[].sourceUrnInfo.offlineAt | integer または null | オフラインの Unix 秒です。未オフラインの場合は null です。 |
| content.items[].sourceUrnInfo.deleteAt | integer または null | ライフサイクルクリーンアップ予定の Unix 秒です。未安排の場合は null です。今回の API 削除時刻ではありません。 |
| content.items[].sourceUrnInfo.statusUpdatedAt | integer または null | エンティティステータスの更新 Unix 秒です。値なしの場合は null です。 |
| content.items[].targetUrnInfo | object | リレーション端点のサマリーです。見つからない場合は {} になることがあり、attributes は全量利用できます。teamInfo/tagsInfo/テレメトリ/ソースの大きなフィールドは付加されません。 |
| content.items[].targetUrnInfo.id | integer または string または null | 基盤となるエンティティレコードの識別子です。値がない場合があります。顧客側の特定には urn を使用します。 |
| content.items[].targetUrnInfo.workspaceUUID | string | 認証ワークスペース UUID。 |
| content.items[].targetUrnInfo.urn | string | エンティティの正規 URN です。以降の読み取り/変更/削除に使用します。 |
| content.items[].targetUrnInfo.entityType | string | エンティティタイプのコード。 |
| content.items[].targetUrnInfo.provider | string | 収集/手動などの実際のソースです。値はエンティティのレポートによって決まります。 |
| content.items[].targetUrnInfo.name | string | エンティティ名。 |
| content.items[].targetUrnInfo.displayName | string | エンティティの表示名。空の場合があります。 |
| content.items[].targetUrnInfo.attributes | object | エンティティの動的属性です。本トポロジーでは利用可能なすべての属性を返します。 |
| content.items[].targetUrnInfo.attributes.フィールド名 | JSON | 対応するタイプの DataSchema およびレポートされる実際のフィールドです。env/project/owner/custom_tags/リレーション設定/ヘルスオーバーライドフィールドなどがあり、すべてのエンティティに必ず存在するわけではありません。 |
| content.items[].targetUrnInfo.healthScore | integer または null | 有効なヘルススコアです。負値/値なしは null に正規化されます。ヘルスが無効な場合は null であり、直接 0 と等しくなるわけではありません。 |
| content.items[].targetUrnInfo.healthStatus | string | healthy/warning/critical/unknown。ヘルスが無効な場合は unknown です。 |
| content.items[].targetUrnInfo.healthUpdateAt | string または null | ヘルス更新日時です。通常は YYYY-MM-DD HH:mm:ss です。無効/値なしの場合は null です。 |
| content.items[].targetUrnInfo.createdAt | string または null | 作成日時です。通常は YYYY-MM-DD HH:mm:ss で、サービスの形式に従って返されます。 |
| content.items[].targetUrnInfo.updatedAt | string または null | 最終更新日時です。作成日時と同じ形式です。 |
| content.items[].targetUrnInfo.healthConfig | object | エンティティのオーバーライドポリシーです。タイプポリシーのコピーではありません。 |
| content.items[].targetUrnInfo.healthConfig.mode | string | inherit/func/disabled。履歴で func_id のみの場合は func に正規化されます。 |
| content.items[].targetUrnInfo.healthConfig.funcId | string | func モードでのみ現れる関数 UUID。 |
| content.items[].targetUrnInfo.healthEnabled | boolean | タイプとエンティティ設定を総合した有効スイッチです。タイプが disabled の場合、エンティティが custom でも有効にできません。 |
| content.items[].targetUrnInfo.entityStatus | string | online/offline。古いデータではデフォルトで online です。ステータスはヘルスレベルと等しくありません。 |
| content.items[].targetUrnInfo.lifecycleManaged | boolean | エンティティのライフサイクル管理対象かどうか。デフォルトは false です。 |
| content.items[].targetUrnInfo.lastReportedAt | integer または null | 最終レポートの Unix 秒です。値なしの場合は null です。 |
| content.items[].targetUrnInfo.offlineAt | integer または null | オフラインの Unix 秒です。未オフラインの場合は null です。 |
| content.items[].targetUrnInfo.deleteAt | integer または null | ライフサイクルクリーンアップ予定の Unix 秒です。未安排の場合は null です。今回の API 削除時刻ではありません。 |
| content.items[].targetUrnInfo.statusUpdatedAt | integer または null | エンティティステータスの更新 Unix 秒です。値なしの場合は null です。 |
| content.groupInfo | object | 返却されたエンティティノードに基づいて構築されるグループです。リレーションエッジの件数によるグループ化ではありません。 |
| content.groupInfo.groupByLayers | array<object> | トップレベルのグループ化階層です。[] はグループ化なしです。 |
| content.groupInfo.groupByLayers[].groupByField | string | 現在のグループ化フィールド。 |
| content.groupInfo.groupByLayers[].groupByData | object | グループ値を文字列とする動的キーのバケットマッピング。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値 | object | このグループのノードデータおよび任意のサブグループ。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data | array<object> | 現在の階層でサブグループに入らなかったノードです。リーフ階層ではこのグループのすべてのノードになります。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.groupByLayers | array<object> | 任意の次階層グループ化です。再帰構造は groupInfo.groupByLayers と同じです。その中のノードを無視することはできません。 |
| content.groupInfo.noGroupData | array<object> | すべてのグループ化フィールドに一致しなかったノードです。groupByFields がない場合は、返却されたすべてのノードを保持します。 |
| content.declaration | object | 外側の共通宣言のみです。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].urn | string | エンティティの正規 URN です。以降の読み取り/変更/削除に使用します。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].entityType | string | エンティティタイプのコード。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].provider | string | 収集/手動などの実際のソースです。値はエンティティのレポートによって決まります。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].name | string | エンティティ名。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].displayName | string | エンティティの表示名。空の場合があります。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].attributes | object | エンティティの動的属性です。本トポロジーでは利用可能なすべての属性を返します。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].attributes.フィールド名 | JSON | 対応するタイプの DataSchema およびレポートされる実際のフィールドです。env/project/owner/custom_tags/リレーション設定/ヘルスオーバーライドフィールドなどがあり、すべてのエンティティに必ず存在するわけではありません。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].healthScore | integer または null | 有効なヘルススコアです。負値/値なしは null に正規化されます。ヘルスが無効な場合は null であり、直接 0 と等しくなるわけではありません。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].healthStatus | string | healthy/warning/critical/unknown。ヘルスが無効な場合は unknown です。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].healthUpdateAt | string または null | ヘルス更新日時です。通常は YYYY-MM-DD HH:mm:ss です。無効/値なしの場合は null です。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].healthConfig | object | エンティティのオーバーライドポリシーです。タイプポリシーのコピーではありません。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].healthConfig.mode | string | inherit/func/disabled。履歴で func_id のみの場合は func に正規化されます。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].healthConfig.funcId | string | func モードでのみ現れる関数 UUID。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].healthEnabled | boolean | タイプとエンティティ設定を総合した有効スイッチです。タイプが disabled の場合、エンティティが custom でも有効にできません。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].entityStatus | string | online/offline。古いデータではデフォルトで online です。ステータスはヘルスレベルと等しくありません。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].lifecycleManaged | boolean | エンティティのライフサイクル管理対象かどうか。デフォルトは false です。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].lastReportedAt | integer または null | 最終レポートの Unix 秒です。値なしの場合は null です。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].offlineAt | integer または null | オフラインの Unix 秒です。未オフラインの場合は null です。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].deleteAt | integer または null | ライフサイクルクリーンアップ予定の Unix 秒です。未安排の場合は null です。今回の API 削除時刻ではありません。 |
| content.groupInfo.groupByLayers[].groupByData.グループ値.data[].statusUpdatedAt | integer または null | エンティティステータスの更新 Unix 秒です。値なしの場合は null です。 |
| content.groupInfo.noGroupData[].urn | string | エンティティの正規 URN です。以降の読み取り/変更/削除に使用します。 |
| content.groupInfo.noGroupData[].entityType | string | エンティティタイプのコード。 |
| content.groupInfo.noGroupData[].provider | string | 収集/手動などの実際のソースです。値はエンティティのレポートによって決まります。 |
| content.groupInfo.noGroupData[].name | string | エンティティ名。 |
| content.groupInfo.noGroupData[].displayName | string | エンティティの表示名。空の場合があります。 |
| content.groupInfo.noGroupData[].attributes | object | エンティティの動的属性です。本トポロジーでは利用可能なすべての属性を返します。 |
| content.groupInfo.noGroupData[].attributes.フィールド名 | JSON | 対応するタイプの DataSchema およびレポートされる実際のフィールドです。env/project/owner/custom_tags/リレーション設定/ヘルスオーバーライドフィールドなどがあり、すべてのエンティティに必ず存在するわけではありません。 |
| content.groupInfo.noGroupData[].healthScore | integer または null | 有効なヘルススコアです。負値/値なしは null に正規化されます。ヘルスが無効な場合は null であり、直接 0 と等しくなるわけではありません。 |
| content.groupInfo.noGroupData[].healthStatus | string | healthy/warning/critical/unknown。ヘルスが無効な場合は unknown です。 |
| content.groupInfo.noGroupData[].healthUpdateAt | string または null | ヘルス更新日時です。通常は YYYY-MM-DD HH:mm:ss です。無効/値なしの場合は null です。 |
| content.groupInfo.noGroupData[].healthConfig | object | エンティティのオーバーライドポリシーです。タイプポリシーのコピーではありません。 |
| content.groupInfo.noGroupData[].healthConfig.mode | string | inherit/func/disabled。履歴で func_id のみの場合は func に正規化されます。 |
| content.groupInfo.noGroupData[].healthConfig.funcId | string | func モードでのみ現れる関数 UUID。 |
| content.groupInfo.noGroupData[].healthEnabled | boolean | タイプとエンティティ設定を総合した有効スイッチです。タイプが disabled の場合、エンティティが custom でも有効にできません。 |
| content.groupInfo.noGroupData[].entityStatus | string | online/offline。古いデータではデフォルトで online です。ステータスはヘルスレベルと等しくありません。 |
| content.groupInfo.noGroupData[].lifecycleManaged | boolean | エンティティのライフサイクル管理対象かどうか。デフォルトは false です。 |
| content.groupInfo.noGroupData[].lastReportedAt | integer または null | 最終レポートの Unix 秒です。値なしの場合は null です。 |
| content.groupInfo.noGroupData[].offlineAt | integer または null | オフラインの Unix 秒です。未オフラインの場合は null です。 |
| content.groupInfo.noGroupData[].deleteAt | integer または null | ライフサイクルクリーンアップ予定の Unix 秒です。未安排の場合は null です。今回の API 削除時刻ではありません。 |
| content.groupInfo.noGroupData[].statusUpdatedAt | integer または null | エンティティステータスの更新 Unix 秒です。値なしの場合は null です。 |
{
"code": 200,
"content": {
"items": [
{
"id": null,
"workspaceUUID": "wksp_example",
"sourceUrn": "urn:service:default:api",
"targetUrn": "urn:database:default:demo",
"relationType": "links",
"sourceUrnInfo": {
"id": null,
"workspaceUUID": "wksp_example",
"urn": "urn:service:default:api",
"entityType": "service",
"provider": "manual",
"name": "api",
"displayName": "API",
"attributes": {
"project": "demo",
"env": "prod"
},
"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
},
"targetUrnInfo": {
"id": null,
"workspaceUUID": "wksp_example",
"urn": "urn:database:default:demo",
"entityType": "database",
"provider": "manual",
"name": "demo",
"displayName": "Demo database",
"attributes": {
"project": "demo"
},
"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
}
}
],
"groupInfo": {
"groupByLayers": [
{
"groupByField": "project",
"groupByData": {
"demo": {
"data": [
{
"urn": "urn:service:default:api",
"entityType": "service",
"provider": "manual",
"name": "api",
"displayName": "API",
"attributes": {
"project": "demo",
"env": "prod"
},
"healthScore": null,
"healthStatus": "unknown",
"healthUpdateAt": null,
"healthConfig": {
"mode": "inherit"
},
"healthEnabled": false,
"entityStatus": "online",
"lifecycleManaged": false,
"lastReportedAt": null,
"offlineAt": null,
"deleteAt": null,
"statusUpdatedAt": null
},
{
"urn": "urn:database:default:demo",
"entityType": "database",
"provider": "manual",
"name": "demo",
"displayName": "Demo database",
"attributes": {
"project": "demo"
},
"healthScore": null,
"healthStatus": "unknown",
"healthUpdateAt": null,
"healthConfig": {
"mode": "inherit"
},
"healthEnabled": false,
"entityStatus": "online",
"lifecycleManaged": false,
"lastReportedAt": null,
"offlineAt": null,
"deleteAt": null,
"statusUpdatedAt": null
}
]
}
}
}
],
"noGroupData": []
},
"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 | ヘルス filters/orderBy で entityType が一意に明示されていません | パラメータ{}が無効です |
単一のタイプコードを入力し、無効状態は null/unknown として処理し、混在タイプの履歴ヘルス値を使用しないでください。 |
| 500 | ft.InternalServerError | ダウンストリームクエリの失敗/タイムアウト、成功データの形状異常、またはタグ/チーム/時間のフォーマット失敗 | 内部エラー | クエリ範囲を絞ってから適切に再試行してください。継続的に失敗する場合は traceId とフィルター条件を保持して調査し、今回の書き込みに起因すると決めつけないでください。 |