콘텐츠로 이동

목록 조회



GET /api/v1/blacklist/list

개요

현재 워크스페이스의 블랙리스트 규칙, 활성화/비활성화 상태 및 전체 매칭 설정을 페이지 단위로 조회합니다.

호출 전 확인 및 사용 단계

type=logging으로 로그를 조회하고, type=all로 전체를 조회하며, 이름으로 검색한 후 페이지별로 읽습니다. 삭제되지 않은 규칙에는 활성화 및 비활성화 규칙이 포함되며, 최근 업데이트(업데이트되지 않은 경우 생성 시각) 기준 내림차순으로 정렬됩니다. 목록은 원본 filters와 실제 conditions를 반환하므로, 규칙 생성/수정 전에 이를 기반으로 전체 설정을 채울 수 있습니다.

이 API는 블랙리스트 규칙 설정 API이며, 과거 데이터 삭제 API가 아닙니다. 저장 응답은 규칙 레코드 처리가 완료되었음만 의미하며, 다운스트림 수집/처리 파이프라인의 적용 진행 상황이나 알림 결과는 제공하지 않습니다. 운영 적용 전에 통제된 샘플로 실제 필터링 범위를 확인하여, 소스/조건이 없는 광범위한 규칙을 피해야 합니다. 무료 플랜 워크스페이스는 본 그룹의 선언에서 제한되므로, 해당 기능을 지원하는 워크스페이스와 적절한 API Key 권한을 사용해야 합니다.

요청 헤더

파라미터 이름 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예시: <DF-API-KEY>
획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다.

Query 요청 파라미터

파라미터 이름 유형 필수 설명
pageIndex integer 선택 사항, 기본값 1, 최솟값 1.
null 허용: False
$minValue: 1
예시: 1
획득 또는 입력 방법: 1부터 시작하여 최상위 pageInfo에 따라 계속합니다.
pageSize integer 선택 사항, 기본값 20, 최솟값 1, 현재 선언된 최댓값 없음; 페이지별로 읽는 것을 권장합니다.
null 허용: False
$minValue: 1
예시: 20
획득 또는 입력 방법: 클라이언트 용량에 맞춰 양의 정수를 선택합니다.
search string 선택 사항, 이름 포함 일치만 수행하며 앞뒤 공백을 제거합니다. 소스나 설명으로는 검색하지 않습니다.
null 허용: False
예시: 헬스 체크
획득 또는 입력 방법: 규칙 이름의 키워드입니다.
type string Y 필수 문자열이며, all은 특수 조회 값으로 새 규칙 유형이 아닙니다. 알 수 없는 카테고리는 일반적으로 성공과 빈 목록을 반환합니다.
null 허용: False
예시: logging
획득 또는 입력 방법: 로그 규칙은 logging, 모든 카테고리 관리는 all을 입력합니다. 대상 데이터 카테고리로 정확히 필터링할 수도 있습니다.

요청 예시

curl --get 'https://openapi.guance.com/api/v1/blacklist/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  --data-urlencode type=logging \
  --data-urlencode pageIndex=1 \
  --data-urlencode pageSize=20

응답

HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content.data array<object> 이 페이지의 삭제되지 않은 규칙이며, 결과가 없으면 []입니다.
content.data[].id integer 또는 null 레코드 번호입니다. 새 항목 생성/가져오기 시에는 영속화 전 스냅샷이므로 null일 수 있으며, uuid로 작업합니다.
content.data[].uuid string blist_규칙 UUID입니다.
content.data[].workspaceUUID string 소속 워크스페이스 UUID입니다.
content.data[].name string 규칙 이름입니다.
content.data[].desc string 규칙 설명입니다.
content.data[].type string 데이터 카테고리입니다.
content.data[].source string 저장된 단일/전체 소스 표현이며 비어 있을 수 있습니다.
content.data[].sources array<string> 저장된 여러 소스 이름이며, 비어 있지 않으면 우선합니다.
content.data[].sources[] string 단일 소스 이름입니다.
content.data[].filters array<object> 또는 object 또는 null 원본 조건 배열이며, 이전 레코드는 {} 또는 null일 수도 있습니다.
content.data[].filters[].name string 리프 필드 이름 또는 이전 그룹 자리 표시자 이름입니다.
content.data[].filters[].condition string 동일 레벨 연결자입니다.
content.data[].filters[].operation string 연산자이며, 이전 항목은 op를 사용하고 생략될 수 있습니다.
content.data[].filters[].op string 이전 연산자 별칭이며 생략될 수 있습니다.
content.data[].filters[].value JSON 저장된 값 또는 값 배열입니다.
content.data[].filters[].value[] JSON 단일 원본 값입니다.
content.data[].filters[].filters array<object> 중첩 조건 그룹이며 생략될 수 있고, 동일한 조건 구조로 재귀합니다.
content.data[].conditions string 필터 실행에 사용하도록 생성된 조건 표현식입니다. 숫자 변환 결과는 이 필드에서 확인하며 직접 다시 쓰지 않습니다.
content.data[].status integer 0 활성화, 2 비활성화, 3 삭제이며, 삭제되지 않은 항목 조회에는 비활성화가 포함됩니다.
content.data[].creator string 생성자 ID UUID입니다.
content.data[].updator string 업데이트한 ID이며 비어 있을 수 있습니다.
content.data[].createAt integer 생성 Unix 초입니다.
content.data[].updateAt integer 최근 업데이트 Unix 초이며, 업데이트되지 않은 경우 -1입니다.
content.data[].deleteAt integer 소프트 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다.
content.data[].creatorInfo object ID 표시 정보이며, 유효한 ID가 없으면 {}입니다.
content.data[].creatorInfo.uuid string ID UUID이며 생략될 수 있습니다.
content.data[].creatorInfo.status integer 계정 상태이며 생략될 수 있습니다.
content.data[].creatorInfo.wsAccountStatus integer 워크스페이스 관계 상태이며 생략될 수 있습니다.
content.data[].creatorInfo.name string 표시 이름입니다.
content.data[].creatorInfo.username string 로그인 이름입니다.
content.data[].creatorInfo.email string 이메일 또는 시스템 ID 식별자입니다.
content.data[].creatorInfo.mobile string 휴대폰 번호이며 비어 있을 수 있습니다.
content.data[].creatorInfo.countryCode string 국가/지역 코드이며 생략될 수 있습니다.
content.data[].creatorInfo.iconUrl string 프로필 이미지이며 생략될 수 있습니다.
content.data[].creatorInfo.acntWsNickname string 워크스페이스 닉네임이며 생략될 수 있습니다.
content.data[].updatorInfo object ID 표시 정보이며, 유효한 ID가 없으면 {}입니다.
content.data[].updatorInfo.uuid string ID UUID이며 생략될 수 있습니다.
content.data[].updatorInfo.status integer 계정 상태이며 생략될 수 있습니다.
content.data[].updatorInfo.wsAccountStatus integer 워크스페이스 관계 상태이며 생략될 수 있습니다.
content.data[].updatorInfo.name string 표시 이름입니다.
content.data[].updatorInfo.username string 로그인 이름입니다.
content.data[].updatorInfo.email string 이메일 또는 시스템 ID 식별자입니다.
content.data[].updatorInfo.mobile string 휴대폰 번호이며 비어 있을 수 있습니다.
content.data[].updatorInfo.countryCode string 국가/지역 코드이며 생략될 수 있습니다.
content.data[].updatorInfo.iconUrl string 프로필 이미지이며 생략될 수 있습니다.
content.data[].updatorInfo.acntWsNickname string 워크스페이스 닉네임이며 생략될 수 있습니다.
content.declaration object 워크스페이스 공통 선언이며 비어 있을 수 있습니다.
pageInfo.pageIndex integer 현재 페이지입니다.
pageInfo.pageSize integer 페이지당 개수입니다.
pageInfo.count integer 이 페이지의 항목 수입니다.
pageInfo.totalCount integer 조건에 맞는 전체 항목 수입니다.
{
  "code": 200,
  "content": {
    "data": [
      {
        "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": "",
        "createAt": 1785427200,
        "updateAt": -1,
        "deleteAt": -1,
        "creatorInfo": {},
        "updatorInfo": {}
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE",
  "pageInfo": {
    "pageIndex": 1,
    "pageSize": 20,
    "count": 1,
    "totalCount": 1
  }
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반함 파라미터 파싱 실패 Query 파라미터 표와 예시를 확인합니다.
500 ft.InternalServerError 규칙 읽기 또는 응답 포맷팅 실패 내부 오류 조회 조건과 UUID를 확인한 후 재시도합니다. 계속 실패하면 traceId를 제공합니다.
403 ft.Forbidden API Key에 해당 작업 권한이 없거나 워크스페이스 버전이 블랙리스트 기능을 지원하지 않음 작업 권한이 없습니다 해당 권한이 있는 API Key와 기능을 지원하는 워크스페이스를 사용합니다.

문서 평가

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