생성¶
POST /api/v1/data_mask_rule/add
개요¶
현재 워크스페이스에서 역할별로 적용되는 민감 필드 정규식 마스킹 규칙을 생성합니다.
호출 전 및 사용 단계¶
이 쓰기 엔드포인트에는 dataRightsManage.workspaceConfigManage 관리 권한이 필요합니다.
대상 워크스페이스의 API Key를 사용합니다. 이 구성은 쿼리 반환 단계의 독립적인 민감 규칙을 설정하며, 원본 저장 데이터를 다시 쓰지 않고, 필드를 생성하지 않으며, 영구 삭제/익명화 인터페이스도 아닙니다.
데이터 카테고리, 실제 필드, 정규식 및 필요한 역할을 선택한 후 생성하며, 이름은 고유성 검사를 하지 않습니다. 성공 시 새 규칙 객체를 반환합니다. 타임아웃 또는 500 응답 후에는 먼저 목록을 조회하고 동일한 이름의 규칙을 중복 생성하지 마세요.
쓰기는 먼저 커밋한 후 해당 데이터 카테고리의 규칙 캐시를 삭제합니다(수정 시 기존 및 신규 카테고리를 정리). 캐시 실패는 커밋 이후에 발생할 수 있습니다. 이후 실제 읽기 주체로 테스트해야 하며, 규칙 목록 저장 성공이 모든 쿼리 경로와 캐시에서의 적용이 검증되었음을 의미하지는 않습니다.
적용 여부는 대상 쿼리 체인, 데이터 카테고리 및 실제 역할 집합에도 달려 있습니다. 역할 구성은 그 자체로 데이터 쿼리 권한 부여가 아닙니다. 동일한 계정/Key에 해당 카테고리 쿼리 권한이 있는 역할이 여러 개 있고 그중 하나의 역할에 적용 가능한 민감 규칙이 없으면, 이 규칙 그룹 전체가 적용되지 않을 수 있습니다. 하나의 역할만 바인딩하고 모든 조회자가 강제 마스킹된다고 가정하지 마세요. 실제 역할/Key로 데이터 쿼리 및 대상 표시 화면에서 검증하세요. 현재 정규식 치환은 문자열 값만 처리하며, 숫자, 객체, 배열, 불리언 및 null은 자동으로 문자열로 변환되어 마스킹되지 않습니다. 표준 쿼리에서 일치한 문자열 부분은 ***로 대체되고 나머지 텍스트는 유지됩니다. 저장 시 정규식 검사는 regex 라이브러리를 사용하고 쿼리 실행 경로는 표준 re를 사용하므로, Python 표준 re와 호환되는 구문만 사용할 것을 권장합니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| roleUUIDs[*] | string | 역할 UUID 하나이며, 쓰기 전에 서버에서 해당 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 허용: 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 | 역할 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를 보관하고 관리자에게 문의하세요. |