インポート¶
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 と、この機能をサポートするワークスペースを使用してください。 |