콘텐츠로 이동

인덱스 바인딩



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와 지원 버전을 사용합니다.

문서 평가

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