인덱스 바인딩¶
POST /api/v1/log_index_cfg/bind
개요¶
외부 로그 스토리지 리소스를 바인딩합니다.
호출 전 및 사용 단계¶
먼저 외부 스토리지에 쿼리 권한, 실제 대상 리소스 및 필드 매핑을 준비한 다음 storeType을 선택하여 이 워크스페이스의 고유 별칭에 바인딩합니다. 여기서는 쿼리 액세스 구성만 생성하며 외부 Logstore/인덱스/테이블을 생성하지 않고, 외부 데이터를 현재 워크스페이스로 복사하지도 않습니다. SLS/TLS는 리소스를 조회하여 검증하며, 다른 유형은 먼저 액세스 테스트를 수행합니다.
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 옵션을 직접 전달할 수 없으며, 기본 native 연결 기능으로 처리됩니다. 배포 측에서 사용 가능한지 먼저 확인하세요. Beaver 조건은 extend.conditionStr을 사용합니다.
액세스 키 필드는 HTTPS를 통해 원문으로 제출하며 프런트엔드 RSA 래핑을 사용하지 않습니다. 바인딩/수정은 먼저 데이터베이스에 저장한 다음 다운스트림에 새로 고침 및 캐시 삭제를 알립니다. 이후 실패가 발생하더라도 구성이 이미 저장되었을 수 있으므로, 먼저 목록/상세 및 실제 외부 쿼리를 확인한 후 재시도 여부를 결정합니다. 이름을 수정하면 이전 이름 삭제와 새 이름 생성이 각각 통지되므로 호출 측 인덱스 이름을 확인해야 합니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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를 받으며, 이 인터페이스의 DF-API-KEY로 대체하지 않습니다. |
| accessCfg.ak | string | SLS 일반 바인딩에서는 sk와 함께 제공해야 하며 TLS에서는 필수입니다. 외부 수정 시에도 유효한 AK를 제공합니다. null 허용: False 예: <EXTERNAL-AK>획득 또는 입력 방법: SLS/TLS 리소스 액세스 키 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 | 외부 수정 시 생략하거나 빈 문자열을 전달하면 기존 비밀번호를 다시 채우려고 시도하며, 비밀번호를 지우는 것으로 간주할 수 없습니다. 비밀번호가 없는 대상은 바인딩 시 실제 요구 사항에 따라 생략할 수 있습니다. 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 등에서 대상 인증 요구 사항에 따라 제공해야 합니다. 외부 수정 시 생략해도 기존 사용자 이름이 유지된다고 보장되지 않으므로 완전하게 다시 채워야 합니다. 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 권한이 적용되는 리전과 일치하는지 확인합니다. |
|
| storeType | string | Y | 바인딩 시 필수입니다. 외부 수정에서는 이 필드를 선언하지 않으며 대상의 기존 storeType을 사용합니다. 이 인터페이스로 스토리지 유형을 변경하지 않습니다. ClickHouse의 공개 연결 파라미터는 제한적이므로 설명을 참조하세요. null 허용: False 예: es획득 또는 입력 방법: sls/es/opensearch/beaver/volctls/clickhouse 중에서 선택합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/log_index_cfg/bind' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"external_app_logs","desc":"外部应用日志。","storeType":"es","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 | 무료/체험 버전은 바인딩을 지원하지 않음 | 현재 워크스페이스 버전이 지원하지 않음 | 버전 지원 여부를 확인한 후 연동하세요. |
| 403 | ft.Forbidden | 권한이 부족하거나 현재 버전에서 해당 인터페이스를 허용하지 않음 | 작업 권한이 없습니다 | 해당 인덱스 권한이 있는 API Key와 지원 버전을 사용합니다. |