コンテンツにスキップ

作成



POST /api/v1/data_query_rule/add

概要

データアクセスルールを作成します。

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

まずデータドメイン、ロール、ソース、DQL 条件を確定してから、一意の名前で作成します。新しいルールは status=0 で直ちに有効状態になりますが、書き込みが成功しても、ソースにデータが存在することや最終的なメンバー権限が想定どおりであることを証明するものではありません。

イベント keyevent の作成には add_v2 を使用し、現在のサイトの regionCode を明示することを推奨します。旧 add/modify で regionCode を省略すると、空文字列としてクロスサイト認可チェックに入り、通常はリージョンエラーが返されます。また、v2 の変更は旧ルートに隠蔽されるため、現在公開されている変更操作では、イベントルール/クロスサイトルールのサイトを確実に保持できません。この種の変更はコンソールから処理し、実際に有効になっている内容を確認してください。

この旧エントリーポイントは regionCode を受け付けません。未指定の場合は空文字列として保存され、読み取り/クエリ時に現在のサイトとして解釈されます。明示的なソースサイトを保持する必要があるルールの変更には使用しないでください。

書き込みでは設定を置き換え、データベースへコミットした後、ルールキャッシュをクリアして監査を記録します。クロスサイト検証ではリソース情報の読み取り/更新も行われる場合があります。この手順は単一のアトミックトランザクションではないため、500/タイムアウト後はまず一覧/詳細で保存済みかどうかを確認し、むやみに再作成しないでください。

ルールの保存は、以降に条件を満たすアイデンティティのデータクエリ範囲/結果マスキングに影響しますが、元データの変更、削除、再収集は行わず、ロールの基本クエリ権限を新たに付与することもありません。複数のロールおよびルールはクエリ側のポリシーに従ってマージされるため、単一のルールだけで最終権限を推測することはできません。Owner は免除され、管理者およびワークスペースの「データアクセス範囲制限」設定によって、一致するロールがない場合の処理が変わります。代表的なメンバーで実際にクエリを実行して受け入れ確認を行ってください。保存後はルールキャッシュが無効化されますが、すべての進行中のクエリが即座に切り替わることを保証するものではありません。

リクエストヘッダー

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

Body リクエストパラメータ

パラメータ名 型 必須 説明
indexes[*] string 配列メンバーには空でない文字列を推奨します。元の宣言では各項目を強制しておらず、誤った型は 500 の原因になる可能性があります。
例: default
取得または入力方法: 単一のログインデックス uuid/default、または認可済みの wksp_来源:lgim_索引。
roleUUIDs[*] string 有効なロールを使用してください。アカウント UUID は使用しないでください。
例: role_example
取得または入力方法: 本ワークスペースで利用可能なロール uuid、または単独の *。
extend.カスタムキー any 任意のシリアライズ可能な JSON 値。追加の有効条件ではありません。
例: production
取得または入力方法: 呼び出し元が定義する表示/編集コンテキスト。実際の conditions と一致させてください。
reExprs[*] json name/enable/reExpr のみを使用することを推奨します。配列要素は元の宣言で構造を強制していないため、オブジェクト以外は 500 になる可能性があります。
例: {"name": "token", "enable": true, "reExpr": "tkn_[0-9A-Za-z]+"}
取得または入力方法: 各オブジェクトで 1 つのマスキング正規表現を定義します。
reExprs[*].name string 任意の表示名。マッチング式としては使用されず、省略しても正規表現マッチングに影響しません。
例: token
取得または入力方法: 業務でカスタマイズした正規表現の表示名。
reExprs[*].enable boolean 明示的なブール値を推奨します。省略時は無効として扱われます。無効化された正規表現も構文が有効である必要があります。
例: true
取得または入力方法: 適用が必要な場合は true、保存のみで適用しない場合は false。
reExprs[*].reExpr string 空でない正規表現を推奨します。現在は省略時に空文字列としてチェックされるため、サーバー側で有効な式が補完されることを前提にしないでください。
例: tkn_[0-9A-Za-z]+
取得または入力方法: 実際の機密コンテンツのパターン。JSON 文字列で使用する場合、バックスラッシュは二重に記述する必要があります。
sources[*] string 上位の type に従って解釈される単一のソース。空でない文字列を推奨します。
例: monitor
取得または入力方法: 対応するデータクエリ結果/ソース一覧から実際の識別子を取得します。イベントの source にはイベント ID やモニター UUID を入力しないでください。
conditions string フィルター式のみを入力し、クエリ全体や外側の中括弧は入力しないでください。任意項目で、デフォルトは空文字列です。空文字列の場合、追加のフィルタリングは行いません。4048 文字以下を推奨します。keyevent は特に Python の文字数で 4048 以下であること、および E クエリ構文を解析できることを条件とします。その他の型では保存時に条件のセマンティクスを完全には検証しないため、保存成功は将来のクエリ成功を保証しません。このルールはアクセスを許可するデータ範囲を定義します。
空文字列を許可: True
null を許可: False
例: `env` = 'production'
取得または入力方法: 対象データの実際のタグ/フィールドから DQL フィルター条件を構築します。まず同じソースのクエリで検証してください。
desc string 任意項目。最大 256(上記と同じ計数単位)。省略/空文字列の場合は空にクリアされます。変更時は元の値を保持するわけではありません。
空文字列を許可: True
null を許可: False
最大長: 256
例: 仅允许查看生产环境数据。
取得または入力方法: 業務担当者がルールの目的と適用対象を入力します。
extend json 任意の JSON をそのまま返却可能な任意項目。省略時は {} です。統一された必須サブキーや単位はなく、サーバーがこれから conditions を自動生成することはありません。変更時は全体を置き換えます。認証情報を保存しないでください。
null を許可: False
例: {}
取得または入力方法: クライアントは自身のエディターの必要に応じて表示用設定を保存します。不要な場合は {} です。
indexes array ログルールでは明示的に指定する必要があります。宣言上は任意ですが、ログクエリには有効なインデックス範囲が必要であり、[] を省略しても自動的にすべてには変更されません。["*"] は利用可能なすべてのログインデックスを表します。* は単独で使用することを推奨します。[] はすべてを意味しません。keyevent は [] を強制保存し、その他の非ログ型では通常 [] を使用します。通常のインデックス名で UUID を代替することはできず、認可が自動的に作成されることもありません。保存成功は、リモートのすべてのリソースが依然として有効であることを証明するものではありません。
null を許可: False
例: ["default"]
取得または入力方法: ログインデックス一覧 から uuid を取得します。デフォルトインデックスは default を使用します。クロスワークスペースの場合は、認可済みのソースワークスペース UUID:インデックス UUID を使用します。
logic string 互換性のための表示用フィールドで、通常は and/or です。任意項目です。省略時は空文字列として保存されます。実際に有効なフィルタリングには conditions が直接使用され、logic を変更しても条件は書き換えられません。複数ロール/複数ルールのマージはこのフィールドでは制御されません。
null を許可: False
例: and
取得または入力方法: クライアントのフィルターエディターにおける条件の組み合わせ方法と一致させてください。
maskFields string 任意項目。省略時は空文字列で、このルールのフィールドマスキングは設定されません。変更時に省略するとクリアされます。選択したフィールドで reExprs=[] の場合、null 以外の値はフィールド全体が *** にマスクされます。空でない正規表現一覧を指定した場合は有効な正規表現のみが適用され、すべて無効でもフィールド全体のマスキングにはなりません。保存列に適合させるため 256 文字以下を推奨します。
空文字列を許可: True
null を許可: False
例: message
取得または入力方法: クエリ結果の実際のフィールド名から選択し、複数は半角カンマで区切ります(例: message,user_email)。* で全体を選択する場合は単独で使用し、具体的なフィールドと混在させないでください。
name string Y 宣言上は必須で、空でない一意の名前を推奨します。空文字列でも自動命名分岐に入る可能性があるため、この互換動作に依存しないでください。最大 64 計数単位(ASCII/半角カタカナは 1、その他の文字は 2)。有効および無効の同一タイプのルールの両方が重複名チェックの対象です。
空文字列を許可: False
null を許可: False
最大長: 64
例: production_only
取得または入力方法: 業務担当者が命名します。まずデータアクセスルール一覧 で同じタイプの既存名を確認してください。
reExprs array 任意項目。省略時は [] で、変更時は全体を置き換えます。保存時には enable=false の項目を含め、各正規表現が検証されます。不正な正規表現は ft.ErrorRegularExpression を返します。任意の文字列を表すために単独の * を使用せず、.* を使用してください。選択したフィールドに正規表現がない場合はフィールド全体が *** になります。正規表現は文字列コンテンツの一致部分のみを処理し、一致した内容を *** に置き換えます。保存時の検証と実行エンジンには差異があるため、保存成功後も代表的なクエリで検証する必要があります。
null を許可: False
例: [{"name": "token", "enable": true, "reExpr": "tkn_[0-9A-Za-z]+"}]
取得または入力方法: 機密値の形式に従って Python re で実行可能な正規表現を作成し、まずマスキング済みサンプルで検証してください。maskFields と組み合わせて使用します。
roleUUIDs array Y 必須の配列です。["*"] は各ロールを表しますが、Owner は引き続きデータアクセス制限を受けません。[] はどのロールにも一致せず、すべてを意味するわけではありません。イベント keyevent は空でない文字列配列である必要があり、* は単独でのみ指定できます。その他の型ではスコープ内にロールが存在することを検証しますが、ロールの status=0 は保証しません。基本クエリ権限は別途必要です。
null を許可: False
例: ["role_example"]
取得または入力方法: ロール一覧 から本ワークスペースのロール uuid を取得します。ワークスペースメンバー一覧 でメンバーの実際のロールを確認できます。
sources array 非ログ範囲の配列です。["*"] は利用可能なすべてのソースを表します。[] を省略してもすべてを意味しません。logging は [] を強制保存します。rum/lineage は認可済みのワークスペース UUID:ソース識別子で限定できます。tracing/metric/keyevent は元のソース文字列を使用します。keyevent は空でない文字列配列である必要があり、wksp_:来源 は受け付けず、* を他の値と混在させることもできません。rum は現在の regionCode を明示した場合にのみ、アプリの存在をクエリで確認します。その他のソースは保存に成功しても、実際にデータが存在することを証明するものではありません。
null を許可: False
例: ["*"]
取得または入力方法: 非ログの場合は実際のデータソースに従って入力します。rum は RUM アプリ一覧 の appId、tracing は service、metric はメジャーメント名、lineage は実際のログソース source、keyevent はイベント source(例: monitor)を使用します。
type string Y 新規作成時は logging/rum/tracing/metric/lineage/keyevent が必須です。宣言上は null を許可しますが、無効な型では正常なクエリルールを形成できないため、常に上記の文字列を送信してください。変更時は type を受け付けず、保存済みの型を引き継ぎます。
null を許可: True
選択可能な値: ['lineage', 'keyevent', 'logging', 'rum', 'tracing', 'metric']
例: logging
取得または入力方法: 制限するデータドメインに応じて選択します。

パラメータ補足説明

データ説明.*

1. ロール認可アクセスの説明 1. 指定されたロールは、指定されたクエリ範囲内のデータのみをクエリできます。 2. ユーザーが複数のロールを持つ場合、そのユーザーのロールのうち、このルールのロールに含まれないロールが 1 つでもあると、このデータアクセスルールはそのユーザーには適用されません。つまり、クエリ範囲は制限されません。 3. 1 つのワークスペース内の複数のログデータアクセスルール間のロジックは or 関係です。

2. リクエストパラメータの説明

パラメータ名 type 必須 説明
name string Y 名前
desc String N 説明
type String Y 型(logging, rum, tracing, metric)
indexes array Y type が logging の場合は必須です。本ワークスペース以外(ワークスペース認可が必須)のインデックス認可の場合は、ワークスペース UUID:インデックス UUID を使用します。例: ["wksp_111:lgim_222", "wksp_333:lgim_444"]
sources array Y type が logging 以外の場合は必須です。type が rum の場合はアプリの appId 一覧、type が tracing の場合はサービス名一覧、type が metric の場合はメジャーメント一覧です。
roleUUIDs array Y ロール UUID 一覧
conditions string N 実際に使用するデータ範囲のフィルター条件。例: "device IN ['PC'] and session_has_replay IN ['1']"
extend dict Y 拡張フィールド。conditions の構造内容を格納し、フロントエンド画面の表示に使用します。例: {"device": [ "PC"], "session_has_replay": [1]}
logic string N ロジックフィールド。and/or でフィルター条件を結合します。
maskFields string N マスキング対象フィールド。複数のフィールドはカンマで区切ります。
reExprs array N 正規表現。例: [{"name":"1111","enable":true,"reExpr":"tkn_[\da-z]*"},{"name":"liuyltest","enable":true,"reExpr":"test"}]

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/data_query_rule/add' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"production_only","desc":"仅允许查看生产环境数据。","type":"logging","indexes":["default"],"sources":[],"roleUUIDs":["role_example"],"conditions":"`env` = '"'"'production'"'"'","extend":{},"logic":"and","maskFields":"message","reExprs":[{"name":"token","enable":true,"reExpr":"tkn_[0-9A-Za-z]+"}]}'

レスポンス

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

フィールド 型 説明
content.id integer または null レコード番号。作成時はコミット前のスナップショットを返すため null になる可能性があります。以降の操作には uuid を使用してください。
content.uuid string lqrl_ルールUUID。2 つのモジュールでエンティティと識別子を共有します。
content.workspaceUUID string このルールが属するワークスペース。ソースワークスペースとは異なります。
content.status integer 0=有効、2=無効、3=削除。本モジュールの読み取りでは削除以外のみを対象とします。
content.creator string 作成したアイデンティティ。
content.updator string 最終更新したアイデンティティ。初期状態では空の場合があります。
content.createAt integer 作成日時の Unix 秒。
content.updateAt integer 更新日時の Unix 秒。未更新の場合は -1。
content.deleteAt integer 削除日時の Unix 秒。未削除の場合は -1。
content.name string 保存値: 宣言上は必須で、空でない一意の名前を推奨します。空文字列でも自動命名分岐に入る可能性があるため、この互換動作に依存しないでください。最大 64 計数単位(ASCII/半角カタカナは 1、その他の文字は 2)。有効および無効の同一タイプのルールの両方が重複名チェックの対象です。
content.desc string 保存値: 任意項目。最大 256(上記と同じ計数単位)。省略/空文字列の場合は空にクリアされます。変更時は元の値を保持するわけではありません。
content.indexes array 保存値: ログルールでは明示的に指定する必要があります。宣言上は任意ですが、ログクエリには有効なインデックス範囲が必要であり、[] を省略しても自動的にすべてには変更されません。["*"] は利用可能なすべてのログインデックスを表します。* は単独で使用することを推奨します。[] はすべてを意味しません。keyevent は [] を強制保存し、その他の非ログ型では通常 [] を使用します。通常のインデックス名で UUID を代替することはできず、認可が自動的に作成されることもありません。保存成功は、リモートのすべてのリソースが依然として有効であることを証明するものではありません。
content.indexes[] string 保存値: 配列メンバーには空でない文字列を推奨します。元の宣言では各項目を強制しておらず、誤った型は 500 の原因になる可能性があります。
content.roleUUIDs array 保存値: 必須の配列です。["*"] は各ロールを表しますが、Owner は引き続きデータアクセス制限を受けません。[] はどのロールにも一致せず、すべてを意味するわけではありません。イベント keyevent は空でない文字列配列である必要があり、* は単独でのみ指定できます。その他の型ではスコープ内にロールが存在することを検証しますが、ロールの status=0 は保証しません。基本クエリ権限は別途必要です。
content.roleUUIDs[] string 保存値: 有効なロールを使用してください。アカウント UUID は使用しないでください。
content.conditions string 保存値: フィルター式のみを入力し、クエリ全体や外側の中括弧は入力しないでください。任意項目で、デフォルトは空文字列です。空文字列の場合、追加のフィルタリングは行いません。4048 文字以下を推奨します。keyevent は特に Python の文字数で 4048 以下であること、および E クエリ構文を解析できることを条件とします。その他の型では保存時に条件のセマンティクスを完全には検証しないため、保存成功は将来のクエリ成功を保証しません。このルールはアクセスを許可するデータ範囲を定義します。
content.extend json 保存値: 任意の JSON をそのまま返却可能な任意項目。省略時は {} です。統一された必須サブキーや単位はなく、サーバーがこれから conditions を自動生成することはありません。変更時は全体を置き換えます。認証情報を保存しないでください。
content.extend.カスタムキー any 保存値: 任意のシリアライズ可能な JSON 値。追加の有効条件ではありません。
content.logic string 保存値: 互換性のための表示用フィールドで、通常は and/or です。任意項目です。省略時は空文字列として保存されます。実際に有効なフィルタリングには conditions が直接使用され、logic を変更しても条件は書き換えられません。複数ロール/複数ルールのマージはこのフィールドでは制御されません。
content.maskFields string 保存値: 任意項目。省略時は空文字列で、このルールのフィールドマスキングは設定されません。変更時に省略するとクリアされます。選択したフィールドで reExprs=[] の場合、null 以外の値はフィールド全体が *** にマスクされます。空でない正規表現一覧を指定した場合は有効な正規表現のみが適用され、すべて無効でもフィールド全体のマスキングにはなりません。保存列に適合させるため 256 文字以下を推奨します。
content.reExprs array 保存値: 任意項目。省略時は [] で、変更時は全体を置き換えます。保存時には enable=false の項目を含め、各正規表現が検証されます。不正な正規表現は ft.ErrorRegularExpression を返します。任意の文字列を表すために単独の * を使用せず、.* を使用してください。選択したフィールドに正規表現がない場合はフィールド全体が *** になります。正規表現は文字列コンテンツの一致部分のみを処理し、一致した内容を *** に置き換えます。保存時の検証と実行エンジンには差異があるため、保存成功後も代表的なクエリで検証する必要があります。
content.reExprs[] json 保存値: name/enable/reExpr のみを使用することを推奨します。配列要素は元の宣言で構造を強制していないため、オブジェクト以外は 500 になる可能性があります。
content.reExprs[].name string 保存値: 任意の表示名。マッチング式としては使用されず、省略しても正規表現マッチングに影響しません。
content.reExprs[].enable boolean 保存値: 明示的なブール値を推奨します。省略時は無効として扱われます。無効化された正規表現も構文が有効である必要があります。
content.reExprs[].reExpr string 保存値: 空でない正規表現を推奨します。現在は省略時に空文字列としてチェックされるため、サーバー側で有効な式が補完されることを前提にしないでください。
content.sources array 保存値: 非ログ範囲の配列です。["*"] は利用可能なすべてのソースを表します。[] を省略してもすべてを意味しません。logging は [] を強制保存します。rum/lineage は認可済みのワークスペース UUID:ソース識別子で限定できます。tracing/metric/keyevent は元のソース文字列を使用します。keyevent は空でない文字列配列である必要があり、wksp_:来源 は受け付けず、* を他の値と混在させることもできません。rum は現在の regionCode を明示した場合にのみ、アプリの存在をクエリで確認します。その他のソースは保存に成功しても、実際にデータが存在することを証明するものではありません。
content.sources[] string 保存値: 上位の type に従って解釈される単一のソース。空でない文字列を推奨します。
content.type string 保存値: 新規作成時は logging/rum/tracing/metric/lineage/keyevent が必須です。宣言上は null を許可しますが、無効な型では正常なクエリルールを形成できないため、常に上記の文字列を送信してください。変更時は type を受け付けず、保存済みの型を引き継ぎます。
content.regionCode string 保存値: v2 の宣言では必須のソースサイトコードです。同じルールのログインデックスは同一サイトに属し、この値と一致している必要があります。旧エントリーポイントはこのフィールドを受け付けません。データアクセスルールはクロスサイト/クロスワークスペース認可の代替にはなりません。イベントのクロスサイトには、keyevent または * を含む有効な認可が必要です。後述の重複ルートの実際の到達性に関する説明に注意してください。
content.declaration object 共通宣言。書き込みレスポンスにはソース/ロール/アイデンティティの要約は自動的に追加されません。
{
  "code": 200,
  "content": {
    "id": null,
    "uuid": "lqrl_example",
    "workspaceUUID": "wksp_example",
    "name": "production_only",
    "desc": "仅允许查看生产环境数据。",
    "type": "logging",
    "indexes": [
      "default"
    ],
    "sources": [],
    "roleUUIDs": [
      "role_example"
    ],
    "conditions": "`env` = 'production'",
    "extend": {},
    "logic": "and",
    "maskFields": "message",
    "reExprs": [
      {
        "name": "token",
        "enable": true,
        "reExpr": "tkn_[0-9A-Za-z]+"
      }
    ],
    "regionCode": "",
    "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 を修正してください。
404 ft.NoInitOtherNodeCfg リモートインデックス/RUM アプリのメタデータを読み取りまたは検証する際に、利用可能なソースサイトアドレスが見つからない 他のノード設定が初期化されていません 管理者がソースサイト設定、アクセス可能なアドレス、有効なクロスワークスペース認可を確認し、修正後に再試行してください。
400 ft.NameRepeat 本ワークスペースに同じタイプで削除されていない同名ルールが存在する 名前は既に存在します 名前を変更するか、確認後に既存の UUID を更新してください。
400 ft.ErrorRegularExpression 無効な正規表現がある(無効化された項目を含む) 正規表現に誤りがあります すべての reExpr を修正してから再送信してください。単独の * は使用しないでください。
400 ft.InvalidRoleUUID ロールがワークスペースのスコープ内にない、または keyevent のロール配列が無効 無効なロールUUID: {} 本ワークスペースのロール一覧から有効な識別子を取得してください。イベントの * は単独で使用します。
400 ft.InvalidLoggingIndex 解析された現在のサイトのソースワークスペースに、通常インデックスが存在しない/削除済み 無効なインデックス:{} 有効なインデックス UUID/default を使用し、認可を確認してください。
400 ft.InvalidRegionDataQueryRuleIndex ログインデックスが複数サイトにまたがる、またはサイトが一致しない、イベントのクロスサイトに有効な認可がない {} サイトのインデックス情報が無効です サイトごとにルールを作成し、認可記録からソースとターゲットを確認してください。
500 ft.InternalServerError 配列項目の形状不一致、フィールドが保存長を超過、下流の通常 5xx、データベースまたはコミット後のキャッシュ失敗 内部エラー 本文の構造と長さを確認し、現在の設定を読み取ってデータベースに保存済みかどうかを確認してから再試行を判断し、traceId を提供してください。
400 ft.InvalidSources keyevent のソース構造が無効、または現在のサイトを明示した rum ソースアプリが存在しない 無効なリソース情報:{} イベントには空でない source 文字列配列を指定し、* は単独で使用します。RUM は有効なアプリから appId を取得してください。
406 ft.InvalidParameter keyevent の conditions が文字列でない、または長さが 4048 文字を超過 パラメータ{}が無効です 長さが要件を満たす DQL 条件文字列を使用してください。
406 ft.DqlParseError keyevent 条件を解析できない dql parser 解析失敗: {} イベントクエリでフィルター条件を検証し、元のエラーと traceId を保持してください。

フィードバック

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