コンテンツにスキップ

統合カタログエンティティのエクスポート



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。
URN,名称,类型
urn:database:default:demo,demo,database

エラー応答

認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。

下流のエラーは 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 とフィルタ条件を保持して調査し、今回の書き込みに起因すると決めつけないでください。

フィードバック

このページは役に立ちましたか?