인덱스 가속 필드 설정 수정¶
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를 보존하고, 쓰기 요청은 먼저 완료된 항목을 읽거나 확인한 후 재시도 여부를 결정합니다. |