変更¶
POST /api/v1/blacklist/{blist_uuid}/modify
概要¶
ブラックリストルールの名前、カテゴリ、ソース、条件を一括で変更します。
呼び出し前の確認と使用手順¶
まず詳細を読み取って完全な設定をバックアップし、その後で name、type、および完全なソース/条件を指定してください。この API は部分パッチではありません。desc/source/sources/filters を省略すると、それぞれ ""/[] などのデフォルト値にクリアされるため、名前だけを送信して範囲が保持されることを期待できません。元の status は保持されます。無効化されたルールを変更しても自動的に有効化されることはありません。名前/条件の重複チェックには無効化されたルールも含まれます。対象が存在しない場合などは 404 を返します。
リーフ演算: =(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 であり、履歴データ削除用の API ではありません。保存時のレスポンスはルールレコードの処理が完了したことのみを示し、下流の収集/処理パイプラインにおける反映状況や通知結果は提供しません。本番適用前に制御されたサンプルで実際のフィルタ範囲を確認し、ソース/条件のない広範囲なルールを避けてください。無料プランのワークスペースはこのグループの宣言で制限されているため、この機能をサポートするワークスペースと適切な API Key 権限を使用する必要があります。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| blist_uuid | string | Y | 現在のワークスペースで未削除のルールのパス UUID。有効化済みおよび無効化済みのルールのいずれも読み取り/変更できます。 例: blist_example取得または入力方法: ブラックリスト一覧 の content.data[].uuid から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| sources[*] | string | 単一のソース名。UUID や正規表現のラップは入力しません。すべてのソースを対象にする場合はトップレベルの source を使用します。 例: nginx取得または入力方法: 実際の単一ソース名を入力します。 |
|
| filters[*] | json | 単一のリーフ条件。name/condition/operation/value を明示的に指定することを推奨します。配列メンバーは完全な宣言検証を行わないため、形状が誤っていると 500 になる可能性があります。 例: {"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}取得または入力方法: 実際のデータフィールド、一致演算、実際の値に基づいて構築します。 |
|
| filters[*].name | string | 必須の空でないフィールド名。バッククォートを含む場合は拒否されます。保存時にフィールドの存在は検証されないため、データを確認する必要があります。 例: path取得または入力方法: 対応するタイプのデータ詳細またはフィールド一覧から実際のフィールド名を取得します。表示エイリアスは使用できません。 |
|
| filters[*].condition | string | and/or のみを使用することを推奨します。最初の条件の連結子は無視されます。現在の緩やかな検証では、すべての不正な論理が拒否されることを保証しないため、クライアント側で制約してください。 例: and取得または入力方法: 同じ階層の前の条件との関係が AND の場合は and、OR 関係の場合は or を入力します。 |
|
| filters[*].operation | string | 演算子の文字列を明示的に指定することを推奨します。互換フィールド op については補足を参照してください。演算子ごとの value の意味は説明を参照してください。 例: =取得または入力方法: 本ページの演算子の説明から、=、in、match、regexp、exist などを選択します。 |
|
| filters[*].op | string | operation の旧エイリアス。両方を同時に指定した場合は operation が優先されます。operation に統一することを推奨します。 例: =取得または入力方法: 過去の条件構造との互換性が必要な場合は op を使用できます。 |
|
| filters[*].value | JSON | 空でない配列を推奨します。=、!=、比較、regexp/wildcard などは各演算子のルールに従って処理されます。= および比較は先頭の値のみを使用し、in/match は複数の値をサポートします。null や空の配列は使用しないでください。 例: ["/healthz"]取得または入力方法: 実際のフィールド値を入力します。数値条件は JSON の数値を直接使用し、テキストは文字列を使用することを推奨します。 |
|
| filters[*].value[*] | string または number | 単一の条件値。検証されていない単位変換を記述しないでください。"0" は数値型であることを確認した際に 0 に変換される可能性がありますが、保存される filters には元の入力が保持されます。 例: /healthz取得または入力方法: 実際のフィールド値を取得します。数値フィールドには数値型を使用し、単位は元のフィールドと一致させます。 |
|
| filters[*].filters | array | オプションのネストグループ。再帰的に同じ構造を使用します。現在の check_filters でも、グループに空でない name/condition/value が必要です。condition+filters のみを持つ一般的なグループは 406 になる可能性があります。通常の呼び出しではリーフ条件をフラットに並べることを優先し、複雑なグループは事前に検証してから保存してください。 例: [{"name": "env", "condition": "and", "operation": "=", "value": ["production"]}]取得または入力方法: ネスト条件は、検証済みのコンソール設定または既存のエクスポートから取得することを優先します。 |
|
| desc | string | オプションの説明。256 文字と宣言されています。変更時に省略すると "" にクリアされ、空文字列でもクリアできます。 空文字列の許可: True null の許可: False 最大長: 256 例: 过滤生产nginx健康检查请求。取得または入力方法: ルールの用途と想定される影響を入力します。 |
|
| filters | array | 条件の配列。ソース条件と AND で組み合わされます。作成/変更時は省略できますが、空のソースと空の条件では {} が生成され、有効な制限がないため、範囲のないフィルタは避けてください。変更時に省略すると元の条件はクリアされます。インポート時は各項目に空でない条件を指定する必要があります。 null の許可: True 例: [{"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}]取得または入力方法: 実際のデータフィールドで構築します。データ詳細またはフィールド管理のフィールド名と型を参照できます。 |
|
| name | string | Y | 名前。明示的に空でなく、48 文字以下にすることを推奨します。元の宣言は 50 ですが、保存列は 48 です。同じワークスペース内の未削除ルールでは重複名は許可されず、無効化されたルールも名前を占有します。 空文字列の許可: False null の許可: False 最大長: 50 例: 忽略健康检查日志取得または入力方法: 業務に基づいて命名します。まずブラックリスト一覧で同じワークスペース内に既に存在しないか確認します。 |
| source | string | 単一のソース。すべてのソースには re(.*) を使用し、複数のソースには sources を使用します。空でない sources は source より優先されます。いずれか一方のみを選択することを推奨します。省略すると "" になり、変更時に省略するとクリアされます。一部の宣言では null が許可されていますが、実際の保存値は空でないため、null を渡さないことを推奨します。空文字列の許可: False null の許可: True $maxCharacterLength: 128 例: nginx取得または入力方法: 対応するカテゴリの実際のデータソースから取得します。logging は source、object/custom_object は class、tracing/profiling は service、rum は app_id、security は category、metric は measurement、object_history も class で、その他の列挙カテゴリは source です。 |
|
| sources | array | 複数の正確なソース名の配列。空でない場合は IN で組み合わされ、source より優先されます。[] の場合は source にフォールバックし、省略すると [] になり、変更時に省略するとクリアされます。null や文字列以外の要素を渡さないでください。 null の許可: True 例: []取得または入力方法: 同じカテゴリの実際のソース名から収集します。別カテゴリの service/app_id を混在させないでください。 |
|
| type | string | Y | データカテゴリであり、ルールの状態ではありません。mapping が source の意味を決定します。未サポートのタイプは DataSourceMismatch を返す可能性があり、宣言された文字列は列挙検証ではありません。 null の許可: False 例: logging取得または入力方法: 一般的なカテゴリは logging/object/custom_object/keyevent/tracing/rum/network/security/profiling/metric です。現在のマッピングでは lineage/object_history/billing/dialtest/llm/agent_monitor も認識されますが、対象のデータパイプライン自体が対応している必要があります。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/blacklist/blist_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"忽略健康检查日志","desc":"过滤生产nginx健康检查请求。","type":"logging","source":"nginx","sources":[],"filters":[{"name":"path","condition":"and","operation":"=","value":["/healthz"]}]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| 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": 10,
"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": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427300,
"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 | 同じワークスペース内の未削除ルールで名前が重複している。無効化されたルールもチェック対象 | 名前は既に存在します | 一意の名前を使用するか、既存のルールを変更してください。 |
| 404 | ft.AlreadyExistsSameSourceAndConditions | 同じワークスペース、同じタイプで完全に同じ生成 conditions が既に存在する(無効化されたルールを含む) | ブラックリストルールは既に存在します。再調整してください | 既存のルールを確認して変更/有効化してください。新規作成を無限に再試行しないでください。エラー HTTP ステータスは 404 です。 |
| 406 | ft.DataSourceMismatch | type をサポートされるデータカテゴリにマッピングできない | データソースが一致しません | 対象サイトでサポートされるデータカテゴリを使用し、綴りを確認してください。 |
| 406 | ft.InvalidOperationSymbol | 条件演算子がサポート対象の集合にない | 無効な演算子{} |
本ページの演算子表を使用してください。 |
| 400 | ft.SpecialCharactersExist | 条件フィールド名にバッククォートが含まれている | 演算子の左側に特殊文字が存在します | 元のフィールド名を使用し、人為的に追加されたバッククォートを削除してください。 |
| 500 | ft.InternalServerError | データベース、保存時の長さ/null、フィールド形状、または後続処理の異常 | 内部エラー | まずルールとその設定を照会してから再試行を判断してください。失敗が続く場合は traceId を保持してください。 |
| 404 | ft.InvalidBlacklistuuid | 現在のワークスペースで指定された未削除のルールが見つからない | ブラックリストが存在しません | UUID とワークスペースを再確認してください。 |
| 403 | ft.Forbidden | API Key にこの操作の権限がない、またはワークスペースのバージョンがブラックリスト機能をサポートしていない | 操作権限がありません | 対応する権限の API Key と、この機能をサポートするワークスペースを使用してください。 |