콘텐츠로 이동

수정



POST /api/v1/blacklist/{blist_uuid}/modify

개요

블랙리스트 규칙의 이름, 카테고리, 소스 및 조건을 전체적으로 수정합니다.

호출 전 준비 및 사용 단계

먼저 상세 정보를 조회하여 전체 구성을 백업한 후 name, type 및 전체 소스/조건을 제공합니다. 이 API는 부분 패치가 아닙니다. desc/source/sources/filters를 생략하면 각각 ""/[] 등의 기본값으로 초기화되므로, 이름만 제출하고 범위가 유지되기를 기대할 수 없습니다. 기존 status는 유지되며, 비활성화된 규칙을 수정해도 자동으로 활성화되지 않습니다. 이름/조건 중복 검사에는 비활성화된 규칙도 포함되며, 대상이 존재하지 않는 경우 등은 404를 반환합니다.

리프 연산: =(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 권한을 사용해야 합니다.

경로 파라미터

파라미터 이름 유형 필수 설명
blist_uuid string Y 현재 워크스페이스에서 삭제되지 않은 규칙의 경로 UUID이며, 활성화 및 비활성화 규칙 모두 읽기/수정할 수 있습니다.null 허용: False
예시: blist_example
조회 또는 입력 방법: 블랙리스트 목록 content.data[].uuid에서 가져옵니다.

요청 헤더

파라미터 이름 유형 필수 설명
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 관계이면 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도 인식하지만 대상 데이터 파이프라인 자체가 지원해야 합니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/blacklist/blist_example/modify' \
  -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 생성 주체 UUID입니다.
content.updator string 수정 주체이며 비어 있을 수 있습니다.
content.createAt integer 생성 Unix 초입니다.
content.updateAt integer 최근 수정 Unix 초이며, 수정되지 않은 경우 -1입니다.
content.deleteAt integer 소프트 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다.
content.declaration object 워크스페이스 공통 선언입니다.
{
  "code": 200,
  "content": {
    "id": 10,
    "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": "wsak_example",
    "createAt": 1785427200,
    "updateAt": 1785427300,
    "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 파일 형식 오류 파라미터 표의 JSON 객체를 제출합니다.
400 ft.NameRepeat 동일 워크스페이스의 삭제되지 않은 규칙 이름 중복, 비활성화 규칙도 검사에 포함 이름이 이미 존재함 고유한 이름으로 변경하거나 기존 규칙을 수정합니다.
404 ft.AlreadyExistsSameSourceAndConditions 동일 워크스페이스, 동일 유형에 완전히 동일한 생성 conditions가 이미 존재(비활성화 규칙 포함) 블랙리스트 규칙이 이미 존재하므로 다시 조정하십시오 기존 규칙을 조회하여 수정/활성화하고, 신규 추가를 무한 재시도하지 마십시오. 오류 HTTP는 404입니다.
406 ft.DataSourceMismatch type을 지원되는 데이터 카테고리로 매핑할 수 없음 데이터 소스 불일치 대상 사이트에서 지원하는 데이터 카테고리를 사용하고 철자를 확인합니다.
406 ft.InvalidOperationSymbol 조건 연산자가 지원 집합에 없음 잘못된 연산자 {} 본 페이지의 연산자 표를 사용합니다.
400 ft.SpecialCharactersExist 조건 필드 이름에 백틱 포함 연산자 왼쪽에 특수 문자가 있음 원본 필드 이름을 사용하고 인위적으로 추가된 백틱을 제거합니다.
500 ft.InternalServerError 데이터베이스, 저장 길이/null, 필드 형태 또는 후속 처리 예외 내부 오류 먼저 규칙 및 구성을 조회한 후 재시도를 결정하고, 지속적으로 실패하면 traceId를 보관합니다.
404 ft.InvalidBlacklistuuid 현재 워크스페이스에서 지정한 삭제되지 않은 규칙을 찾을 수 없음 블랙리스트가 존재하지 않음 UUID와 워크스페이스를 다시 확인합니다.
403 ft.Forbidden API Key에 해당 작업 권한이 없거나 워크스페이스 버전이 블랙리스트 기능을 지원하지 않음 작업 권한이 없습니다 해당 권한이 있는 API Key와 기능을 지원하는 워크스페이스를 사용합니다.

문서 평가

이 페이지가 도움이 되었나요?