2024年2月19日发(作者：)
分布式关系数据库服务接口
1 范围
本标准规定了分布式计算环境中关系数据库服务应提供的接口，包括数据库实例接口和管理接口，同时规定分布式关系数据库服务接口的调用方式、共用参数和共用错误信息。
本标准适用于运行在分布式计算环境中关系数据库服务的研制和测试。
2 规范性引用文件
下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。
IETF RFC 2616 超文本传输协议 HTTP/1.1（Hypertext Transfer Protocol -- HTTP/1.1）
3 术语和定义
下列术语和定义适用于本文件。
3.1
数据库实例 database instance
一个独立占用物理内存的数据库服务进程。
4 缩略语
下列缩略语适用于本文件。
HTTP：超文本传输协议（hypertext transfer protocol）
JSON：JavaScript对象标记（javascript object notation）
URL：统一资源定位符（uniform resource locators）
XML：可扩展置标语言（extensible markup language）
5 接口调用方式
5.1 请求
应通过IETF RFC 2616中规定的HTTP请求格式调用分布式关系数据库服务产品接口，并将请求参数包含在请求的URL中。
5.2 返回
调用成功后应以XML或JSON格式返回结果，调用失败时返回相应的错误信息。
6 接口定义格式
分布式关系数据库服务产品的数据库实例接口和管理接口定义格式如下：
a)
接口名：接口的名称；
b)
描述：对接口内容的简单描述；
c)
参数：请求调用的参数；
d)
返回值：请求返回的内容；
e)
错误信息：调用错误时返回的信息。
7 数据库实例接口
7.1 概述
本章的接口定义按照第5章的接口定义格式表示。
7.2 创建数据库实例
接口名：CreateDBInstance
描述：创建数据库实例
参数：见表1
表1 创建数据库实例接口参数
参数名
BackupRetentionPeriod
DBInstanceClass
DBInstanceId
DBInstanceStorage
Engine
EngineVersion
MasterUserPassword
MasterUsername
Port
Region
自动备份保留的天数
数据库实例类型，指定数据库实例的规格
数据库实例标识符
描述 类型
整型
字符串
字符串
选择
可选
必选
必选
可选
必选
可选
必选
必选
可选
可选
为数据库实例初始分配的存储空间大小，以GB为单位 整型
实例使用的数据库引擎名
实例使用的数据库引擎版本
数据库主用户的密码
数据库实例的主用户名称
应用访问端口
数据中心
字符串
字符串
字符串
字符串
字符串
字符串
返回值：见表2
表2 创建数据库实例接口返回值
参数名
BackupRetentionPeriod
DBInstanceClass
DBInstanceId
DBInstanceStatus
DBInstanceStorage
Engine
EngineVersion
MasterUsername
InstanceCreateTime
Region
自动备份保留的天数
数据库实例类型，指定数据库实例的规格
数据库实例标识符
数据库实例的当前状态
描述
整型
字符串
字符串
字符串
类型
为数据库实例初始分配的存储空间大小，以GB为单位 整型
实例使用的数据库引擎名
实例使用的数据库引擎版本
数据库实例的主用户名称
该数据库实例创建的时间
数据中心
字符串
字符串
字符串
日期时间
字符串
错误信息：见表3
表2 创建数据库实例接口错误信息
错误信息
DBInstanceAlreadyExists
StorageQuotaExceeded
描述
请求参数DBInstanceId指定的数据库实例已存在
请求的存储空间大小大于用户可用的存储空间
400
400
HTTP状态代码
7.3 删除数据库实例
接口名：DeleteDBInstance
描述：删除数据库实例
参数：见表4
表3 删除数据库实例接口参数
参数名
DBInstanceId 数据库实例标识符
描述 类型
字符串
选择
必选
返回值：见表5
表4 删除数据库实例接口返回值
参数名
BackupRetentionPeriod
DBInstanceClass
DBInstanceId
DBInstanceStatus
DBInstanceStorage
Engine
EngineVersion
MasterUsername
InstanceCreateTime
Region
自动备份保留的天数
数据库实例类型，指定数据库实例的规格
数据库实例标识符
数据库实例的当前状态
描述
整型
字符串
字符串
字符串
类型
为数据库实例初始分配的存储空间大小，以GB为单位 整型
实例使用的数据库引擎名
实例使用的数据库引擎版本
数据库实例的主用户名称
该数据库实例创建的时间
数据中心
字符串
字符串
字符串
日期时间
字符串
错误信息：见表6
表5 删除数据库实例接口错误信息
错误信息
DBInstanceNotFound
InvalidDBInstanceState
描述
请求参数DBInstanceId指定的数据库实例不存在
指定的数据库实例当前为不可用状态
404
400
HTTP状态代码
7.4 修改数据库实例
接口名：ModifyDBInstance
描述：修改数据库实例
参数：见表7
表6 修改数据库实例接口参数
参数名
BackupRetentionPeriod
DBInstanceClass
DBInstanceId
DBInstanceStorage
EngineVersion
MasterUserPassword
NewDBInstanceId
自动备份保留的天数
数据库实例类型，指定数据库实例的规格
数据库实例标识符
描述 类型
整型
字符串
字符串
选择
可选
可选
必选
可选
可选
必选
可选
为数据库实例初始分配的存储空间大小，以GB为单位 整型
实例使用的数据库引擎版本
数据库主用户的密码
数据库实例的新标识符，用于重命名数据库实例
字符串
字符串
字符串
返回值：见表8
表7 修改数据库实例接口返回值
参数名
BackupRetentionPeriod
DBInstanceClass
DBInstanceId
DBInstanceStatus
DBInstanceStorage
Engine
EngineVersion
MasterUsername
InstanceCreateTime
Region
自动备份保留的天数
数据库实例类型，指定数据库实例的规格
数据库实例标识符
数据库实例的当前状态
描述
整型
字符串
字符串
字符串
类型
为数据库实例初始分配的存储空间大小，以GB为单位 整型
实例使用的数据库引擎名
实例使用的数据库引擎版本
数据库实例的主用户名称
该数据库实例创建的时间
数据中心
字符串
字符串
字符串
日期时间
字符串
错误信息：见表9
表8 修改数据库实例接口错误信息
错误信息
DBInstanceNotFound
InvalidDBInstanceState
StorageQuotaExceeded
描述
请求参数DBInstanceId指定的数据库实例不存在
指定的数据库实例当前为不可用状态
请求的存储空间大小大于用户可用的存储空间
404
400
400
HTTP状态代码
7.5 查看数据库实例
接口名：DescribeDBInstances
描述：返回关系数据库服务系统实例的相关信息
参数：见表10
表9 查看数据库实例接口参数
参数名
DBInstanceId 数据库实例标识符
描述 类型
字符串
选择
可选
返回值：见表11
表10 查看数据库实例接口返回值
参数名
BackupRetentionPeriod
DBInstanceClass
DBInstanceId
DBInstanceStatus
DBInstanceStorage
Engine
EngineVersion
InstanceCreateTime
Port
Region
自动备份保留的天数
数据库实例类型，指定数据库实例的规格
数据库实例标识符
数据库实例的当前状态
为数据库实例初始分配的存储空间大小，以GB为单位
实例使用的数据库引擎名
实例使用的数据库引擎版本
该数据库实例创建的时间
应用访问端口
数据中心
描述
整型
字符串
字符串
字符串
整型
字符串
字符串
日期时间
字符串
字符串
类型
错误信息：见表12
表11 查看数据库实例接口错误信息
错误信息
DBInstanceNotFound
描述
请求参数DBInstanceId指定的数据库实例不存在 404
HTTP状态代码
7.6 重启数据库实例
接口名：RebootDBInstance
描述： 重启数据库实例将重启数据库引擎服务
参数：见表13
表12 重启数据库实例接口参数
参数名
DBInstanceId 数据库实例标识符
描述 类型
字符串
选择
必选
返回值：见表14
表13 重启数据库实例接口返回值
参数名
BackupRetentionPeriod
DBInstanceClass
DBInstanceId
DBInstanceStatus
DBInstanceStorage
自动备份保留的天数
数据库实例类型，指定数据库实例的规格
数据库实例标识符
数据库实例的当前状态
为数据库实例初始分配的存储空间大小，以GB为单位
Engine
EngineVersion
MasterUsername
InstanceCreateTime
Region
实例使用的数据库引擎名
实例使用的数据库引擎版本
数据库实例的主用户名称
该数据库实例创建的时间
数据中心
字符串
字符串
字符串
日期时间
字符串
描述
整型
字符串
字符串
字符串
整型
类型
错误信息：见表15
表14 重启数据库实例接口错误信息
错误信息
DBInstanceNotFound
InvalidDBInstanceState
描述
请求参数DBInstanceId指定的数据库实例不存在
指定的数据库实例当前为不可用状态
404
400
HTTP状态代码
8 管理接口
8.1 概述
本章的接口定义按照第6章的接口定义格式表示。
8.2 查看数据库引擎版本
接口名：DescribeDBEngineVersions
描述： 查看可用的数据库引擎
参数：见表16
表15 查看数据库引擎版本接口参数
参数名
DefaultOnly
Engine
EngineVersion
描述
指定是否只返回指定引擎的默认版本
数据库引擎名
数据库引擎版本
类型
布尔型
字符串
字符串
选择
可选
可选
可选
返回值：见表17
表16 查看数据库引擎版本接口返回值
参数名
DBEngineDescription
DBEngineVersionDescription
Engine
EngineVersion
数据库引擎描述
数据库引擎版本描述
数据库引擎名称
数据库引擎版本号
描述
字符串
字符串
字符串
字符串
类型
错误信息：无
8.3 查看数据库日志文件
接口名：DescribeDBLogFiles
描述：返回数据库实例的日志文件
参数：见表18
表17 查看数据库日志文件接口参数
参数名
DBInstanceId
FileLastWritten
描述
需要返回日志文件的数据库实例名
返回的日志文件的起始日期
类型
字符串
长整型
选择
必选
可选
FileSize
FilenameContains
日志文件大小
返回的日志文件名中包含的字符串
长整型
字符串
可选
可选
返回值：见表19
表18 查看数据库日志文件接口返回值
参数名
LastWritten
LogFileName
Size
描述
最近的日志的生成时间
日志文件名
日志文件大小
长整型
字符串
长整型
类型
错误信息：见表20
表19 查看数据库日志文件接口错误信息
错误信息
DBInstanceNotFound
描述
请求参数DBInstanceId指定的数据库实例不存在 404
HTTP状态代码
8.4 下载查看数据库日志文件
接口名：DownloadDBLogFilePortion
描述：下载指定的日志文件
参数：见表21
表20 下载查看数据库日志文件接口参数
参数名
DBInstanceId
LogFileName
描述
含有需要下载的日志文件的数据库实例名
需要下载的日志文件名
类型
字符串
字符串
选择
必选
可选
返回值：见表22
表21 下载查看数据库日志文件接口返回值
参数名
LogFileData 下载的日志文件
描述
字符串
类型
错误信息：见表23
表22 下载查看数据库日志文件接口错误信息
错误信息
DBInstanceNotFound
描述
请求参数DBInstanceId指定的数据库实例不存在 404
HTTP状态代码
9 共用参数
共用参数是每个分布式关系数据库服务产品接口都需要使用到的请求参数，见表24。
表23 共用参数
参数名
Action
AccessKeyId
Format
Signature
SignatureMethod
SignatureVersion
Timestamp
Version
描述
执行的操作，即调用的接口名
用户访问服务所用的密钥标识
结果返回的格式，可为JSON或XML
为请求创建的数字签名
签名算法
签名算法版本
请求的时间戳
服务接口版本号，表达格式为：YYYY-MM-DD
类型
字符串
字符串
字符串
字符串
字符串
字符串
字符串
字符串
是否必选
是
是
否
是
是
是
是
是
10 共用错误信息
共用错误信息适用于分布式关系数据库服务产品的数据库实例接口和管理接口，见表25。
表24 共用错误信息
错误信息
InternalError
InvalidAction
UnsupportedOperation
InvalidParameter
MissingParameter
ServiceUnavailable
指定的参数不正确
必选的参数缺失
由服务器失效造成的请求失败
400
400
503
描述
由未知的错误、异常或失效导致请求失败
请求的操作不可用
500
400
HTTP状态代码
发布评论