콘텐츠로 이동

가져오기



POST /api/v1/blacklist/import

개요

블랙리스트 구성을 일괄 가져오고, 기존 소스/조건을 기준으로 중복 제거 또는 업데이트를 수행합니다.

호출 전 및 사용 단계

내보낸 content.blacklists를 이 API의 Body.blacklists에 넣고 blacklistType을 명시적으로 선택합니다. 먼저 대상 워크스페이스에서 이름, 데이터 카테고리, 소스 및 필드 유형을 확인해야 하며, export의 통합 래퍼를 그대로 이 API의 Body로 사용할 수 없습니다. 가져오기는 status 보존 또는 UUID 지정 덮어쓰기를 지원하지 않습니다.

각 항목에는 type, 비어 있지 않은 filters, 그리고 source/sources 중 최소 하나가 있어야 합니다. 필드 내부 형태가 잘못되면 500이 발생할 수 있습니다. 이름 중복 검사는 로그 카테고리 건너뛰기 및 조건 중복 제거보다 먼저 수행되며, 같은 배치 내에서도 이름이 중복될 수 없습니다. 기존의 삭제되지 않은 레코드와 (source,conditions)가 완전히 같으면 새롭고 아직 사용되지 않은 name과 desc로 해당 레코드를 업데이트하고, 원래 상태, 유형 및 원본 filters 등 나머지 필드는 유지합니다. 판정에는 type이 포함되지 않으므로 이를 의존해 유형 간 지정 업데이트를 수행해서는 안 됩니다. 같은 배치에서 동일한 (source,conditions)를 가진 새 항목은 첫 번째 항목만 유지되며, 항목별 건너뛰기 사유는 반환되지 않습니다. 여러 항목이 동일한 기존 항목과 일치하면 순차적으로 덮어쓸 수 있습니다.

반환되는 새 객체 스냅샷의 id는 null일 수 있으므로 완료 후 목록/상세 조회로 다시 읽어야 합니다. 예외가 최종 커밋 전에 발생하면 일반적으로 이번 배치의 데이터베이스 변경이 롤백되지만, 오류를 '저장되지 않음이 확인됨'으로 간주해서는 안 되며 재시도 전에 현재 상태를 먼저 확인해야 합니다.

리프 연산: =(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 요청 매개변수

매개변수 이름 유형 필수 설명
blacklists[*] json 단일 가져오기 객체입니다. 배열 내 필드에는 전체 선언 검증이 수행되지 않습니다. null 또는 객체가 아닌 값을 전달하지 마십시오.
예: {"name": "忽略健康检查日志", "desc": "过滤生产nginx健康检查请求。", "type": "logging", "source": "nginx", "sources": [], "filters": [{"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}]}
가져오는 방법 또는 입력 방법: 내보낸 구성 하나를 템플릿으로 사용하여 대상 소스와 값을 교체합니다.
blacklists[*].name string 비어 있지 않고 고유하며 48자 이내로 지정하는 것을 권장합니다. 생략하면 이름 생성을 시도하며, 같은 배치/기존 규칙과 이름이 충돌하면 모두 오류가 발생합니다.
예: 忽略健康检查日志
가져오는 방법 또는 입력 방법: 업무에서 이름을 정합니다. 먼저 블랙리스트 목록에서 같은 워크스페이스에 이미 존재하는지 확인합니다.
blacklists[*].desc string 선택적 설명이며 256자로 선언됩니다. 수정 시 생략하면 ""로 초기화되며, 빈 문자열로 초기화할 수 있습니다.
예: 过滤生产nginx健康检查请求。
가져오는 방법 또는 입력 방법: 규칙 용도와 예상 영향을 작성합니다.
blacklists[*].type string 데이터 카테고리이며 규칙 상태가 아닙니다. mapping이 source의 의미를 결정합니다. 지원되지 않는 유형은 DataSourceMismatch를 반환할 수 있으며, 선언 문구가 열거형 검증인 것은 아닙니다.
예: logging
가져오는 방법 또는 입력 방법: 일반적인 카테고리는 logging/object/custom_object/keyevent/tracing/rum/network/security/profiling/metric이며, 현재 매핑은 lineage/object_history/billing/dialtest/llm/agent_monitor도 인식하지만 대상 데이터 파이프라인 자체가 이를 지원해야 합니다.
blacklists[*].source string 소스 필드와 sources 중 최소 하나는 비어 있지 않아야 합니다. sources가 비어 있지 않으면 우선하며, 하나만 선택하는 것을 권장합니다. filters만 제공하고 소스를 생략할 수는 없습니다.
예: nginx
가져오는 방법 또는 입력 방법: 해당 카테고리의 실제 데이터 소스에서 가져옵니다. logging은 source, object/custom_object는 class, tracing/profiling은 service, rum은 app_id, security는 category, metric은 measurement, object_history도 class이며, 그 밖에 나열된 카테고리는 source입니다.
blacklists[*].sources array 여러 정확한 소스 이름 배열입니다. 비어 있지 않으면 IN으로 결합되며 source보다 우선합니다. []이면 source로 폴백하고, 생략하면 []이며, 수정 시 생략하면 초기화됩니다. null 또는 문자열이 아닌 요소를 전달하지 마십시오.
예: []
가져오는 방법 또는 입력 방법: 같은 카테고리의 실제 소스 이름에서 수집합니다. 다른 카테고리의 service/app_id를 섞지 마십시오.
blacklists[*].sources[*] string 단일 소스 이름이며 UUID나 정규식 래핑을 입력하지 않습니다. 모든 소스는 최상위 source를 사용합니다.
예: nginx
가져오는 방법 또는 입력 방법: 실제 소스 이름 하나를 입력합니다.
blacklists[*].filters array 가져오기 조건은 반드시 비어 있지 않아야 합니다. 소스가 유효하더라도 filters=[]이면 MissingParameters가 발생합니다.
예: [{"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}]
가져오는 방법 또는 입력 방법: 실제 데이터 필드로 구성합니다. 데이터 상세 또는 필드 관리의 필드 이름과 유형을 참고할 수 있습니다.
blacklists[*].filters[*] json 단일 리프 조건입니다. name/condition/operation/value를 명시적으로 제공하는 것을 권장하며, 배열 멤버에는 전체 선언 검증이 수행되지 않으므로 형태가 잘못되면 500이 발생할 수 있습니다.
예: {"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}
가져오는 방법 또는 입력 방법: 실제 데이터 필드, 일치 연산 및 실제 값을 기반으로 구성합니다.
blacklists[*].filters[*].name string 필수이며 비어 있지 않은 필드 이름입니다. 백틱()이 포함되면 거부됩니다. 저장 시 필드 존재가 검증된다고 보장하지 않으므로 데이터를 확인해야 합니다.<br>예: path `
가져오는 방법 또는 입력 방법: 해당 유형의 데이터 상세 또는 필드 목록에서 실제 필드 이름을 가져옵니다. 표시 별칭은 사용할 수 없습니다.
blacklists[*].filters[*].condition string and/or만 사용하는 것을 권장합니다. 첫 번째 조건의 연결자는 무시됩니다. 현재의 느슨한 검증이 모든 잘못된 논리를 거부한다고 보장하지 않으므로 클라이언트에서 직접 제한해야 합니다.
예: and
가져오는 방법 또는 입력 방법: 같은 계층의 이전 조건과 AND 관계이면 and, 어느 하나의 관계이면 or를 입력합니다.
blacklists[*].filters[*].operation string 연산자 문자열을 명시적으로 지정하는 것을 권장합니다. 호환 필드 op는 추가 설명을 참고하십시오. 연산자별 value 의미는 설명을 참고하십시오.
예: =
가져오는 방법 또는 입력 방법: 이 페이지의 연산자 설명에서 =, in, match, regexp, exist 등과 같이 선택합니다.
blacklists[*].filters[*].op string operation의 이전 별칭입니다. 둘 다 제공하면 operation이 우선하며, operation으로 통일하는 것을 권장합니다.
예: =
가져오는 방법 또는 입력 방법: 이전 조건 구조와 호환해야 할 때 op를 사용할 수 있습니다.
blacklists[*].filters[*].value JSON 비어 있지 않은 배열을 권장합니다. =, !=, 비교, regexp/wildcard 등은 각 연산자 규칙에 따라 처리됩니다. = 및 비교는 첫 번째 값만 사용하고, in/match는 여러 값을 지원합니다. null 또는 빈 배열을 사용하지 마십시오.
예: ["/healthz"]
가져오는 방법 또는 입력 방법: 실제 필드 값을 입력합니다. 숫자 조건은 JSON 숫자를 직접 사용하고 텍스트는 문자열을 사용하는 것을 권장합니다.
blacklists[*].filters[*].value[*] string 또는 number 단일 조건 값입니다. 검증되지 않은 단위 변환을 작성하지 마십시오. "0"은 숫자 유형 확인 시 0으로 변환될 수 있지만, 저장된 filters에는 원래 입력이 유지됩니다.
예: /healthz
가져오는 방법 또는 입력 방법: 실제 필드 값을 사용합니다. 숫자 필드는 숫자 유형을 사용하고 단위는 원본 필드와 일치시킵니다.
blacklists[*].filters[*].filters array 선택적 중첩 그룹이며 동일한 구조를 재귀적으로 사용합니다. 현재 check_filters는 그룹에도 비어 있지 않은 name/condition/value를 요구하므로, condition+filters만 있는 일반적인 그룹은 406이 발생할 수 있습니다. 일반 호출에서는 리프 조건을 평면적으로 배치하는 것을 우선하고, 복잡한 그룹은 먼저 검증한 후 저장하십시오.
예: [{"name": "env", "condition": "and", "operation": "=", "value": ["production"]}]
가져오는 방법 또는 입력 방법: 중첩 조건은 검증된 콘솔 구성 또는 기존 내보내기에서 가져오는 것을 우선합니다.
blacklistType string Y 필수이며 logging/all입니다. logging 모드에서는 type이 logging이 아닌 항목을 건너뛰지만, 이름 중복 검증은 건너뛰기 전에 수행됩니다. all 모드에서는 지원되는 각 카테고리를 항목별로 처리합니다.
선택 가능한 값: ['logging', 'all']
예: logging
가져오는 방법 또는 입력 방법: 로그 메뉴 전용 가져오기에는 logging, 카테고리 간 관리 가져오기에는 all을 입력합니다.
blacklists array Y 필수 구성 객체 배열이며 JSON 문자열/파일이 아닙니다. []이면 성공 시 []를 반환합니다. 각 항목에는 비어 있지 않은 소스와 filters가 있어야 합니다.
허용 null: False
예: [{"name": "忽略健康检查日志", "desc": "过滤生产nginx健康检查请求。", "type": "logging", "source": "nginx", "sources": [], "filters": [{"name": "path", "condition": "and", "operation": "=", "value": ["/healthz"]}]}]
가져오는 방법 또는 입력 방법: 내보내기에서 반환된 content.blacklists를 사용하거나 아래 단일 항목 구조에 따라 작성할 수 있습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/blacklist/import' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"blacklistType":"logging","blacklists":[{"name":"忽略健康检查日志","desc":"过滤生产nginx健康检查请求。","type":"logging","source":"nginx","sources":[],"filters":[{"name":"path","condition":"and","operation":"=","value":["/healthz"]}]}]}'

응답

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

필드 유형 설명
content array<object> 이번 생성/업데이트된 규칙 스냅샷 배열입니다. 빈 입력이거나 모두 건너뛴 경우 []이며, 항목별 결과 보고가 아닙니다.
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를 사용하고 operation을 생략했을 수 있습니다.
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": 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 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다 매개변수 파싱 실패 매개변수 위치, 필드 이름, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError JSON 최상위가 객체가 아님 일부 json 파일 형식 오류 매개변수 표의 JSON 객체를 제출합니다.
400 ft.NameRepeat 기존 또는 같은 배치의 이름과 중복됨. 해당 항목이 이후 blacklistType으로 인해 건너뛰어지더라도 마찬가지입니다 이름이 이미 존재함 먼저 모든 가져오기 이름을 확인하고 이름을 변경한 후 다시 제출합니다.
406 ft.MissingParameters 가져올 항목에 type, 비어 있지 않은 filters 또는 소스가 누락됨 매개변수 누락 각 항목에 type, 소스 및 비어 있지 않은 filters를 완전히 제공합니다.
406 ft.DataSourceMismatch 처리할 항목의 type이 조건 생성을 지원하지 않음 데이터 소스 불일치 지원되는 데이터 카테고리를 사용합니다.
406 ft.InvalidOperationSymbol 조건 연산자가 유효하지 않음 잘못된 연산자{} 이 페이지에서 지원하는 연산자를 사용합니다.
400 ft.SpecialCharactersExist 필드 이름에 백틱이 있음 연산자 왼쪽에 특수 문자가 있음 실제 필드 이름을 전달하고 백틱을 추가하지 않습니다.
500 ft.InternalServerError 데이터베이스, 저장소 길이/null, 필드 형태 또는 후속 처리 예외 내부 오류 먼저 규칙 및 해당 구성을 조회한 후 재시도 여부를 결정합니다. 지속적으로 실패하면 traceId를 보관합니다.
403 ft.Forbidden API Key에 해당 작업 권한이 없거나 워크스페이스 버전이 블랙리스트 기능을 지원하지 않음 작업 권한이 없습니다 해당 권한이 있는 API Key와 이 기능을 지원하는 워크스페이스를 사용합니다.

문서 평가

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