조회¶
GET /api/v1/blacklist/{blist_uuid}/get
개요¶
현재 워크스페이스에 지정된 블랙리스트 규칙의 전체 저장 구성을 조회합니다.
호출 전 및 사용 단계¶
목록에서 blist_uuid를 선택하면 status=0/2인 규칙을 조회할 수 있습니다. 반환되는 filters는 원본 입력이고, conditions는 생성된 실제 조건이며, 목록의 creatorInfo/updatorInfo는 포함하지 않습니다. 대상이 다른 워크스페이스에 있거나 삭제되었거나 존재하지 않으면 모두 404를 반환합니다.
이 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를 가져옵니다. |
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/blacklist/blist_example/get' \
-H 'DF-API-KEY: <DF-API-KEY>'
응답¶
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": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 404 | ft.InvalidBlacklistuuid | 현재 워크스페이스에서 지정된 삭제되지 않은 규칙을 찾을 수 없음 | 블랙리스트가 존재하지 않음 | 현재 워크스페이스 목록에서 유효한 UUID를 다시 가져오세요. |
| 500 | ft.InternalServerError | 규칙 조회 또는 응답 형식 지정 실패 | 내부 오류 | 조회 조건과 UUID를 확인한 후 다시 시도하세요. 계속 실패하면 traceId를 제공하세요. |
| 403 | ft.Forbidden | API Key에 해당 작업 권한이 없거나 워크스페이스 버전에서 블랙리스트 기능을 지원하지 않음 | 작업 권한이 없습니다 | 해당 권한이 있는 API Key와 이 기능을 지원하는 워크스페이스를 사용하세요. |