作成¶
POST /api/v1/blacklist/add
概要¶
現在のワークスペースのブラックリストフィルタールールを作成します。
呼び出し前と使用手順¶
リクエストは application/json を使用し、フィールドは以下の JSON 例に従って Body に配置します。現在の新規作成 Body には完全なフィールド検証は適用されません。呼び出し元はフィールド表に従って型、長さ、範囲を確認してください。空でない一意の name、サポートされる type、ソース、条件を完全に送信することを推奨します。
作成時に名前を省略した場合は呼び出し元の識別情報に基づく生成を試みますが、解析可能な識別情報がない場合は空になることがあるため、自動命名に依存しないでください。name は 48 文字以内を推奨します。ソースに明示的な null、保存フィールドが長すぎる場合、JSON のトップレベルがオブジェクトでない場合、その他の不正な形式の場合は 500 になる可能性があります。
リーフ演算:=(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 の権限を使用する必要があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。<DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 を入力します。 |
|
| 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 も認識されますが、対象のデータパイプライン自体がサポートしている必要があります。 |
パラメータの補足説明¶
フィールドは JSON Body で送信し、本ページのリクエスト例を使用してください。新規作成 Body では現在、必須・型・長さの完全な検証は行われないため、呼び出し元はフィールド説明に従って自己確認してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/blacklist/add' \
-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": 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 | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正します。 |
| 406 | ft.ParameterValidationFailed | 空でない filters 内のメンバーに name/condition/value がない、または条件グループの形式が不正 | パラメータ解析に失敗しました | filters を項目ごとに確認します。新規作成 Body では完全な宣言検証は行われません。 |
| 400 | ft.NameRepeat | 同一ワークスペース内の削除されていないルール名が重複している。無効なルールもチェック対象 | 名前は既に存在します | 一意の名前に変更するか、既存ルールを変更します。 |
| 404 | ft.AlreadyExistsSameSourceAndConditions | 同一ワークスペース内の同じ型に、完全に同一の生成 conditions が既に存在する(無効なルールを含む) | ブラックリストルールは既に存在します。再調整してください | 既存ルールを検索して変更/有効化し、新規作成を無限にリトライしないでください。エラーの HTTP は 404 です。 |
| 406 | ft.DataSourceMismatch | type がサポートされるデータカテゴリにマッピングできない | データソースが一致しません | 対象サイトがサポートするデータカテゴリを使用し、スペルを確認します。 |
| 406 | ft.InvalidOperationSymbol | 条件演算子がサポート対象外 | 無効な演算子{} |
本ページの演算子表を使用します。 |
| 400 | ft.SpecialCharactersExist | 条件フィールド名にバッククォートが含まれている | 演算子の左側に特殊文字があります | 元のフィールド名を使用し、人為的に追加したバッククォートを削除します。 |
| 500 | ft.InternalServerError | データベース、保存長/null、フィールド形式、または後続処理の異常 | 内部エラー | まずルールとその設定を照会してからリトライを判断します。継続的に失敗する場合は traceId を保持します。 |
| 403 | ft.Forbidden | API Key にこの操作権限がない、またはワークスペースのプランがブラックリスト機能をサポートしていない | 操作権限がありません | 対応する権限の API Key と、この機能をサポートするワークスペースを使用します。 |