목록 조회¶
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와 기능을 지원하는 워크스페이스를 사용합니다. |