コンテンツにスキップ

インポート



POST /api/v1/blacklist/import

概要

ブラックリスト設定を一括インポートし、既存のソース/条件に基づいて重複排除または更新を行います。

呼び出し前の確認と使用手順

エクスポートした content.blacklists を本インターフェースの Body.blacklists に設定し、blacklistType を明示的に選択します。まず対象のワークスペースで名前、データカテゴリ、ソース、フィールド型を確認してください。export の統一シェルをそのまま本インターフェースの Body として使用することはできません。インポートは status の保持や UUID による直接上書きを受け付けません。

各項目には type、空でない filters、および source/sources のうち少なくとも1つが必要です。フィールド内部の形状エラーは 500 になる可能性があります。名前の重複チェックはログカテゴリのスキップおよび条件の重複排除より先に行われ、同一バッチ内でも名前を重複させることはできません。既存の非削除レコードと (source,conditions) が完全に一致する場合、新しく未使用の name と desc でそのレコードを更新し、元のステータス、型、元の filters などのその他のフィールドは保持します。判定に type は含まれないため、これに依存してカテゴリをまたぐ直接更新を行うべきではありません。同一バッチ内で (source,conditions) が同じ新規項目は先頭の1件のみ保持され、項目ごとのスキップ理由は返されません。複数の項目が同じ既存項目に一致した場合は順次上書きされる可能性があります。

返される新規オブジェクトのスナップショット id は null になる可能性があるため、完了後は一覧/詳細で読み戻してください。例外が最終コミット前に発生した場合は通常、本バッチのデータベース変更がロールバックされますが、エラーを「未保存が確定」とみなさず、再試行前に現在の状態を確認してください。

リーフ演算: =(is)、!=(is_not/is not)、>/>=/<!--<= は value の先頭項目のみを使用します。in、not_in(not in)は集合にマッチします。match/contain、not_match/not_contain は包含マッチを行います。regexp(re)、not_regexp は正規表現で、正規表現の値には元の式を入力します。wildcard/not_wildcard は文字列ワイルドカード値を使用します。exist/exists、not_exist/not_exists はフィールドの存在をチェックします。exist 系でも現在の検証を通過するために空でない value 配列が必要で、["ignored"] を設定できますが、この値は条件には使用されません。ログインデックスの advancedFilter の type=group/rule 構造をそのまま流用しないでください。

数値の値は JSON の数値として直接渡すことを推奨します。新しいロジックでは、同一型のソースでフィールドが数値であることを確認でき、演算が比較/等値/集合の場合にのみ、パース可能な数値文字列を生成される conditions に書き込みます。元の filters は変更されません。フィールド型が不明/競合する場合、クエリが失敗した場合、または metric が推論しない場合は元の文字列を保持し、文字列マッチ/正規表現も変換しません。保存の成功は、不明なフィールドや変換できない数値がマッチすることを保証するものではありません。

これはブラックリストルール設定インターフェースであり、履歴データの削除インターフェースではありません。保存の返却はルールレコードの処理完了のみを証明し、下流の収集/処理チェーンにおける反映進捗や通知結果は提供しません。リリース前に管理されたサンプルで実際のフィルタ範囲を確認し、ソース/条件のない広範囲なルールを避けてください。無料プランのワークスペースは本グループの宣言では制限されているため、この機能をサポートするワークスペースと対応する API Key 権限を使用する必要があります。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証資格情報。例: <DF-API-KEY>
取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
blacklists[*] json 単一のインポートオブジェクト。配列内のフィールドに対して完全な宣言検証は実行されません。null や非オブジェクトを渡さないでください。
例: {"name": "ヘルスチェックログを無視", "desc": "本番nginxのヘルスチェックリクエストをフィルタします。", "type": "logging", "source": "nginx", "sources": [], "filters": [{"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}]}
取得または入力方法: エクスポート済みの設定をテンプレートとして、対象のソースと値を置き換えます。
blacklists[*].name string 空でなく、一意で、48文字以内にすることを推奨します。省略した場合は名前の生成が試行され、同一バッチ内/既存ルールとの名前衝突はいずれもエラーになります。
例: ヘルスチェックログを無視
取得または入力方法: 業務に基づいて命名します。まずブラックリスト一覧で同一ワークスペース内に既に存在しないか確認してください。
blacklists[*].desc string 任意の説明。宣言は256文字です。変更時に省略すると "" にクリアされ、空文字列でもクリアできます。
例: 本番nginxのヘルスチェックリクエストをフィルタします。
取得または入力方法: ルールの用途と想定される影響を記入します。
blacklists[*].type string データカテゴリであり、ルールのステータスではありません。mapping が source の意味を決定します。未サポートの型は DataSourceMismatch を返す可能性があり、宣言の文言は列挙型の検証ではありません。
例: logging
取得または入力方法: 一般的なカテゴリは logging/object/custom_object/keyevent/tracing/rum/network/security/profiling/metric です。現在のマッピングは lineage/object_history/billing/dialtest/llm/agent_monitor も認識しますが、対象のデータチェーン自体がサポートしている必要があります。
blacklists[*].source string source フィールドと sources のうち少なくとも1つが非空である必要があります。sources が非空の場合はそちらが優先されるため、どちらか一方のみを指定することを推奨します。filters のみを提供してソースを欠くことはできません。
例: nginx
取得または入力方法: 対応するカテゴリの実際のデータソースから取得します。logging は source、object/custom_object は class、tracing/profiling は service、rum は app_id、security は category、metric は measurement、object_history も class、その他の列挙カテゴリは source です。
blacklists[*].sources array 複数の正確なソース名の配列。非空の場合は IN で結合され、source より優先されます。[] は source にフォールバックし、省略時は []、変更時に省略するとクリアされます。null や文字列以外の要素を渡さないでください。
例: []
取得または入力方法: 同一カテゴリの実際のソース名を収集します。別カテゴリの service/app_id を混在させないでください。
blacklists[*].sources[*] string 単一のソース名。UUID や正規表現のラッピングは入力しません。すべてのソースは最上位の source を使用します。
例: nginx
取得または入力方法: 実際の単一ソース名を入力します。
blacklists[*].filters array インポート条件は非空である必要があります。ソースが有効でも filters=[] の場合は MissingParameters が返されます。
例: [{"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}]
取得または入力方法: 実際のデータフィールドで構築します。データ詳細やフィールド管理のフィールド名と型を参照できます。
blacklists[*].filters[*] json 単一のリーフ条件。name/condition/operation/value を明示的に提供することを推奨します。配列メンバーには完全な宣言検証が実行されず、形状エラーは 500 になる可能性があります。
例: {"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}
取得または入力方法: 実際のデータフィールド、マッチ演算、実際の値に基づいて構築します。
blacklists[*].filters[*].name string 必須の非空フィールド名。バッククォートを含む場合は拒否されます。保存時にフィールドの存在は保証されないため、データを確認する必要があります。
例: path
取得または入力方法: 対応する型のデータ詳細またはフィールド一覧から実際のフィールド名を取得します。表示エイリアスは使用できません。
blacklists[*].filters[*].condition string and/or のみを推奨します。最初の条件の連結子は無視されます。現在の緩やかな検証ではすべての不正な論理が拒否されるとは限らないため、クライアント側で制約してください。
例: and
取得または入力方法: 同一階層の直前の条件との関係が AND の場合は and、いずれかの関係の場合は or を入力します。
blacklists[*].filters[*].operation string 演算子文字列を明示的に指定することを推奨します。互換フィールド op については補足を参照してください。演算子ごとの value の意味は説明を参照してください。
例: =
取得または入力方法: 本ページの演算子の説明から選択します(例: =、in、match、regexp、exist)。
blacklists[*].filters[*].op string operation の旧エイリアス。両方を提供した場合は operation が優先されます。operation に統一することを推奨します。
例: =
取得または入力方法: 従来の条件構造との互換性が必要な場合に op を使用できます。
blacklists[*].filters[*].value JSON 空でない配列を推奨します。=、!=、比較、regexp/wildcard などは各演算子のルールに従って処理されます。= および比較は先頭の値のみを使用し、in/match は複数をサポートします。null や空配列を使用しないでください。
例: ["/healthz"]
取得または入力方法: 実際のフィールド値を入力します。数値条件は JSON の数値を直接使用し、テキストは文字列を使用することを推奨します。
blacklists[*].filters[*].value[*] string または number 単一の条件値。検証していない単位換算を記述しないでください。"0" は数値型を確認する際に 0 に変換される可能性がありますが、保存される filters には元の入力が保持されます。
例: /healthz
取得または入力方法: 実際のフィールド値を取得します。数値フィールドは数値型を使用し、単位は元のフィールドと一致させます。
blacklists[*].filters[*].filters array 任意のネストグループで、再帰的に同じ構造を使用します。現在の check_filters はグループにも非空の name/condition/value を要求するため、condition と filters のみを持つ一般的なグループは 406 になる可能性があります。通常の呼び出しではリーフ条件をフラット化することを優先し、複雑なグループは検証してから保存してください。
例: [{"name": "env", "condition": "and", "operation": "=", "value": ["production"]}]
取得または入力方法: ネスト条件は検証済みのコンソール設定または既存のエクスポートから取得することを優先します。
blacklistType string Y 必須。logging/all。logging モードでは type が logging でない項目をスキップしますが、名前の重複検証はスキップの前に行われます。all モードではサポートされる各カテゴリの項目を順に処理します。
選択可能な値: ['logging', 'all']
例: logging
取得または入力方法: ログメニュー専用のインポートでは logging、カテゴリをまたぐ管理インポートでは all を指定します。
blacklists array Y 必須の設定オブジェクト配列。JSON 文字列/ファイルではありません。[] は成功時に [] を返します。各項目には非空のソースと filters が必要です。
null を許可: False
例: [{"name": "ヘルスチェックログを無視", "desc": "本番nginxのヘルスチェックリクエストをフィルタします。", "type": "logging", "source": "nginx", "sources": [], "filters": [{"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}]}]
取得または入力方法: エクスポートで返される content.blacklists を使用するか、以下の単一項目構造に従って入力します。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/blacklist/import' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"blacklistType":"logging","blacklists":[{"name":"ヘルスチェックログを無視","desc":"本番nginxのヘルスチェックリクエストをフィルタします。","type":"logging","source":"nginx","sources":[],"filters":[{"name":"path","condition":"and","operation":"=","value":["/healthz"]}]}]}'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。

フィールド 型 説明
content array<object> 今回作成/更新されたルールのスナップショット配列。空の入力または全件スキップの場合は [] で、項目ごとの結果レポートではありません。
content[].id integer または null レコード番号。作成/インポートの新規項目は永続化前のスナップショットのため null になる可能性があり、uuid で操作します。
content[].uuid string blist_ルールUUID。
content[].workspaceUUID string 所属ワークスペースの UUID。
content[].name string ルール名。
content[].desc string ルールの説明。
content[].type string データカテゴリ。
content[].source string 保存された単一/すべてのソース表現。空になる場合があります。
content[].sources array<string> 保存された複数のソース名。非空の場合は優先されます。
content[].sources[] string 単一のソース名。
content[].filters array<object> または object または null 元の条件配列。履歴レコードでは {} や null の場合もあります。
content[].filters[].name string リーフのフィールド名、または履歴グループのプレースホルダー名。
content[].filters[].condition string 同一階層の連結子。
content[].filters[].operation string 演算子。履歴項目では op を使用して省略される場合があります。
content[].filters[].op string 従来の演算子エイリアス。省略可能。
content[].filters[].value JSON 保存された値または値の配列。
content[].filters[].value[] JSON 単一の元の値。
content[].filters[].filters array<object> ネスト条件グループ。省略可能。再帰的に同じ条件構造です。
content[].conditions string フィルタ実行用に生成された条件式。数値変換の結果はこのフィールドで確認でき、直接書き戻されることはありません。
content[].status integer 0 有効、2 無効、3 削除。非削除のクエリには無効も含まれます。
content[].creator string 作成者の ID UUID。
content[].updator string 更新者 ID。空の場合があります。
content[].createAt integer 作成 Unix 秒。
content[].updateAt integer 最終更新 Unix 秒。未更新は -1。
content[].deleteAt integer ソフト削除 Unix 秒。未削除は -1。
content[].declaration object 空でない各オブジェクトにワークスペースの共通宣言が付与されます。
{
  "code": 200,
  "content": [
    {
      "id": null,
      "uuid": "blist_example",
      "workspaceUUID": "wksp_example",
      "name": "ヘルスチェックログを無視",
      "desc": "本番nginxのヘルスチェックリクエストをフィルタします。",
      "type": "logging",
      "source": "nginx",
      "sources": [],
      "filters": [
        {
          "name": "path",
          "condition": "and",
          "operation": "=",
          "value": [
            "/healthz"
          ]
        }
      ],
      "conditions": "{ `source` =  'nginx'  and (`path` =  '/healthz' )}",
      "status": 0,
      "creator": "wsak_example",
      "updator": "",
      "createAt": 1785427200,
      "updateAt": -1,
      "deleteAt": -1,
      "declaration": {}
    }
  ],
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

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

HTTP ステータス errorCode 発生条件 メッセージまたは応答の説明 対応方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 パラメータの解析に失敗 パラメータの位置、フィールド名、型、値を確認してください。
400 ft.RequestJsonFormatError リクエスト JSON の構文が無効 リクエスト JSON の形式エラー content.reason、line、column に従って JSON を修正してください。
400 ft.JsonFormatError JSON の最上位がオブジェクトでない 一部の json ファイルの形式エラー パラメータ表の JSON オブジェクトを送信してください。
400 ft.NameRepeat 既存または同一バッチ内の名前と重複。その項目が後で blacklistType によりスキップされる場合でも発生 名前が既に存在します すべてのインポート名を確認し、リネームして再送信してください。
406 ft.MissingParameters インポート対象項目に type、非空の filters、またはソースが欠落 パラメータの欠落 各項目に type、ソース、非空の filters を完全に指定してください。
406 ft.DataSourceMismatch 処理対象項目の type が条件生成をサポートしていない データソースの不一致 サポートされているデータカテゴリを使用してください。
406 ft.InvalidOperationSymbol 条件演算子が無効 無効な演算子{} 本ページでサポートされている演算子を使用してください。
400 ft.SpecialCharactersExist フィールド名にバッククォートが存在 演算子の左側に特殊文字が存在します 実際のフィールド名を渡し、バッククォートを付けないでください。
500 ft.InternalServerError データベース、ストレージの長さ/null、フィールド形状、または後続処理の異常 内部エラー まずルールとその設定を照会してから再試行を判断してください。継続的に失敗する場合は traceId を保管してください。
403 ft.Forbidden API Key に該当操作の権限がない、またはワークスペースのプランがブラックリスト機能をサポートしていない 操作権限がありません 対応する権限を持つ API Key と、この機能をサポートするワークスペースを使用してください。

フィードバック

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