統合カタログのトポロジーフィールドフィルターオプション¶
POST /api/v1/unified_catalog/topology/filter_options
概要¶
指定したフィールドに基づいて、フィルター可能な候補値、可読ラベル、および件数を読み取ります。
呼び出し前および使用手順¶
fields の返却キーはリクエスト時の表記を保持します。裸の env と attributes.env は同等のクエリを実行した後、それぞれのリクエストキーに値を戻します。裸の owner はさらに、過去のアカウント/チーム UUID を名前に変換しようとし、見つからない場合は元の値にフォールバックします。名前で保存された owner も元の名前を保持し、すべての値が group_ UUID であることは保証されません。各 value は Python の str に従って文字列化されます。たとえば null→"None"、true→"True"、数値 3→"3" で、count は非負です。エンティティの field_value/count が JSON の値型を保持するのとは異なります。
filters はエンティティ集合を限定します。fieldValue または互換性のある search で候補値を絞り込み、両方が非空の場合は fieldValue を優先し、エンティティの全文 search は実行しません。すべての fields が空白の場合でも {} を正常に返せます。候補は件数の降順で並び、owner はさらに表示ラベルで並びます。ページネーション API ではありません。
すべてのエンティティタイプは有効なヘルス設定に従って処理され、バックグラウンドの履歴クリーンアップの進行状況には依存しません。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 リクエストパラメーター¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| filters.属性フィールド名 | string | 動的キー。スカラーの候補値配列を推奨します。任意の DQL 式をフィールド名として扱うことはできません。urn/provider/entityType や healthStatus などのトップレベル組み込みフィールド、および snake_case エイリアスはトップレベルに保持され、attributes/sourceMetadata/telemetrySelectors オブジェクト内のキーはフラット化されます。例: ["prod"]取得または入力方法: 現在のエンティティの attributes の実際のフィールド名を使用します。複雑な値のフィルターセマンティクスは、保存済みフィールドタイプとクエリサービスの機能に従います。 |
|
| filters.属性フィールド名[*] | string | 同じフィールドの候補値を1つ指定します。数値/ブール値は元の JSON 型を保持し、null と文字列の null を混同しないでください。例: prod取得または入力方法: 現在のフィールドの候補値/既存エンティティの値から取得します。 |
|
| fields[*] | string | フィールド名はタイトルではなく、DQL でもありません。attributes.entityType とトップレベルの entityType は独立しており、バケットをまたぎません。owner(裸キー)はさらにアイデンティティ/チームラベルを解決し、attributes.owner は通常のバケット化のみを行います。例: env取得または入力方法: 単一の属性/組み込みフィールド名( env、attributes.env、provider、healthStatus など)。 |
|
| entityType | string | 一覧/集計では任意です。トップレベルのヘルスフィールドを使用してフィルター、集計、またはソートする場合は業務上必須です。作成/変更時は必須で、空白除去後も非空である必要があります。エクスポート時は必須です。 null を許可: False 例: database取得または入力方法: エンティティタイプ一覧 の items[].entityType からコードを取得します。タイプ UUID/表示名ではありません。 |
|
| fieldValue | string | filter_options では任意です。非空の場合は search より優先されます。候補のバケットのみを絞り込み、エンティティの全文検索ではありません。空文字列の場合は search にフォールバックし、どちらも空の場合は候補をフィルターしません。null を許可: False 例: prod取得または入力方法: ユーザーが入力する候補値のキーワード。 |
|
| fields | array | Y | 必須で1..64項目。空白はスキップし、完全に同一のキーは重複排除します。裸の env と attributes.env はクエリ時に同じフィールドにマージされますが、返却時はそれぞれのリクエストキーに値を戻します。すべての項目が空白の場合は {} を返し、一致なしエラーにはなりません。ヘルスフィールドには entityType が必要です。null を許可: False 最大長: 64 最小長: 1 例: ["env", "owner"]取得または入力方法: entity_fields の fields[].key または既存エンティティの組み込みフィールドから名前を取得します。 |
| filters | json | 任意のオブジェクト。{} は追加フィルターなしです。裸の属性キー env は attributes.env に変換され、明示的な attributes.entityType はトップレベルの entityType として扱われません。同じフィールドに複数の候補値がある場合は配列に入れます。異なるフィールドはクエリサービスが組み合わせます。ヘルスフィールドには個別の有効な無効化状態があり、使用方法を参照してください。null を許可: False 例: {"env": ["prod"]}取得または入力方法: フィールド名はタイプの DataSchema/属性、またはトポロジーフィールド一覧 から取得し、値はフィールド統計/既存エンティティから取得します。 |
|
| search | string | トポロジークエリでは起点エンティティの URN/name/display_name を検索します。filter_options では候補値キーワードの履歴互換パラメーターであり、fieldValue が非空の場合はそちらを優先します。この2つのシナリオを混同しないでください。null を許可: False 例: demo取得または入力方法: 呼び出し元が検索キーワードを入力します。 |
パラメーター補足説明¶
リクエストパラメーター説明
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| entityType | string | 否 | エンティティタイプコード。ヘルスフィールドのフィルターオプションを要求する場合、またはヘルスフィールドでフィルターする場合は必須です。 |
| fields | array[string] | 是 | フィルターオプションを返す対象フィールドのリスト。最大64項目。 |
| filters | json | 否 | 選択済みのフィルター条件。 |
| search | string | 否 | 候補値検索の互換パラメーター。新しい呼び出し元は fieldValue の使用を推奨します。 |
| fieldValue | string | 否 | 候補値のみをフィルターします。search と同時に指定した場合はこちらを優先します。 |
呼び出し時の注意事項
fieldsは複数フィールドを指定できます。API は各フィールドの選択可能値を個別に返します。- フィールドが
ownerの場合、返却結果はできる限りチームの可読名に解決されます。 filtersは連動フィルターのシナリオで使用できます。fieldsまたはfiltersにヘルスフィールドが含まれる場合はentityTypeが必須です。タイプがdisabledの場合は、有効な無効状態に基づいて候補値を生成します。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/unified_catalog/topology/filter_options' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"entityType":"database","fields":["env","owner"],"filters":{},"fieldValue":""}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.リクエストフィールド名 | array<object> | 有効な各リクエストフィールドに対応する候補配列。候補がない場合は [] で、動的フィールド名はリクエストと同じです。 |
| content.リクエストフィールド名[].label | string | 可読テキスト。裸の owner はチーム/アイデンティティ名に解決される場合があり、それ以外は値の文字列です。 |
| content.リクエストフィールド名[].value | string | フィルター送信に使用する値文字列。owner は UUID または元の名前である可能性があり、現在の実際のエンティティ属性に依存します。 |
| content.リクエストフィールド名[].count | integer | 候補値に対応するエンティティ数。 |
| content.declaration | object | 結果が非空の場合にのみ共通宣言を挿入します。完全に {} の場合は空のオブジェクトのままです。 |
{
"code": 200,
"content": {
"env": [
{
"label": "prod",
"value": "prod",
"count": 12
}
],
"owner": [
{
"label": "DBA",
"value": "group_example",
"count": 3
}
],
"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 が指定されていない、または集計フィールドが無効です |
パラメーター {} が無効です |
一意のタイプコードを入力し、フィールド API/実際の属性キーを使用してください。 |
| 500 | ft.InternalServerError | ダウンストリームクエリの失敗/タイムアウト、成功データの形状異常、またはラベル/チーム/時間のフォーマット失敗 | 内部エラー | クエリ範囲を絞ってから適切に再試行してください。継続的に失敗する場合は traceId とフィルター条件を保持して調査し、今回の書き込みに起因すると判断しないでください。 |