콘텐츠로 이동

인덱스 가속 필드 설정 수정



POST /api/v1/workspace/index_speed_field/modify

개요

필드를 순서대로 추가하거나 삭제하여 가속하며, 첫 번째 실패 시 중단되고 완료된 항목은 유지됩니다.

호출 전 및 사용 단계

대상 워크스페이스에서 로그 인덱스 관리 권한이 있는 키를 사용합니다. 필드 가속을 지원하는 스토리지 엔진/데이터 카테고리에서 호출하며, 일반적으로 ScopeDB 로그입니다. 먼저 로그 인덱스 목록에서 인덱스 name을 확인한 다음 실제 필드 이름과 필요한 가속 유형을 가져옵니다. 이 API는 핵심 필드 표시 설정과 다르며 extendFields를 수정하지 않습니다.

namespace=logging, 전체 fieldSpeedConfig 및 enable을 명시적으로 제출합니다. namespace에 유효한 매핑이 없으면 성공 응답 외형 안의 content=false가 되므로, 호출자는 HTTP 200만으로 실행 여부를 판단하지 말고 불리언 값을 확인해야 합니다. namespace가 유효하고 배열이 비어 있는 경우 true이더라도 필드 변경이 있음을 의미하지 않습니다. 모든 indexType을 먼저 검사한 후 필드별로 순서대로 실행하며, 첫 번째 실패 시 즉시 중단되고 이미 성공한 필드는 유지되며 이후 항목은 실행되지 않습니다. 일괄 롤백이나 프로그램 내 자동 재시도는 수행하지 않습니다.

삭제 시 특히 주의할 점: indexType=search는 역색인만 삭제합니다. 생략/null/빈 문자열/materialized는 모두 빈 유형으로 매핑되어 모든 가속 인덱스 유형을 삭제합니다. 범위를 확인한 후 삭제를 요청하십시오. 실패 시 실제 오류에 따라 수정한 후 기존의 멱등 작업을 재시도할 수 있지만, 먼저 이미 성공한 항목과 수량 한도를 확인해야 합니다. 항목별 상태/작업 ID가 없으므로 전체 배치가 실행되지 않았다고 단정할 수 없습니다.

요청 헤더

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

Body 요청 파라미터

파라미터 이름 유형 필수 설명
fieldSpeedConfig array 선택적 배열이며, namespace가 유효할 때 생략/[]이면 필드 작업 없이 true를 반환합니다. 모든 indexType을 먼저 사전 검사한 후 원래 순서대로 항목별 실행하며 중복 제거하지 않습니다.
null 허용: False
예: [{"index": "default", "field": "host", "enable": true, "indexType": "search"}]
가져오기 또는 입력 방법: 인덱스 목록에서 name을 가져오고, 로그 필드 조회에서 실제 field를 가져옵니다.
fieldSpeedConfig[*] object 클라이언트는 전체 객체 구조를 제공해야 하며 null/비객체를 전달하지 마십시오.
예: {"index": "default", "field": "host", "enable": true, "indexType": "search"}
가져오기 또는 입력 방법: 각 항목에 가속 필드 작업 하나를 입력합니다.
fieldSpeedConfig[*].enable boolean 조건부 필수 각 항목은 불리언 값을 명시적으로 제출해야 합니다. 누락/유형 불일치는 공개 파라미터 계층에서 먼저 406을 반환하며 컨트롤러 내부 기본값 false에 의존하지 않습니다.
null 허용: False
예: true
가져오기 또는 입력 방법: 생성 시 true, 삭제 시 false를 입력합니다.
fieldSpeedConfig[*].field string 조건부 필수 가속할 실제 필드 이름이며 별칭이 아닙니다.
null 허용: False
예: host
가져오기 또는 입력 방법: SHOW_LOGGING_FIELD(index=...) 등 조회로 실제 필드 이름을 가져옵니다.
fieldSpeedConfig[*].index string 인덱스 이름이며 UUID가 아닙니다. Studio에서는 여기서 인덱스 설정을 먼저 조회하지 않으며 최종 유효성은 하위 시스템에서 판단합니다.
null 허용: False
예: default
가져오기 또는 입력 방법: 로그 인덱스 목록의 name을 가져오며, 기본값은 default입니다.
fieldSpeedConfig[*].indexType string 빈 문자열/materialized/search만 지원하며 null은 빈 값으로 처리됩니다. 추가 시 빈 값/materialized는 일반 유형을 전달합니다. 삭제 시 빈 값/materialized는 모든 가속 인덱스 유형을 삭제합니다! 역색인만 삭제하려면 search를 명시해야 합니다.
빈 문자열 허용: True
null 허용: True
예: search
가져오기 또는 입력 방법: 역색인 가속만 필요하면 search, 일반/ materialized는 materialized를 입력하거나 생략합니다.
namespace string 선택 사항이지만 누락/알 수 없는 매핑이면 HTTP 200 content=false이며 작업을 실행하지 않습니다. Studio에서는 여기서 사이트 매핑에 따라 변환하며, logging이 아니라는 이유만으로 일괄 거부하지 않습니다. 구체적인 데이터 카테고리/엔진 지원 여부는 하위 시스템에서 확인하며, 현재 일반적으로 ScopeDB 로그입니다.
null 허용: False
예: logging
가져오기 또는 입력 방법: 로그 필드 가속 시 logging을 입력하고 전체 이름을 소문자로 사용하며 L을 입력하지 않습니다.
source string 선택 사항이며 원래 값을 하위 시스템으로 전달합니다. 생략하면 source 필터를 전달하지 않습니다. 인덱스 이름이 아닙니다.
null 허용: False
예: nginx
가져오기 또는 입력 방법: 소스 제한이 필요하면 실제 source를 입력하고, 필요 없으면 생략합니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/workspace/index_speed_field/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"namespace":"logging","fieldSpeedConfig":[{"index":"default","field":"host","enable":true,"indexType":"search"}]}'

응답

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

필드 유형 설명
content boolean namespace가 매핑되지 않으면 false이고, 유효한 매핑에서 순회를 완료하면 true이며 빈 배치도 true입니다. 필드별 보고가 아닙니다.
{
  "code": 200,
  "content": true,
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

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

기타 하위 시스템 인덱스 미존재, 엔진 기능 또는 권한 오류는 실제 HTTP/errorCode/message에 따라 그대로 전달될 수 있습니다. 제어되지 않은 5xx는 공통 오류에서 500으로 래핑되며 고정된 동적 코드를 위조하지 않습니다. 수량이 상한에 도달하면 일반적으로 406이며, 이 API는 해당 생성 오류를 삼키지 않습니다. 이는 핵심 필드 설정의 백그라운드 동기화와 다릅니다.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError 요청 JSON 최상위가 객체가 아님 일부 json 파일 형식 오류 예시에 따라 객체를 제출합니다.
406 ft.InvalidParameter namespace 매핑이 유효하고 어느 하나의 indexType이 빈 값/materialized/search가 아님 파라미터 {}가 유효하지 않음 대상 작업에 맞는 유효한 유형을 선택하십시오. 전체 배치 indexType 사전 검사에서 먼저 거부됩니다.
406 ft.KodoFieldIndexLimitReached 하위 시스템에서 가속 인덱스 생성 시 수량 상한 도달 현재 인덱스의 가속 필드 수가 상한에 도달했습니다. 최대 {}개까지 허용되며, 불필요한 가속 필드를 삭제한 후 다시 시도하십시오. message에 제시된 상한에 따라 더 이상 필요 없는 가속 필드를 삭제한 후 완료되지 않은 항목을 다시 시도합니다.
500 ft.InternalServerError 설정 읽기, 저장, 캐시 또는 하위 시스템 처리 중 제어되지 않은 예외 발생 내부 오류 traceId를 보존하고, 쓰기 요청은 먼저 완료된 항목을 읽거나 확인한 후 재시도 여부를 결정합니다.

문서 평가

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