統合カタログエンティティのエクスポート¶
GET /api/v1/unified_catalog/entity/export
概要¶
単一のエンティティタイプのフィルタ結果を CSV として同期的にエクスポートします。
呼び出し前の確認と使用手順¶
対象タイプの viewDefine.layout を読み取り、列およびローカライズされたヘッダーを決定します。利用可能なレイアウトがない場合は URN/名前/タイプにフォールバックします。オブジェクト/配列の値は JSON テキストとして CSV セルに書き込まれ、null 値は空のセルになり、結果が空でもヘッダーは出力されます。非同期ダウンロードジョブや JSON ラップレスポンスではありません。
現在の実装では最初のページのみをリクエストします。エクスポート設定は pageSize=10000 ですが、アダプタ層が実際には 500 に制限します。そのため、当該クエリの先頭 500 エンティティまでしかエクスポートされず、全量を保証するものではありません。より多くのデータが必要な場合は、エンティティリストをページングしてご自身でエクスポートしてください。CSV の行数から総量を推測しないでください。filters は GET Query で --data-urlencode を使用して完全な JSON テキストを渡します。
すべてのエンティティタイプは有効なヘルス設定に従って処理され、バックグラウンドの履歴クリーンアップ進捗には依存しません。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 を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| filters.属性フィールド名 | array または JSON | 動的キー。スカラー候補値の配列を推奨します。任意の DQL 式をフィールド名として扱うことはできません。urn/provider/entityType や healthStatus および snake_case エイリアスなどのトップレベル組み込みフィールドはトップレベルのまま維持され、attributes/sourceMetadata/telemetrySelectors オブジェクト内のキーはフラット化されます。 例: ["prod"]取得または入力方法: 現在のエンティティの attributes の実際のフィールド名を使用します。複雑な値のフィルタセマンティクスは、保存済みのフィールドタイプとクエリサービスの機能に依存します。 |
|
| filters.属性フィールド名[*] | JSON | 同一フィールドの単一候補値。数値/ブール値は元の JSON タイプを維持し、null と文字列の null を混同しないでください。 例: prod取得または入力方法: 現在のフィールドの候補値/既存エンティティの値から取得します。 |
|
| entityType | string | Y | リスト/統計では任意。トップレベルのヘルスフィールドでフィルタ、統計、ソートを行う場合は業務上必須です。作成/変更時は必須で、空白除去後に空でないこと。エクスポート時は必須です。 null を許可: False 例: database取得または入力方法: エンティティタイプ一覧の items[].entityType からコードを取得します。タイプ UUID/表示名ではありません。 |
| filters | json | 任意のオブジェクト。{} は追加フィルタなし。裸の属性キー env は attributes.env に変換され、明示的な attributes.entityType はトップレベルの entityType として扱われません。同じフィールドの複数の候補値は配列に入れます。異なるフィールドはクエリサービスが組み合わせます。ヘルスフィールドには個別の有効な無効状態があり、使用方法を参照してください。 null を許可: False 例: {"env": ["prod"]}取得または入力方法: フィールド名はタイプ DataSchema/属性またはトポロジーフィールド一覧から取得し、値はフィールド統計/既存エンティティから取得します。 |
|
| order | string | 任意。デフォルトは desc。asc/desc のみを渡すことを推奨します。公開宣言には列挙が付いていないため、任意の文字列を保存したことをもって他の方向がサポートされると見なすべきではありません。 null を許可: False 例: desc取得または入力方法: 呼び出し側が asc または desc を選択します。 |
|
| orderBy | string | 任意。デフォルトのソートはクエリサービスが updatedAt に基づいて処理します。ヘルスソートには entityType が必要です。タイプでヘルスが無効化されている場合、ヘルスソートは履歴のヘルス値ではなく updatedAt desc を使用します。 null を許可: False 例: updatedAt取得または入力方法: タイプビュー/フィールドインターフェースからソート可能なフィールドを選択します。組み込みは updatedAt/name/healthScore など、属性は attributes.env を使用します。 |
|
| provider | string | 任意。渡さない場合はソースでフィルタしません。複数のソースには providers を使用し、その非 null 値が provider より優先されます。エンティティのソースは変更されません。 null を許可: False 例: manual取得または入力方法: 既存エンティティの provider またはフィールド値統計の provider バケットから取得します。具体的な値は収集/報告ソースによって決まります。 |
|
| search | string | 任意。省略/空文字列の場合はあいまい検索を行いません。エンティティ集合に作用し、fieldValue の候補値フィルタとは異なります。 null を許可: False 例: demo取得または入力方法: 呼び出し側がエンティティ名/URN/表示名に含まれる検索語を入力します。 |
パラメータ補足説明¶
リクエストパラメータの説明
| パラメータ名 | type | 必須 | 説明 |
|---|---|---|---|
| entityType | string | 必須 | エンティティタイプのコード。タイプによってエクスポート列が異なります |
| provider | string | 任意 | 単一のソースタイプ |
| search | string | 任意 | あいまい検索。urn / display_name / name にマッチします |
| filters | json | 任意 | attributes フィールドのフィルタ |
| orderBy | string | 任意 | ソートフィールド。デフォルトは updatedAt |
| order | string | 任意 | ソート方向。デフォルトは desc |
呼び出し時の注意事項
- エクスポート列はエンティティタイプビューの定義
viewDefine.layoutに従います。 filtersは JSON オブジェクトまたは文字列化された JSON をサポートします。- インターフェース成功時は CSV ファイルストリームを直接返します。呼び出し側はファイルダウンロードとして処理することを推奨します。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/unified_catalog/entity/export' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode entityType=database \
--data-urlencode 'filters={
"env": [
"prod"
]
}' \
--data-urlencode orderBy=updatedAt \
--data-urlencode order=desc
レスポンス¶
HTTP 200、text/csv;charset=utf-8。Content-Disposition は attachment、ファイル名は entities_YYYYmmddHHMMSS.csv です。列はタイプビューによって決まり、例はレイアウトがない場合のフォールバック列です。
| フィールド | タイプ | 説明 |
|---|---|---|
| CSV.ヘッダー | string | viewDefine.layout および言語に従って生成され、レイアウトがない場合は URN/名前/タイプにフォールバックします。 |
| CSV.行 | string | 各行が 1 エンティティで、最大先頭 500 件。カンマ/引用符などを含む場合は CSV のエスケープに従います。 |
| レスポンスヘッダー | タイプ | 説明 |
|---|---|---|
| Content-Type | string | text/csv;charset=utf-8。 |
| Content-Disposition | string | attachment; filename=entities_YYYYmmddHHMMSS.csv。 |
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
下流のエラーは Kodo の共有マッピングに沿って処理され、4xx は実際の HTTP ステータスおよび ft.KodoCommonApiErr またはマッピング済みのビジネスコードを返す場合があります。すべての失敗が 406 に変換されるわけではありません。透過されない 5xx/接続例外/成功結果の構造不一致は最終的に 500 ft.InternalServerError になります。errorCode/message/traceId を保持し、読み取りまたは書き込み段階に応じて処理してください。HTTP の成功はエンティティの実際の可視性の検証に代わるものではありません。
| HTTP ステータス | errorCode | トリガー条件 | メッセージまたはレスポンスの説明 | 処理方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗 | パラメータの位置、フィールド名、タイプ、値を確認してください。 |
| 406 | ft.InvalidParameter | entityType が空、またはヘルス系クエリパラメータが不完全 | パラメータ {} が無効 |
タイプコードを入力し、フィールドルールに従ってヘルス系クエリの制約を補完してください。 |
| 500 | ft.InternalServerError | 下流クエリの失敗/タイムアウト、成功データの形状異常、またはタグ/チーム/時間のフォーマット失敗 | 内部エラー | クエリ範囲を絞って適切にリトライしてください。継続的に失敗する場合は traceId とフィルタ条件を保持して調査し、今回の書き込みに起因すると決めつけないでください。 |