인덱스 키 필드 수정¶
POST /api/v1/workspace/index_key_field/modify
개요¶
선택한 로그 인덱스의 키 필드를 전체적으로 업데이트하고, 전역 스위치에 따라 필드 가속을 동기화합니다.
호출 전 및 사용 단계¶
워크스페이스는 API Key로 식별되며, 로그 인덱스/탐색기 관리 권한이 있는 Key를 사용합니다. 키 필드 설정은 로그 표시와 선택적 가속을 제어하며, 실제 로그 필드 이름, 과거 로그 값 또는 단위 설명은 수정하지 않습니다. 인덱스 UUID와 인덱스 이름은 혼용할 수 없습니다.
먼저 설정을 읽고 백업한 뒤 syncKeywordSpeed를 명확히 정한 후 각 인덱스의 전체 extendFields를 제출합니다. 중복 uuid는 마지막 항목이 적용되며, default가 우선 처리되고, 기타 UUID는 먼저 현재 워크스페이스에서 유효한 레코드를 조회합니다. 기본이 아닌 인덱스의 동시 관계 잠금 예외는 429가 될 수 있으므로, 재시도 전에 설정을 다시 읽습니다. 선택한 인덱스의 키 필드만 덮어쓰고 해당 인덱스의 다른 설정은 유지합니다. 이 인터페이스를 필드 유형/전체 텍스트 인덱스/인덱스 보존 기간 수정 용도로 사용하지 마십시오.
syncKeywordSpeed의 기본값은 true입니다. 꺼짐에서 켜짐으로 변경되면 모든 인덱스의 키 필드를 동기화합니다. 이미 켜져 있으면 이번 배치에서 새로 나타난 필드에 대해서만 가속을 생성합니다. false는 전역 설정을 꺼진 상태로 저장하지만 기존 가속 필드를 직접 삭제하지 않으며, extendFields를 비워도 가속을 직접 삭제하지 않습니다. 기본값 때문에 cfgList가 생략되어도 전역 동기화가 트리거될 수 있으므로, 호출자는 반드시 명시적으로 결정해야 합니다.
설정이 먼저 제출된 후 가속이 디스패치됩니다. 중복 제거된 (index,field) 작업이 200개 미만이면 동기적으로 처리합니다. 더 큰 배치는 200개 단위로 샤딩하여 백그라운드로 전달하며, 전달 실패 시 동기 처리로 대체할 수 있습니다. 일부 다운스트림 가속 실패는 기록되지만 반드시 이 인터페이스가 실패하게 하지는 않습니다. HTTP 200/true는 설정 처리와 디스패치 경로가 완료되었음만 의미하며, 가속이 모두 완료되었음을 보장하지 않습니다. 이 응답에는 작업 ID나 필드별 성공 목록이 없습니다. 쓰기 후 키 필드를 다시 읽어야 하며, 실제 가속은 별도로 확인해야 합니다. 실패 시 설정이 롤백되었다고 가정해서는 안 됩니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| cfgList | array | 선택적 배열입니다. 생략하거나 []로 두면 특정 인덱스 필드를 변경하지 않지만, 전역 syncKeywordSpeed 기본값 true는 여전히 처리됩니다. 빈 배치를 엄격한 무작업으로 간주해서는 안 됩니다. null 허용: False 예: [{"uuid": "default", "extendFields": [{"tag": "host", "alias": "主机"}, {"tag": "service", "alias": "服务"}]}]획득 또는 입력 방법: 먼저 키 필드 조회에서 cfg_uuid를 읽고, 여전히 필요한 필드를 전체적으로 다시 채웁니다. |
|
| cfgList[*] | object | 각 항목은 이 페이지의 구조에 따라 제출해야 합니다. uuid/extendFields가 누락되었거나 하위 항목이 공개 선언에 부합하지 않으면 먼저 406이 반환됩니다. 중복 uuid는 뒤 항목이 앞 항목을 덮어씁니다. 예: {"uuid": "default", "extendFields": [{"tag": "host", "alias": "主机"}, {"tag": "service", "alias": "服务"}]}획득 또는 입력 방법: 각 객체는 하나의 인덱스 설정에 대응합니다. |
|
| cfgList[*].extendFields | array | 조건부 필수 | 해당 인덱스의 전체 키 필드 목록이며 기존 값을 덮어씁니다. []는 비우는 데 사용합니다. 빈 문자열은 과거 선언과의 호환성은 있지만 비즈니스 계층에서 여전히 400이 반환되므로 비우는 용도로 사용하지 않습니다. 목록 순서는 유지되며, 필드를 제거해도 해당 필드의 기존 가속 인덱스가 자동으로 삭제되지는 않습니다. 빈 문자열 허용: True null 허용: False 예: [{"tag": "host", "alias": "主机"}, {"tag": "service", "alias": "服务"}]획득 또는 입력 방법: 조회 결과에서 전체 목록을 복사한 후 필드를 추가하거나 삭제합니다. |
| cfgList[*].extendFields[*] | object | tag와 alias만 허용하며 tag는 비어 있으면 안 됩니다. 공개 선언에서는 일반적으로 객체가 아니거나 추가 하위 키가 있거나 필드 유형이 잘못된 경우를 먼저 406으로 거부합니다. 예: {"tag": "host", "alias": "主机"}획득 또는 입력 방법: 각 항목에 실제 필드 이름과 선택적 표시 별칭을 입력합니다. |
|
| cfgList[*].extendFields[*].alias | string | 선택적 별칭이며 실제 필드를 매칭하는 데 사용되지 않습니다. 빈 문자열 허용: True null 허용: False 예: 主机획득 또는 입력 방법: 표시 요구 사항에 따라 입력하며, 필요 없으면 생략하거나 빈 문자열로 둡니다. |
|
| cfgList[*].extendFields[*].tag | string | 조건부 필수 | 필수 실제 필드 이름입니다. 클라이언트는 별칭이 아닌 비어 있지 않은 문자열을 사용합니다. null 허용: False 예: host획득 또는 입력 방법: 실제 로그 필드 이름을 사용하며, SHOW_LOGGING_FIELD(index=...)로 조회할 수 있습니다. |
| cfgList[*].uuid | string | 조건부 필수 | 인덱스 설정 UUID이며 일반 인덱스 이름으로 대체할 수 없습니다. default가 아닌 경우 먼저 현재 워크스페이스의 유효한 레코드를 조회하고 관계 잠금을 획득합니다. 알 수 없거나 삭제되었거나 다른 워크스페이스의 UUID는 404가 될 수 있으며, 일괄적으로 무시되지는 않습니다. null 허용: False 예: default획득 또는 입력 방법: 키 필드 조회에서 cfg_uuid를 가져오거나, 로그 인덱스 목록에서 uuid를 가져옵니다. 기본 항목은 default로 고정됩니다. |
| syncKeywordSpeed | boolean | 선택적 불리언이며 생략 시 기본값은 true이고, 전역 동기화를 다시 켤 수 있습니다. false는 이번 호출만 건너뛰는 것이 아니라 전역 자동 동기화를 끕니다. 기존 가속 인덱스는 삭제하지 않습니다. null 허용: False 예: false획득 또는 입력 방법: 워크스페이스 관리자가 전역 키워드 자동 가속 정책을 결정합니다. 이 조회 인터페이스는 해당 스위치를 반환하지 않습니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/index_key_field/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"cfgList":[{"uuid":"default","extendFields":[{"tag":"host","alias":"主机"},{"tag":"service","alias":"服务"}]}],"syncKeywordSpeed":false}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 정상 반환 시 true입니다. 인덱스별/가속 필드별 완료 상태가 아닙니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
키 필드 동기화 중 일반 Kodo 가속 실패는 보통 흡수되어 기록되므로, 모든 다운스트림 수량/인덱스 오류를 이 인터페이스가 반드시 그대로 전달하는 오류로 나열하지는 않습니다. 잠금 소유권 등 사전/샤딩 검사는 여전히 요청을 실패시킬 수 있습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 구문 분석 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | 요청 JSON의 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 설정 JSON 객체를 제출하십시오. |
| 400 | ft.InvalidLogIndexCfgKeyFields | 공개 검증을 통과한 후에도 키 필드 구조에 부합하지 않음. 예: extendFields의 빈 문자열이 과거 호환성 검증을 통과한 뒤 비즈니스 배열 검증으로 진입함 | 잘못된 로그 인덱스 키 필드 | 구조에 맞게 입력하고 실제 필드 이름을 유지하십시오. |
| 404 | ft.LogIndexCfgNoExists | 잠금 전에 default가 아닌 인덱스를 찾을 때 현재 워크스페이스의 유효한 설정을 찾지 못함 | 지정한 로그 인덱스 설정이 존재하지 않음 | 인덱스 UUID를 다시 읽고 삭제되었거나 다른 워크스페이스의 레코드를 제외하십시오. |
| 429 | ft.OperationTooFrequently | 인덱스 관계 잠금을 사용할 수 없거나, 획득에 실패했거나, 실행 중 잠금 임대 기간이 만료됨 | 작업이 너무 빈번합니다. 잠시 후 다시 시도하십시오. | 잠시 후 재시도하기 전에 제출된 설정을 다시 읽어 동시 중복 배치를 피하십시오. |
| 500 | ft.InternalServerError | 설정 조회, 저장, 캐시 또는 다운스트림 처리에서 제어되지 않은 예외가 발생함 | 내부 오류 | traceId를 보존하고, 쓰기 요청은 먼저 완료된 항목을 읽어 확인한 후 재시도 여부를 결정하십시오. |