統合カタログ トポロジクエリ¶
POST /api/v1/unified_catalog/topology/query
概要¶
統合カタログのトポロジ関係を照会します。
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| entityType | string | エンティティタイプコード。filters または orderBy にヘルスフィールドが含まれる場合は必須 空を許可: False |
|
| urn | string | フォーカスエンティティ URN 空を許可: False |
|
| providers | array | ソースタイプリスト 空を許可: False |
|
| relationTypes | array | 関係タイプリスト。現在は主に links と contains を使用 空を許可: False |
|
| orderBy | string | 起点エンティティのソートフィールド。ヘルスフィールドを使用する場合は entityType を指定必須 空を許可: False |
|
| filters | json | エンティティフィルタフィールド。attributes 内の任意のフィールドをサポート 空を許可: False |
|
| groupByFields | array | 配列順に従った多階層グループ化。entityType はエンティティのトップレベルフィールドを読み取り、その他のフィールドは attributes を読み取る 空を許可: False |
|
| search | string | 検索キーワード 空を許可: False |
パラメータ補足説明¶
リクエストパラメータ説明
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 'https://openapi.guance.com/api/v1/unified_catalog/topology/query' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"entityType":"service","filters":{"project":["demo"]},"groupByFields":["project"]}'
レスポンス¶
{
"code": 200,
"content": {
"items": [
{
"relationType": "links",
"sourceUrn": "urn:system:default:core",
"targetUrn": "urn:service:default:demo",
"sourceUrnInfo": {
"urn": "urn:system:default:core",
"attributes": {
"project": "demo"
},
"healthConfig": {
"mode": "inherit"
},
"healthEnabled": true,
"healthScore": 67,
"healthStatus": "warning",
"healthUpdateAt": "2026-08-11 22:40:00"
},
"targetUrnInfo": {
"urn": "urn:service:default:demo",
"attributes": {
"project": "demo",
"env": "prod"
},
"healthConfig": {},
"healthEnabled": false,
"healthScore": null,
"healthStatus": "unknown",
"healthUpdateAt": null
}
}
],
"groupInfo": {
"groupByLayers": [
{
"groupByField": "project",
"groupByData": {
"demo": {
"data": [
{
"urn": "urn:system:default:core",
"entityType": "system",
"healthScore": 67,
"healthStatus": "warning",
"healthConfig": {
"mode": "inherit"
},
"healthEnabled": true,
"attributes": {
"project": "demo"
}
},
{
"urn": "urn:service:default:demo",
"entityType": "service",
"healthScore": null,
"healthStatus": "unknown",
"healthConfig": {},
"healthEnabled": false,
"attributes": {
"project": "demo",
"env": "prod"
}
}
]
}
}
}
],
"noGroupData": []
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-XXXX"
}