바인딩된 인덱스 구성 수정¶
POST /api/v1/external_log_index_cfg/{cfg_uuid}/modify
개요¶
기존 외부 바인딩 인덱스 및 액세스 구성을 수정합니다.
호출 전 및 사용 단계¶
먼저 로그 인덱스 목록에서 외부 바인딩의 cfg_uuid를 선택하고, 상세 정보를 읽어 기존 storeType, 외부 리소스 및 필드 매핑을 확인합니다. 이 API는 대상의 기존 유형에 따라 검증하며 storeType 유형 변경은 허용하지 않습니다. name/exterStoreName/accessCfg는 전체 객체를 제공해야 하며, desc를 생략하면 비워집니다. extend는 전체 교체로 제공되며 전달하지 않으면 유지됩니다. 비밀번호/SK를 생략하거나 빈 값으로 두면 기존 민감한 값을 채우려고 시도하며, 나머지 액세스 키는 자동 병합되지 않으므로 새 URL만 제출하지 마세요. fields를 생략하면 유지되며, [] 또는 모두 빈 매핑이어도 기존 매핑을 비우지 않습니다.
SLS는 project/logstore/region과 AK/SK가 필요하고, TLS는 project/topic 이름, region, iamProjectName/projectId/topicId 및 AK/SK가 필요합니다. ES/OpenSearch/Beaver는 최소 URL이 필요하며 인증은 대상 요구 사항에 따릅니다. ClickHouse 공개 파라미터는 exterStoreProject를 통해 데이터베이스를 제공할 수 있으며 time 필드 매핑을 반드시 구성해야 합니다. 현재 공개 accessCfg에는 database/port/secure가 선언되어 있지 않아 내부 SDK 옵션을 직접 전달할 수 없으며, 현재는 기본 네이티브 연결 기능으로 처리하므로 먼저 배포 측에서 사용 가능한지 확인하세요. Beaver 조건은 extend.conditionStr을 사용합니다.
액세스 키 필드는 HTTPS를 통해 원문으로 제출하며 프런트엔드 RSA 래핑을 사용하지 않습니다. 바인딩/수정은 먼저 데이터베이스에 저장한 후 다운스트림에 새로 고침 및 캐시 삭제를 알리므로, 이후 실패가 발생해도 구성이 이미 저장되었을 수 있습니다. 재시도 여부를 결정하기 전에 목록/상세 및 실제 외부 쿼리를 먼저 확인하세요. 이름을 수정하면 이전 이름 삭제와 새 이름 생성이 각각 통지되므로 호출 측의 인덱스 이름을 확인해야 합니다.
라우트 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| cfg_uuid | string | Y | 경로 구성 UUID이며 인덱스 이름이 아닙니다. 기본 인덱스는 일부 수정 기능만 지원합니다. 사용법을 참조하세요. 예시: lgim_example조회 또는 입력 방법: 로그 인덱스 목록의 content.data[].uuid에서 현재 워크스페이스 구성을 가져옵니다. 기본 인덱스는 default를 사용합니다. |
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>조회 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| extend.conditionStr | string | Beaver 조건 문자열입니다. 바인딩 또는 외부 수정 시 제공하면 conditions로 저장하며, 일반 인덱스의 extend.filters 생성 규칙을 적용하지 않습니다. 예시: status=200조회 또는 입력 방법: Beaver에서만 해당 스토리지의 실제 필터 구문에 따라 제공하며, 먼저 대상 쿼리 도구에서 검증하세요. |
|
| accessCfg | json | Y | 필수 액세스 객체입니다. storeType에 따라 아래 필드를 제공합니다. OpenAPI는 원문을 사용하고 HTTPS로 전송하며 콘솔 RSA 래핑을 사용하지 않습니다. 외부 수정은 전체 객체 교체이며 일부 민감한 값만 채울 수 있으므로 변경된 필드만 전달하지 마세요. null 허용: False 예시: {"url": "https://logs.example.com", "username": "reader", "password": "<EXTERNAL-PASSWORD>"}조회 또는 입력 방법: 외부 리소스 관리자로부터 최소 쿼리 권한 계정/AK를 받으며, 이 API의 DF-API-KEY로 대체하지 않습니다. |
| accessCfg.ak | string | SLS 일반 바인딩에서는 sk와 함께 제공해야 하며, TLS에서는 필수입니다. 외부 수정 시에도 유효한 AK를 제공해야 합니다. null 허용: False 예시: <EXTERNAL-AK>조회 또는 입력 방법: SLS/TLS 리소스 액세스 키 ID이며, 해당 클라우드 리소스 권한 부여에서 가져옵니다. |
|
| accessCfg.cloudAccountId | string | 외부 수정에서만 사용하는 공개 필드입니다. 바인딩 Body에는 이 하위 필드가 선언되어 있지 않으므로 최초 바인딩 시 AK/SK 방식을 사용하고 선언되지 않은 파라미터를 제출하지 마세요. null 허용: False 예시: cloud-account-example조회 또는 입력 방법: SLS 시나리오에서는 권한이 부여된 클라우드 계정 관리에서 대상에 액세스할 수 있는 클라우드 계정 ID를 가져옵니다. |
|
| accessCfg.iamProjectDisplayName | string | TLS IAM 프로젝트 표시 이름이며 생략할 수 있습니다. TLS는 iamProjectName/projectId/topicId가 모두 비어 있지 않아야 하며, topicId가 해당 프로젝트에 속하는지 조회하여 검증합니다. 빈 문자열 허용: True null 허용: False 예시: 默认项目조회 또는 입력 방법: Volcengine TLS 콘솔에서 리소스에 해당하는 값을 가져옵니다. |
|
| accessCfg.iamProjectName | string | TLS IAM 프로젝트 이름이며 project_name이 아닙니다. TLS는 iamProjectName/projectId/topicId가 모두 비어 있지 않아야 하며, topicId가 해당 프로젝트에 속하는지 조회하여 검증합니다. 빈 문자열 허용: True null 허용: False 예시: default조회 또는 입력 방법: Volcengine TLS 콘솔에서 리소스에 해당하는 값을 가져옵니다. |
|
| accessCfg.password | string | 외부 수정 시 생략하거나 빈 문자열로 두면 기존 비밀번호를 채우려고 시도하며, 비밀번호를 지우는 것으로 간주하지 않습니다. 비밀번호가 없는 대상은 바인딩 시 실제 요구 사항에 따라 생략할 수 있습니다. 빈 문자열 허용: True null 허용: False 예시: <EXTERNAL-PASSWORD>조회 또는 입력 방법: 대상 계정 비밀번호이며 HTTPS로 전송되고 예시는 자리 표시자입니다. |
|
| accessCfg.projectId | string | TLS 프로젝트 ID이며 exterStoreProject 이름에 대응합니다. TLS는 iamProjectName/projectId/topicId가 모두 비어 있지 않아야 하며, topicId가 해당 프로젝트에 속하는지 조회하여 검증합니다. 빈 문자열 허용: True null 허용: False 예시: project-example조회 또는 입력 방법: Volcengine TLS 콘솔에서 리소스에 해당하는 값을 가져옵니다. |
|
| accessCfg.sk | string | SLS/TLS 키입니다. 외부 수정 시 생략하거나 빈 문자열로 두면 기존 SK를 유지하려고 시도하며 빈 값으로 삭제할 수 없습니다. 바인딩 시에는 반드시 전체를 제공해야 합니다. null 허용: False 예시: <EXTERNAL-SK>조회 또는 입력 방법: ak와 함께 사용하는 키이며 실제 값을 로그나 문서에 기록하지 마세요. |
|
| accessCfg.topicId | string | TLS 로그 토픽 ID이며 exterStoreName 이름에 대응합니다. TLS는 iamProjectName/projectId/topicId가 모두 비어 있지 않아야 하며, topicId가 해당 프로젝트에 속하는지 조회하여 검증합니다. 빈 문자열 허용: True null 허용: False 예시: topic-example조회 또는 입력 방법: Volcengine TLS 콘솔에서 리소스에 해당하는 값을 가져옵니다. |
|
| accessCfg.url | string | 해당 연결 유형에 따라 조건부 필수이며, 서버에서 액세스 테스트를 수행합니다. 주소가 유효하다고 해서 이후 모든 쿼리 권한이 보장되지는 않습니다. null 허용: False 예시: https://logs.example.com조회 또는 입력 방법: ES/OpenSearch/Beaver의 실제 연결 주소이며, ClickHouse는 관리자가 제공한 연결 주소를 사용합니다. |
|
| accessCfg.username | string | ES 등 대상 인증 요구 사항에 따라 제공해야 합니다. 외부 수정 시 생략해도 기존 사용자 이름이 유지된다고 보장하지 않으므로 전체를 다시 채워야 합니다. 빈 문자열 허용: True null 허용: False 예시: reader조회 또는 입력 방법: 대상 조회 계정이며 현재 워크스페이스 멤버가 아닙니다. |
|
| desc | string | 선택 설명입니다. 바인딩 시 생략하면 빈 값이 되고, 외부 수정 시에도 생략하면 비워지므로 1024자 이내로 사용하는 것이 좋습니다. 빈 문자열 허용: True null 허용: False 예시: 外部应用日志。조회 또는 입력 방법: 외부 데이터 소스를 설명합니다. |
|
| extend | json | 선택 사항입니다. 외부 modify에서 전달하면 전체 교체되고 생략하면 유지됩니다. null은 피하세요. Beaver 조건 처리 시 500이 발생할 수 있습니다. null 허용: True 예시: {}조회 또는 입력 방법: 외부 인덱스의 추가 표시 구성이며, Beaver 필터링에는 conditionStr을 사용할 수 있습니다. |
|
| exterStoreName | string | Y | 필수 외부 대상 이름이며 로컬 name 별칭이나 구성 UUID가 아닙니다. 수정 시 반드시 전체를 제공해야 합니다. null 허용: False 예시: app_logs조회 또는 입력 방법: 외부 콘솔에서 실제 리소스 이름을 가져옵니다: SLS Logstore, TLS topic_name, ES/OpenSearch 인덱스, Beaver 대상 또는 ClickHouse 테이블 이름. |
| exterStoreProject | string | SLS/TLS에서는 조건부 필수이며, ClickHouse에서는 필수 데이터베이스 소스입니다. 일반 외부 수정에서 전달하지 않으면 일부 기존 값이 유지되지만 SLS/TLS 검증은 여전히 전체 프로젝트 구성을 요구합니다. null 허용: False 예시: app_project조회 또는 입력 방법: SLS 프로젝트 이름, TLS project_name, ClickHouse 데이터베이스 이름이며, 다른 유형에서는 일반적으로 생략합니다. |
|
| fields | array | 선택 매핑 배열입니다. field와 비어 있지 않은 originalField는 모두 고유해야 하며, originalField가 빈 항목은 무시됩니다. TLS에서 time/__docid/message가 없으면 동일 이름으로 자동 보완하며, ClickHouse는 time 매핑을 명시해야 합니다. 외부 수정은 비어 있지 않은 유효 매핑이 있을 때만 교체하며, []는 기존 매핑을 비우지 않습니다. null 허용: False 예시: [{"field": "time", "originalField": "timestamp"}, {"field": "message", "originalField": "content"}]조회 또는 입력 방법: 대상의 실제 필드에서 플랫폼 쿼리 필드로 매핑할 필드를 선택합니다. 상세의 isShowFields=true에서 기존 매핑을 확인합니다. |
|
| fields[*] | object | 매핑 객체입니다. 예시: {"field": "message", "originalField": "content"}조회 또는 입력 방법: 하나의 로컬 쿼리 필드가 하나의 외부 실제 필드에 대응합니다. |
|
| fields[*].field | string | 조건부 필수 | 선언 시 필수이며 비어 있지 않고 중복되지 않아야 합니다. null 허용: False 예시: message조회 또는 입력 방법: 일반적인 플랫폼 필드 time/__docid/message 또는 매핑이 필요한 다른 키입니다. |
| fields[*].originalField | string | 조건부 필수 | 선언 시 필수이며 빈 문자열을 전달할 수 있지만 해당 항목은 무시되며 기존 매핑 삭제를 의미하지 않습니다. 빈 문자열 허용: True null 허용: False 예시: content조회 또는 입력 방법: 외부 스토리지의 실제 필드 이름입니다. 예를 들어 content를 message로 매핑합니다. |
| isPublicNetworkAccess | boolean | 선택 사항입니다. SLS 기본값은 false이며, ES/OpenSearch/Beaver/ClickHouse 바인딩은 true로 저장됩니다. null은 피하세요. 연결 도달 가능성을 증명하지는 않습니다. null 허용: True 예시: false조회 또는 입력 방법: SLS는 대상 액세스 네트워크에 따라 선택합니다. 프라이빗 네트워크인 경우 사이트에서 대상에 액세스할 수 있어야 합니다. |
|
| name | string | Y | 필수 로컬 인덱스 이름이며 128자 이내를 권장하고 외부 스토리지 이름과 구분합니다. 외부 수정 시 이 로컬 이름을 변경할 수 있습니다. null 허용: False 예시: external_app_logs조회 또는 입력 방법: 현재 워크스페이스의 바인딩 인덱스에 고유 별칭을 지정합니다. 먼저 로그 인덱스 목록을 확인하세요. |
| region | string | SLS/TLS에서는 조건부 필수이며, ES/OpenSearch/Beaver/ClickHouse 바인딩은 빈 리전으로 정규화됩니다. null 허용: False 예시: cn-hangzhou조회 또는 입력 방법: 대상 클라우드 리소스 콘솔에서 실제 리전 코드를 가져오고 AK 권한이 적용되는 리전과 일치하는지 확인하세요. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/external_log_index_cfg/lgim_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"external_app_logs","desc":"外部应用日志。","exterStoreName":"app_logs","accessCfg":{"url":"https://logs.example.com","username":"reader","password":"<EXTERNAL-PASSWORD>"},"fields":[{"field":"time","originalField":"timestamp"},{"field":"message","originalField":"content"}]}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 성공 시 true입니다. 자격 증명이나 새 구성은 반환하지 않으므로 목록/상세에서 다시 읽어야 합니다. |
{
"code": 200,
"content": true,
"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 파일 형식 오류 | 파라미터 표에 따라 객체를 제출하고 storagePolicy는 JSON 객체를 사용하세요. |
| 429 | ft.OperationTooFrequently | 동일 워크스페이스의 스토리지 쓰기/인덱스 관계 동시 작업 또는 잠금 리스 만료 | 작업이 너무 빈번합니다. 잠시 후 다시 시도하세요 | 진행 중인 작업이 완료될 때까지 기다린 후 백오프 재시도하고, 먼저 현재 상태를 조회하세요. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 다운스트림 연결/일반 5xx 또는 필드 형태 이상 | 내부 오류 | 먼저 구성을 읽고 실제 스토리지의 현재 상태를 확인하세요. 지속적으로 실패하면 traceId를 제공하세요. 오류를 미저장으로 간주하거나 바로 반복 생성해서는 안 됩니다. |
| 406 | ft.InvalidParameterValidation | 해당 스토리지에 필요한 AK/SK/URL 등의 값이 비어 있음 | {}의 값이 유효하지 않습니다. 현재 값: {} |
storeType에 따라 해당 액세스 구성을 전체 제공하세요. |
| 406 | ft.DataStoreCfgAkSkOrAccountIdIsMissing | SLS에 AK/SK가 없고 사용 가능한 클라우드 계정 ID도 없음 | 스토리지 구성 파라미터 오류, ak/sk 누락 또는 클라우드 계정 ID 누락 | 최초 공개 바인딩에서는 전체 AK/SK를 사용하고, 외부 수정에서는 공개 필드에 따라 클라우드 계정 ID를 사용할 수 있습니다. |
| 406 | ft.DataStoreCfgAkSkIsMissing | TLS에 AK/SK가 없음 | 스토리지 구성 파라미터 오류, ak/sk 누락 | 해당 키를 제공하세요. |
| 406 | ft.InvalidTlsIamORProjectORTopic | TLS 프로젝트/리전/토픽 정보가 불완전하거나 토픽 검증이 일치하지 않음 | TLS의 Iam/project/topic이 유효하지 않음 | 이름, ID 및 권한 부여 관계를 확인하세요. |
| 400 | ft.CustomStoreLogstoreInvalid | SLS 대상이 유효한 쿼리 모드를 반환하지 않음 | 유효하지 않은 사용자 정의 클라우드 리소스 | Logstore의 존재, 유형 및 권한 부여를 확인하세요. |
| 400 | ft.TestExternalResourceAccessInvalid | SLS/TLS가 아닌 액세스 연결 테스트 실패 | 테스트에 통과하지 못했습니다. 구성 정보가 올바른지 확인하고 네트워크 연결이 정상인지 보장하세요 | 네트워크, 주소 및 대상 액세스 권한을 확인하세요. |
| 406 | ft.ObjectFieldNameRepeat | field가 중복됨 | 매핑 구성에서 필드 {}가 중복됩니다 |
각 대상 필드에는 하나의 매핑만 구성하세요. |
| 406 | ft.ObjectOriginalFieldNameRepeat | originalField가 중복됨 | 매핑 구성에서 매핑 필드 {}가 중복됩니다 |
각 소스 필드는 한 번만 사용하세요. |
| 400 | ft.ForIndexCfgNameExists | 현재 워크스페이스에 이미 활성 상태의 동일 이름 인덱스가 있음 | 지정한 인덱스 구성 이름이 이미 존재합니다 | 고유 별칭을 선택하세요. |
| 400 | ft.LogIndexCfgNameHasUsed | 바인딩 별칭이 이전에 사용한 내부 인덱스 이름과 충돌함 | 지정한 인덱스 구성 이름이 이미 사용되었습니다 | 별칭을 변경하고 내부 이전 이름을 재사용하지 마세요. |
| 400 | ft.WKSPTypeUnsupportAction | 무료/체험 버전에서는 바인딩을 지원하지 않음 | 현재 워크스페이스 버전에서 지원하지 않습니다 | 버전 지원 여부를 확인한 후 연결하세요. |
| 404 | ft.LogIndexCfgNoExists | 지정한 인덱스 구성이 존재하지 않음/삭제됨/다른 워크스페이스에 속함 | 지정한 로그 인덱스 구성이 존재하지 않습니다 | 목록에서 유효한 외부 바인딩 UUID를 다시 가져오세요. |
| 404 | ft.ObjectNotExists | 민감한 값을 채울 때 관련 액세스 구성이 존재하지 않음 | 지정한 객체가 존재하지 않습니다 | 바인딩 수명 주기와 액세스 구성을 확인하고 무작정 다시 생성하지 마세요. |
| 404 | ft.NotFoundExternalResourceAccessCfg | 이후 액세스 구성 수정 시 대상이 존재하지 않거나 동시 작업으로 사라짐 | 지정한 외부 인덱스 액세스 정보 구성을 찾을 수 없습니다 | 바인딩 수명 주기를 확인하고 관리자가 처리하도록 하며 기본 인덱스로 대체하지 마세요. |
| 403 | ft.Forbidden | 권한이 부족하거나 현재 버전에서 해당 API를 허용하지 않음 | 작업 권한이 없습니다 | 해당 인덱스 권한이 있는 API Key와 지원 버전을 사용하세요. |