콘텐츠로 이동

바인딩된 인덱스 구성 수정



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와 지원 버전을 사용하세요.

문서 평가

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