생성¶
POST /api/v1/blacklist/add
개요¶
현재 워크스페이스의 블랙리스트 필터 규칙을 생성합니다.
호출 전 및 사용 단계¶
요청은 application/json을 사용하며, 필드는 아래 JSON 예시에 따라 Body에 넣습니다. 현재 생성 Body에는 필드 검증이 완전히 적용되지 않으므로 호출자는 필드 표에 따라 타입, 길이, 범위를 확인해야 합니다. 비어 있지 않은 고유한 name, 지원되는 type, 소스, 조건을 모두 제출할 것을 권장합니다.
생성 시 이름이 생략되면 호출 ID 기준으로 생성을 시도하지만, 해석 가능한 ID가 없으면 빈 값일 수 있으므로 자동 이름 지정에 의존하지 마십시오. 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와 기능을 지원하는 워크스페이스를 사용합니다. |