作成¶
POST /api/v1/data_mask_rule/add
概要¶
現在のワークスペースでロールごとに適用される機密フィールドの正規表現マスキングルールを作成します。
呼び出し前の準備と使用手順¶
この書き込みエンドポイントには dataRightsManage.workspaceConfigManage の管理権限が必要です。
対象ワークスペースの API Key を使用します。この設定グループは、クエリの返却段階で独立した機密ルールを適用するものであり、元の保存データを書き換えず、フィールドも作成しません。また、永久削除/匿名化インターフェースでもありません。
データカテゴリ、実際のフィールド、正規表現、必要なロールを選択して作成します。名前の一意性チェックは行いません。成功すると新しいルールオブジェクトを返します。タイムアウトまたは 500 の後は、まず一覧を確認し、同名ルールを重複作成しないでください。
書き込みはまずコミットされ、その後、該当するデータカテゴリのルールキャッシュが削除されます(変更時は新旧のカテゴリをクリアします)。キャッシュの失敗はコミット後に発生する可能性があります。その後、実際の読み取り主体でテストしてください。ルール一覧への保存成功は、すべてのクエリ経路とキャッシュで有効性が検証済みであることを意味しません。
有効性は、対象のクエリチェーン、データカテゴリ、実際のロール集合にも依存します。ロール設定はデータクエリの認可そのものではありません。同一のアカウント/Key が、そのカテゴリのクエリ権限を持つ複数のロールに属している場合、そのうち 1 つのロールに適用可能な機密ルールがないと、このルールグループ全体が適用されない可能性があります。1 つのロールだけをバインドして、すべての閲覧者に強制マスキングされると仮定しないでください。実際のロール/Key を使用して、データクエリ および対象の表示画面で検証してください。現在の正規表現置換は文字列値のみを処理します。数値、オブジェクト、配列、真偽値、null は自動的に文字列へ変換してマスクされません。標準クエリで一致した文字列部分は***に置換され、その他のテキストは保持されます。保存時の正規表現チェックには regex ライブラリを使用し、クエリ実行パスでは標準 re を使用します。Python 標準 re 互換の構文のみを使用することを推奨します。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| roleUUIDs[*] | string | 1 つのロール UUID。書き込み前に、サーバー側でワークスペースの利用可能なロール集合に含まれるかを確認します。 例: role_example取得または入力方法: ロール一覧の UUID を項目ごとに入力します。ロール名は使用しません。 |
|
| field | string | Y | 必須で空にできません。最大 128 文字です。複数フィールドは半角カンマで区切り、スペースを入れません(例: message,phone)。* を含めると、一致するすべてのフィールドに作用します。範囲を明確にするため、* は単独で使用することを推奨します。 空文字列を許可: False null を許可: False 最大長: 128 例: message取得または入力方法: 対応するデータフィールドのクエリから元のフィールド名を取得します。エイリアスは入力しません。 |
| name | string | Y | 必須で空にできません。最大 128 文字です。現在、同名を許可しており、名前による冪等性保証は提供しません。 空文字列を許可: False null を許可: False 最大長: 128 例: 验证码脱敏取得または入力方法: ルールの用途を入力します。タイムアウト後の重複作成を避けるため、先に一覧で既存設定を確認してください。 |
| reExpr | string | Y | 必須で空にできません。最大 5000 文字です。例では「验证码=123456」を「验证码=***」に変換します。カスタム置換パラメータはサポートしていません。一部の regex 拡張構文は保存できても標準 re では実行に失敗するため、保存成功だけで利用可能と判断しないでください。 空文字列を許可: False null を許可: False 最大長: 5000 例: (?<=验证码=)[0-9]{6}取得または入力方法: 標準 Python re 互換の式を入力し、JSON エスケープを使用します。先にマスキングテストで制御されたサンプルを使用してテストできます。 |
| roleUUIDs | array | Y | 必須の配列です。現在のチェックでは削除済みロールを除外しますが、無効化済みで未削除のロールは通過する可能性があります。[] は明示的に一致するロールがないことを示し、すべてのロールを意味しません。* をこの公開インターフェースの検証免除ワイルドカードロールとして扱わないでください。通常のロールテーブルに該当 UUID が含まれない場合は 404 になります。 null を許可: False 例: ["role_example"]取得または入力方法: ロール一覧から現在のワークスペースで利用可能かつ未削除のロール UUID を取得します。システムロールは一覧上の実際の識別子を使用します。 |
| type | string | Y | 必須です。過去の宣言では null を許可していますが、クライアントは実際にサポートされるカテゴリを選択する必要があり、null をすべてのカテゴリとして扱わないでください。null では信頼できる有効なルールを形成できず、変更時に非 NULL の保存制約に違反する可能性があります。 null を許可: True 選択可能な値: ['lineage', 'logging', 'metric', 'object', 'custom_object', 'keyevent', 'tracing', 'rum', 'security', 'network', 'profiling', 'billing'] 例: logging取得または入力方法: 実際にクエリするデータカテゴリに応じて lineage/logging/metric/object/custom_object/keyevent/tracing/rum/security/network/profiling/billing を選択します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/data_mask_rule/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"验证码脱敏","type":"logging","field":"message","reExpr":"(?<=验证码=)[0-9]{6}","roleUUIDs":["role_example"]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer | レコード番号。アドレス指定には使用しません。 |
| content.uuid | string | wdmk_ ルール UUID。詳細、変更、一括操作に使用します。 |
| content.workspaceUUID | string | 所属ワークスペース。 |
| content.name | string | ルール名。現在のエンドポイントでは同名の一意性をチェックしません。 |
| content.type | string | データカテゴリ。適用される namespace を決定します。 |
| content.field | string | フィールド設定の原文。カンマ区切りです。コンシューマーは各項目の先頭と末尾の空白を自動的に削除しません。 |
| content.reExpr | string | 保存された正規表現。カスタム置換テキストは含みません。 |
| content.roleUUIDs | array<string> | 適用ロール UUID。[] はすべてのロールを意味しません。 |
| content.roleUUIDs[*] | string | 1 つのロール UUID。システムロールの識別子またはカスタム role_ UUID の場合があります。 |
| content.status | integer | 0 は有効、2 は無効、3 は削除済み。一覧/詳細では 3 を除外し、2 は保持します。 |
| content.creator | string | 作成主体。Key UUID の場合があります。 |
| content.updator | string | 更新主体。未更新の場合は空文字列です。 |
| content.createAt | integer | 作成時刻(Unix 秒)。 |
| content.updateAt | integer | 更新時刻(Unix 秒)。未更新の場合は -1 になることがあります。 |
| content.deleteAt | integer | 削除時刻(Unix 秒)。未削除の場合は -1 です。 |
| content.declaration | object | ワークスペースの共通宣言。新規作成時に roles や識別情報は補完しません。 |
{
"code": 200,
"content": {
"id": 10,
"uuid": "wdmk_example",
"workspaceUUID": "wksp_example",
"name": "验证码脱敏",
"type": "logging",
"field": "message",
"reExpr": "(?<=验证码=)[0-9]{6}",
"roleUUIDs": [
"role_example"
],
"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 ファイルの形式エラー | 例に従ってオブジェクトを送信してください。 |
| 404 | ft.NotFoundRole | roleUUIDs のいずれかのメンバーが、現在のワークスペースで利用可能な未削除ロールの集合に含まれていません | 指定されたロールが見つからないか、ロールが削除されています | ロール一覧から UUID を再取得してください。名前、別ワークスペースのロール、* は使用しないでください。 |
| 400 | ft.ErrorRegularExpression | 保存時の正規表現事前チェックに失敗しました | 正規表現に誤りがあります | 有効かつ標準 re 互換の式に変更し、JSON のバックスラッシュエスケープを確認してください。 |
| 500 | ft.InternalServerError | ストレージまたはレスポンスに失敗しました。書き込みコミット後のキャッシュクリア失敗でも 500 になる可能性があります | 内部エラー | 書き込みリクエストはまず一覧/詳細で読み戻してから再試行を判断してください。traceId を保持して管理者に連絡してください。 |