이 가이드는 API 명세를 기반으로 AI가 자동 생성했습니다.
VPC 환경에서 이용 가능합니다.
Ncloud 표준 표현을 적용한 API입니다.
Cloud DB Serverless는 이용 패턴에 따라 스펙과 용량을 자동으로 최적화하는 데이터베이스를 운영할 수 있도록 지원하는 네이버 클라우드 플랫폼의 서비스입니다.
Cloud DB Serverless 서비스에서는 클러스터와 백업, DB 사용자, Database, 파라미터, 로그, 이벤트 관리 기능에 대한 API를 RESTful 형태로 제공합니다.
Cloud DB Serverless 요청 형식
Cloud DB Serverless API에서 공통으로 사용하는 요청 형식을 설명합니다.
API URL
요청 API URL은 다음과 같습니다.
https://clouddb-serverless.apigw.ntruss.com/mysql/v1
요청 헤더
요청 헤더에 대한 설명은 다음과 같습니다.
| 필드 | 필수 여부 | 설명 |
|---|---|---|
x-ncp-apigw-timestamp |
Required | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초)
|
x-ncp-iam-access-key |
Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key
|
x-ncp-apigw-signature-v2 |
Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명
|
x-ncp-lang |
Optional | 응답 메시지 언어 (BCP 47 언어 태그). 생략 시 기본 영문(en). 오류 응답의 error.message가 이 헤더에 따라 다국어로 반환 |
Cloud DB Serverless 응답 형식
Cloud DB Serverless API에서 공통으로 사용하는 응답 형식을 설명합니다.
응답 바디
API 오류 시 공통으로 반환하는 응답 바디는 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
error |
Object<Error> | - | 오류 정보 |
Error
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
errorCode |
String | - | 에러 코드 |
message |
String | - | 에러 메시지 (기본 영어, 다국어 지원 가능) |
detail |
String | - | 에러 상세 정보 (기본 영어, 다국어 지원 가능) |
fieldErrors |
List<FieldError> | - | 입력값 에러가 발생한 경우 각 필드별 에러 상세 정보 목록 |
FieldError
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
message |
String | - | 필드 에러 메시지 (기본 영어, 다국어 지원 가능) |
field |
String | - | 입력값 검증 실패 시 해당 필드 이름 |
동기 방식 배치 API는 오류를 error와 failures 두 가지 중 하나의 형태로 응답합니다. 요청 항목과 무관한 오류(인증·권한, 요청 형식, 서버 내부 오류 등)는 error로, 요청 항목의 처리에서 발생한 실패는 failures로 반환합니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
failures |
Map<Error> | - | index → 실패 사유 |
failures.{index} |
Object<Error> | - |
응답 상태 코드
응답 상태 코드에 대한 설명은 다음과 같습니다.
| HTTP 상태 코드 | 코드 | 메시지 | 설명 |
|---|---|---|---|
| 200 | - | - | 각 API 문서의 응답 상태 코드를 참조 |
| 202 | - | - | 요청 접수 (Long-Running Operation) |
| 400 | BadRequest | The request is malformed or contains an error such as an invalid parameter value or a missing required parameter. | 요청 본문 또는 파라미터의 형식이 올바르지 않은 경우 |
| 400 | InvalidParameter | The specified parameter is invalid. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | InvalidState | Indicates that the specified state is not a valid state for an event source. | 각 API 문서의 응답 상태 코드를 참조 |
| 400 | partialFailure | 각 API 문서의 응답 상태 코드를 참조 | |
| 401 | Unauthorized | Invalid authentication credentials. | 인증 헤더가 없거나 서명이 유효하지 않은 경우 |
| 403 | AccessDenied | The client is permanently forbidden from making the request. | 요청한 리소스에 대한 접근 권한이 없는 경우 |
| 403 | Forbidden | You do not have sufficient permissions to perform this action. | 해당 작업을 수행할 권한이 없는 경우 |
| 404 | NotFound | One or more of the resources in the request does not exist in the system. | 지정한 리소스가 존재하지 않는 경우 (권한 있는 사용자 기준) |
| 409 | Conflict | The request could not be processed because of a conflict in the current status of the resource. | 각 API 문서의 응답 상태 코드를 참조 |
| 409 | ResourceInUse | The specified resource is in use. | 각 API 문서의 응답 상태 코드를 참조 |
| 415 | UnsupportedMediaType | The content type of the request body is not supported. | 요청 Content-Type이 지원 대상이 아닌 경우. accept-patch 응답 헤더로 지원 미디어 타입을 안내 |
| 429 | TooManyRequests | The operation failed because it was called too frequently and exceeded a throttle limit. | 요청 한도를 초과한 경우 |
| 429 | ThrottlingExceeded | The request was denied due to request throttling. | 단위 시간당 허용 호출 수를 초과한 경우 |
| 500 | InternalServerError | The request processing has failed because of an unknown error, exception, or failure. | 서버 내부 오류가 발생한 경우 |
참고
네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Ncloud API 응답 상태 코드를 참조해 주십시오.
Cloud DB Serverless API
Cloud DB Serverless 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다.
Cluster
Cluster 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createCluster | 비동기 클러스터 생성 |
| getCluster | 클러스터 상세 조회 |
| listClusters | 클러스터 목록 조회 |
| updateCluster | 비동기 클러스터 설정 변경 |
| deleteCluster | 비동기 클러스터 삭제 |
| restoreCluster | 비동기 백업으로부터 클러스터 복원(신규 생성) |
Instance
Instance 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| getInstance | 인스턴스 상세 조회 |
| listInstances | 인스턴스 목록 조회 (read-only) |
| listProcesses | 프로세스(세션) 목록 조회 |
| batchKillProcesses | 비동기 세션 일괄 종료 |
Backup
Backup 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createImportedBackup | 비동기 Object Storage에서 백업 가져오기 |
| getBackup | 백업 상세 조회 |
| getImportedBackup | Imported Backup 상세 조회 |
| listBackups | 백업 목록 조회 |
| listImportedBackups | Imported Backup 목록 조회 |
| deleteImportedBackup | 비동기 Imported Backup 삭제 |
| exportBackup | 비동기 백업을 Object Storage로 내보내기 |
User
User 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createUser | 비동기 DB 사용자 생성 |
| getUser | DB 사용자 단건 조회 |
| listUsers | DB 사용자 목록 조회 |
| updateUser | 비동기 DB 사용자 변경 (비밀번호/권한) |
| deleteUser | 비동기 DB 사용자 삭제 |
| batchCreateUsers | 비동기 DB 사용자 일괄 생성 |
| batchDeleteUsers | 비동기 DB 사용자 일괄 삭제 |
Database
Database 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| createDatabase | 비동기 Database 생성 |
| getDatabase | Database 단건 조회 |
| listDatabases | Database 목록 조회 |
| deleteDatabase | 비동기 Database 삭제 |
| batchCreateDatabases | 비동기 Database 일괄 생성 |
| batchDeleteDatabases | 비동기 Database 일괄 삭제 |
Config
Config 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| getConfig | DB 파라미터 설정 조회 |
| listConfigParameters | 변경 가능 파라미터 카탈로그 조회 |
| updateConfig | 비동기 DB 파라미터 변경 |
Log
Log 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| getLogConfig | 로그 로테이션 설정 조회 |
| listLogs | 로그 파일 목록 조회 |
| updateLogConfig | 로그 로테이션 설정 변경 |
| batchDeleteLogs | 비동기 로그 파일 일괄 삭제 |
| exportLogs | 비동기 로그 파일을 Object Storage로 내보내기 |
Event
Event 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| listEvents | 이벤트(감사 이력) 조회 |
Engine Version
Engine Version 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| listEngineVersions | 지원 엔진 버전 조회 |
Operation
Operation 관련 API에 대한 설명은 다음과 같습니다.
| API | 설명 |
|---|---|
| getBackupOperation | 백업 Operation 단건 조회 |
| getClusterOperation | 클러스터 Operation 단건 조회 |
| getConfigOperation | DB 파라미터 변경 작업 Operation 단건 조회 |
| getDatabaseOperation | Database Operation 단건 조회 |
| getImportedBackupOperation | Imported Backup Operation 단건 조회 |
| getLogOperation | 로그 삭제·내보내기 작업 Operation 단건 조회 |
| getProcessOperation | 세션 종료 작업 Operation 단건 조회 |
| getUserOperation | 사용자 Operation 단건 조회 |
| listBackupOperations | 백업 Operation 목록 조회 |
| listClusterOperations | 클러스터 Operation 목록 조회 |
| listConfigOperations | DB 파라미터 변경 작업 Operation 목록 조회 |
| listDatabaseOperations | Database Operation 목록 조회 |
| listImportedBackupOperations | Imported Backup Operation 목록 조회 |
| listLogOperations | 로그 삭제·내보내기 작업 Operation 목록 조회 |
| listProcessOperations | 세션 종료 작업 Operation 목록 조회 |
| listUserOperations | 사용자 Operation 목록 조회 |
Cloud DB Serverless 연관 콘텐츠
Cloud DB Serverless API에 대한 사용자의 이해를 돕기 위해 다양한 연관 콘텐츠를 제공하고 있습니다.
-
Cloud DB Serverless API 사용 방법
- API 개요: 네이버 클라우드 플랫폼에서 발급받은 Access Key, Secret Key 발급 및 확인, 요청 헤더에 필요한 서명 생성 방법
- API Gateway 사용 가이드: 요청 헤더에 필요한 API Key 확인 방법
-
Cloud DB Serverless 서비스 사용 방법
- Cloud DB Serverless 사용 가이드: 네이버 클라우드 플랫폼 콘솔에서 Cloud DB Serverless 사용하는 방법
- Ncloud 사용 환경 가이드: VPC, Classic 환경 및 지원 여부에 대한 가이드
- 요금 소개, 특징, 상세 기능: Cloud DB Serverless의 요금 체계, 특징, 상세 기능 요약
- 서비스 최신 소식: Cloud DB Serverless 관련 최신 소식
- 자주 하는 질문: Cloud DB Serverless 사용자들이 자주 하는 질문
- 문의하기: 사용 가이드를 통해서도 궁금증이 해결되지 않는 경우 직접 문의