云数据库 GaussDB 2.23.07.210 使用指南(for 华为云Stack 8.3.0) 04
云数据库 GaussDB
2.23.07.210
API 参考
文档版本 01
发布日期 2023-10-30
华为云计算技术有限公司
版权所有 © 华为云计算技术有限公司 2023。 保留一切权利。
非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传
播。
商标声明
和其他华为商标均为华为技术有限公司的商标。
本文档提及的其他所有商标或注册商标，由各自的所有人拥有。
注意
您购买的产品、服务或特性等应受华为云计算技术有限公司商业合同和条款的约束，本文档中描述的全部或部
分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为云计算技术有限公司对本文
档内容不做任何明示或暗示的声明或保证。
由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文
档中的所有陈述、信息和建议不构成任何明示或暗示的担保。
华为云计算技术有限公司
地址： 贵州省贵安新区黔中大道交兴功路华为云数据中心 邮编：550029
网址： https://www.huaweicloud.com/
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 i
云数据库 GaussDB
API 参考 目 录
目 录
1 使用前必读.................................................................................................................................. 1
1.1 概述.............................................................................................................................................................................................. 1
1.2 调用说明......................................................................................................................................................................................1
1.3 终端节点......................................................................................................................................................................................1
1.4 约束限制......................................................................................................................................................................................1
1.5 基本概念......................................................................................................................................................................................1
2 API 概览...................................................................................................................................... 3
3 如何调用 API...............................................................................................................................4
3.1 构造请求......................................................................................................................................................................................4
3.2 认证鉴权......................................................................................................................................................................................7
3.3 返回结果......................................................................................................................................................................................8
4 API（推荐）............................................................................................................................. 10
4.1 实例管理................................................................................................................................................................................... 10
4.1.1 创建数据库实例................................................................................................................................................................... 10
4.1.2 删除数据库实例................................................................................................................................................................... 21
4.1.3 查询数据库实例列表.......................................................................................................................................................... 22
4.1.4 同城切换 AZ......................................................................................................................................................................... 35
4.1.5 分片节点主备切换.............................................................................................................................................................. 36
4.1.6 查询实例的组件列表.......................................................................................................................................................... 39
4.1.7 实例主备状态重置.............................................................................................................................................................. 44
4.1.8 查询实例主备平衡状态......................................................................................................................................................46
4.1.9 查询实例扩展信息.............................................................................................................................................................. 47
4.1.10 设置实例扩展信息............................................................................................................................................................ 49
4.1.11 启动实例/节点................................................................................................................................................................... 50
4.1.12 停止实例/节点................................................................................................................................................................... 52
4.1.13 切换透明加密.....................................................................................................................................................................54
4.1.14 结束空闲会话.....................................................................................................................................................................56
4.1.15 结束会话............................................................................................................................................................................. 58
4.1.16 获取实时会话.....................................................................................................................................................................60
4.2 参数配置................................................................................................................................................................................... 62
4.2.1 获取参数模板列表.............................................................................................................................................................. 62
4.2.2 获取指定实例的参数.......................................................................................................................................................... 65
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 ii
云数据库 GaussDB
API 参考 目 录
4.2.3 修改指定实例的参数.......................................................................................................................................................... 67
4.2.4 创建参数模板....................................................................................................................................................................... 69
4.2.5 删除参数模板....................................................................................................................................................................... 72
4.2.6 查询参数模板详情.............................................................................................................................................................. 73
4.2.7 复制参数模板....................................................................................................................................................................... 76
4.2.8 重置参数组........................................................................................................................................................................... 78
4.2.9 比较两个参数组模板之间的差异.................................................................................................................................... 79
4.2.10 查询可应用实例列表........................................................................................................................................................81
4.2.11 校验参数组名称是否存在............................................................................................................................................... 83
4.2.12 应用参数模板.....................................................................................................................................................................84
4.2.13 查询参数模板的应用记录............................................................................................................................................... 86
4.2.14 查询参数模板的修改历史............................................................................................................................................... 88
4.3 备份管理................................................................................................................................................................................... 90
4.3.1 查询备份列表....................................................................................................................................................................... 90
4.3.2 创建手动备份....................................................................................................................................................................... 94
4.3.3 删除手动备份....................................................................................................................................................................... 98
4.3.4 查询可恢复时间段.............................................................................................................................................................. 99
4.3.5 恢复到新实例.....................................................................................................................................................................101
4.3.6 恢复到当前实例................................................................................................................................................................ 113
4.3.7 备份恢复后执行数据确认............................................................................................................................................... 118
4.3.8 查询差量备份列表............................................................................................................................................................ 119
4.3.9 安装三方备份 SSL 证书................................................................................................................................................... 122
4.4 引擎版本和规格.................................................................................................................................................................... 124
4.4.1 查询引擎列表.....................................................................................................................................................................124
4.5 管理数据库和用户............................................................................................................................................................... 125
4.5.1 创建数据库......................................................................................................................................................................... 126
4.5.2 创建数据库用户................................................................................................................................................................ 128
4.5.3 创建数据库 SCHEMA...................................................................................................................................................... 130
4.5.4 授权数据库帐号................................................................................................................................................................ 132
4.5.5 重置数据库帐号密码........................................................................................................................................................135
4.5.6 查询数据库列表................................................................................................................................................................ 137
4.5.7 查询数据库用户列表........................................................................................................................................................139
4.5.8 查询数据库 SCHEMA 列表.............................................................................................................................................141
4.6 容灾管理................................................................................................................................................................................. 143
4.6.1 查询容灾集群监控状态................................................................................................................................................... 144
4.6.2 查询容灾关系列表............................................................................................................................................................ 145
4.6.3 搭建容灾关系.....................................................................................................................................................................149
4.6.4 备实例容灾升主................................................................................................................................................................ 151
4.6.5 解除容灾关系.....................................................................................................................................................................152
4.6.6 灾备实例主从切换............................................................................................................................................................ 154
4.6.7 重建容灾关系.....................................................................................................................................................................156
4.6.8 开启容灾演练.....................................................................................................................................................................157
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 iii
云数据库 GaussDB
API 参考 目 录
4.6.9 结束容灾演练.....................................................................................................................................................................159
4.6.10 开启日志保持.................................................................................................................................................................. 161
4.6.11 结束日志保持.................................................................................................................................................................. 163
4.6.12 重置容灾配置.................................................................................................................................................................. 164
4.7 任务管理................................................................................................................................................................................. 166
4.7.1 获取任务信息.....................................................................................................................................................................166
5 历史 API.................................................................................................................................. 169
5.1 实例管理................................................................................................................................................................................. 169
5.1.1 创建数据库实例................................................................................................................................................................ 169
5.1.2 删除数据库实例................................................................................................................................................................ 178
5.1.3 查询数据库实例列表........................................................................................................................................................180
5.1.4 同城切换 AZ....................................................................................................................................................................... 193
5.1.5 实例主备状态重置............................................................................................................................................................ 195
5.1.6 查询实例主备平衡状态................................................................................................................................................... 196
5.2 备份管理................................................................................................................................................................................. 198
5.2.1 查询备份列表.....................................................................................................................................................................198
5.2.2 创建手动备份.....................................................................................................................................................................202
5.2.3 删除手动备份.....................................................................................................................................................................204
5.2.4 恢复到新实例.....................................................................................................................................................................205
5.3 容灾管理（V3.1）............................................................................................................................................................... 215
5.3.1 查询可搭建容灾实例列表............................................................................................................................................... 215
5.3.2 容灾操作校验.....................................................................................................................................................................217
5.3.3 查询容灾集群监控状态................................................................................................................................................... 219
5.3.4 查询容灾关系列表............................................................................................................................................................ 222
5.3.5 搭建容灾关系.....................................................................................................................................................................225
5.3.6 备实例容灾升主................................................................................................................................................................ 227
5.3.7 解除容灾关系.....................................................................................................................................................................229
5.3.8 灾备实例主从切换............................................................................................................................................................ 231
5.3.9 重建容灾关系.....................................................................................................................................................................232
5.3.10 开启容灾演练.................................................................................................................................................................. 233
5.3.11 结束容灾演练.................................................................................................................................................................. 235
5.3.12 开启日志保持.................................................................................................................................................................. 236
5.3.13 结束日志保持.................................................................................................................................................................. 238
6 附录......................................................................................................................................... 240
6.1 异常请求结果........................................................................................................................................................................ 240
6.2 状态码..................................................................................................................................................................................... 240
6.3 错误码..................................................................................................................................................................................... 243
6.4 获取项目 ID/名称................................................................................................................................................................. 280
6.5 获取终端节点........................................................................................................................................................................ 280
6.6 ReplicationMode 列表....................................................................................................................................................... 281
6.7 数据库实例规格.................................................................................................................................................................... 282
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 iv
云数据库 GaussDB
API 参考 目 录
7 修订记录................................................................................................................................. 284
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 v
云数据库 GaussDB
API 参考 1 使用前必读
1 使用前必读
1.1 概述
GaussDB是华为自主创新研发的分布式关系型数据库。该产品支持分布式事务，同城
跨AZ部署，数据0丢失，支持1000+的扩展能力，PB级海量存储。同时拥有云上高可
用，高可靠，高安全，弹性伸缩，一键部署，快速备份恢复，监控告警等关键能力，
能为企业提供功能全面，稳定可靠，扩展性强，性能优越的企业级数据库服务。
您可以使用本文档提供API对数据库实例进行相关操作，如创建、删除等。支持的全部
操作请参见API概览。
1.2 调用说明
GaussDB提供了REST（Representational State Transfer）风格API，支持您通过
HTTPS请求调用，调用方法请参见API概览。
1.3 终端节点
终端节点（Endpoint）即调用API的请求地址，不同服务不同区域的终端节点不同，您
需要提前联系企业管理员，获取终端节点。
1.4 约束限制
详细的限制请参见具体API的说明。
1.5 基本概念
● 帐号
用户注册时的帐号，帐号对其所拥有的资源及云服务具有完全的访问权限，可以
重置用户密码、分配用户权限等。为了确保帐号安全，建议您不要直接使用帐号
进行日常管理工作。
● 用户
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 1
云数据库 GaussDB
API 参考 1 使用前必读
用户是云服务的使用人员，具有身份凭证（密码和访问密钥）。
您需要用到帐号、用户和密码等信息。
● 区域
指云资源所在的物理位置，同一区域内可用区间内网互通，不同区域间内网不互
通。通过在不同地区创建云资源，可以将应用程序设计的更接近特定客户的要
求，或满足不同地区的法律或其他要求。
● 可用区
一个可用区是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上
再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高
速光纤相连，以满足用户跨AZ构建高可用性系统的需求。
● 资源集
用户只有和资源集关联，在界面中即用户只有和资源集关联了同一个用户组，才
可以申请或管理资源，其中用户申请的资源就属于该资源集，从而实现资源分
组。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 2
云数据库 GaussDB
API 参考 2 API 概览
2 API 概览
通过使用GaussDB接口，您可以使用GaussDB的创建实例、删除实例等功能。
类型 子类型 说明
GaussDB 接口 实例管理 包括创建实例、删除实例、查询实例列表接口。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 3
云数据库 GaussDB
API 参考 3 如何调用 API
3 如何调用 API
3.1 构造请求
本节介绍REST API请求的组成，并以调用IAM服务获取用户Token说明如何调用API。
该API获取用户的Token，Token可以用于调用其他API时鉴权。
请求 URI
请求URI由如下部分组成：
{URI-scheme}://{Endpoint}/{resource-path}?{query-string}
尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传
递它，所以在此单独强调。
表 3-1 URI 中的参数说明
参数 描述
URI-scheme 表示用于传输请求的协议，当前所有API均采用HTTPS协议。
Endpoint 指定承载REST服务端点的服务器域名或IP，不同服务不同区域的
Endpoint不同，您可以从获取IAM服务的终端节点获取。
resource-path 资源路径，即API访问路径。从具体API的URI模块获取，例如“获
取用户Token”API的resource-path为“/v3/auth/tokens”。
query-string 查询参数，是可选部分，并不是每个API都有查询参数。查询参数
前面需要带一个“？”，形式为“参数名=参数取值”，例如
“limit=10”，表示查询不超过10条数据。
说明
为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。
这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分
省略。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 4
云数据库 GaussDB
API 参考 3 如何调用 API
请求方法
HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。
表 3-2 HTTP 方法
方法 说明
GET 请求服务器返回指定资源。
PUT 请求服务器更新指定资源。
POST 请求服务器新增资源或执行特殊操作。
DELETE 请求服务器删除指定资源，如删除对象等。
在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为：
POST https://{{Endpoint}}/v3/auth/tokens
请求消息头
附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请
求头“Content-Type”，请求鉴权信息等。
详细的公共请求消息头字段请参见表3-3。
表 3-3 公共请求消息头
名称 描述 是否必选 示例
Host 请求的服务器信 否 code.test.com
息，从服务API的 or
URL中获取。值为
hostname[:port]。 code.test.com:443
端口缺省时使用默
认的端口，https的
默认端口为443。
Content-Type 发送的实体的MIME 是 application/json
类型。推荐用户默
认使用application/
json，如果API是对
象、镜像上传等接
口，媒体类型可按
照流类型的不同进
行确定。
Content- 请求body长度，单 否 3495
Length 位为Byte。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 5
云数据库 GaussDB
API 参考 3 如何调用 API
名称 描述 是否必选 示例
X-Project-Id project id，项目编 否 e9993fc787d94b6c886cb
号。请参考获取项 aa340f9c0f4
目ID/名称章节获取
项目编号。
X-Auth-Token 用户Token。 否 注：以下仅为Token示例片
用户Token也就是调 使用Token认 段
用获取用户Token接 证时该字段必 MIIPAgYJKoZIhvcNAQcCo
口的响应值，该接 选。 ...ggg1BBIINPXsidG9rZ
口是唯一不需要认
证的接口。
请求响应成功后在
响应消息头中包含
的“X-Subject-
Token”的值即为
Token值。
对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加
消息头后的请求如下所示。
POST https://{{Endpoint}}/v3/auth/tokens
Content-Type: application/json
请求消息体（可选）
该部分可选。请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中
Content-Type对应，传递除请求消息头之外的内容。若请求消息体中的参数支持中
文，则中文字符必须为UTF-8编码。
每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消
息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根
据具体接口而定。
对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。
将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中
username为用户名，domainname为用户所属的帐号名称，********为用户登录密
码，xxxxxxxxxxxxxxxxxx为project的名称，您可以从管理员处获取。
说明
scope参数定义了Token的作用域，上面示例中获取的Token仅能访问project下的资源。您还可
以设置Token的作用域为某个帐号下所有资源或帐号的某个project下的资源，详细定义请参见获
取用户Token。
POST https://{{Endpoint}}/v3/auth/tokens
Content-Type: application/json
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 6
云数据库 GaussDB
API 参考 3 如何调用 API
"name": "username",
"password": "********",
"domain": {
"name": "domainname"
}
}
}
},
"scope": {
"project": {
"name": "xxxxxxxxxxxxxxxxxx"
}
}
}
}
到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编
写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x-
subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认
证调用其他API。
3.2 认证鉴权
调用接口需进行Token认证鉴权。
Token认证：通过Token认证调用请求。
Token 认证
说明
Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。
Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。
Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得
操作API的权限。
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"name": "username",
"password": "********",
"domain": {
"name": "domainname"
}
}
}
},
"scope": {
"project": {
"name": "xxxxxxxx"
}
}
}
}
在构造请求中以调用获取用户Token接口为例说明了如何调用API。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 7
云数据库 GaussDB
API 参考 3 如何调用 API
获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，
其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token:
ABCDEFJ....”加到请求消息头即可，如下所示。
POST https://{{Endpoint}}/v3/auth/projects
Content-Type: application/json
X-Auth-Token: ABCDEFJ....
3.3 返回结果
状态码
请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。
状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码
列表请参见状态码。
对于获取用户Token接口，如果调用后返回状态码为“201”，则表示请求成功。
响应消息头
对应请求消息头，响应同样也有消息头，如“Content-type”。
对于获取用户Token接口，返回如图3-1所示的消息头，其中“x-subject-token”就是
需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。
图 3-1 获取用户 Token 响应消息头
响应消息体（可选）
该部分可选。响应消息体通常以结构化格式（如JSON或XML）返回，与响应消息头中
Content-Type对应，传递除响应消息头之外的内容。
对于获取用户Token接口，返回如下消息体，为篇幅起见，这里只展示部分内容。
{
"token": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 8
云数据库 GaussDB
API 参考 3 如何调用 API
"expires_at": "2019-02-13T06:52:13.855000Z",
"methods": [
"password"
],
"catalog": [
{
"endpoints": [
{
"region_id": "az-01",
......
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 9
云数据库 GaussDB
API 参考 4 API（推荐）
4 API（推荐）
4.1 实例管理
4.1.1 创建数据库实例
功能介绍
创建GaussDB实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/054ea741f700d4a32f1bc00f5c80dd4c/instances
● 参数说明
表 4-1 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项
目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 10
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
表 4-2 参数说明
名称 是否必 参数类型 说明
选
name 是 String 实例名称。
用于表示实例的名称，同一租户下，同类型
的实例名可重名。
取值范围：4~64个字符之间，必须以字母
开头，区分大小写，可以包含字母、数字、
中划线或者下划线，不能包含其他的特殊字
符。
datastore 是 Object 数据库信息。
详情请参见表4-3。
ha 是 Object 实例部署形态。详情请参见表4-4。
configuration_i 否 String 参数模板ID。当不传该参数时，使用系统默
d 认的参数模板，且响应体中不返回该参数
port 否 String GaussDB数据库端口当前只支持设置为
8000，当不传该参数时，默认端口为
8000。
password 是 String 数据库密码。
GaussDB密码取值范围:
非空； 至少包含大写字母（A-Z），小写字
母（a-z），数字（0-9），非字母数字字符
（限定为~!@#$%^&*()-_=+|[{}];:,<>/?）四
类字符中的三类字符；长度8~32个字符。
建议您输入高强度密码，以提高安全性，防
止出现密码被暴力破解等安全风险。
backup_strateg 否 Object 备份策略。
y 详情请参见表4-5。
enterprise_proje 否 String 企业项目ID。创建指定企业项目实例时必
ct_id 选。
flavor_ref 是 String 规格码，取值范围：非空。参考数据库实例
规格中GaussDB的“规格编码”列内容获
取。
volume 是 Object volume信息。
详情请参见表4-6。
region 是 String 区域ID。
取值范围：非空，请向企业管理员获取。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 11
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必 参数类型 说明
选
availability_zon 是 String 可用区ID。
e GaussDB取值范围：非空，可选部署在同一
可用区或三个不同可用区，可用区之间用逗
号隔开。详见请求示例。
● 部署在同一可用区：需要输入三个相同
的可用区。
● 部署在三个不同可用区：需要分别输入
三个不同的可用区。
取值范围：非空，请向企业管理员获取。
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界
面，在虚拟私有云的详情页面查找VPC
ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询VPC列表”的内容。
subnet_id 是 String 子网的网络ID信息，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界
面，单击VPC下的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询子网列表”的内容。
security_group_ 是 String 指定实例所属的安全组。
id ● 方法1：登录虚拟私有云服务的控制台界
面，在安全组的详情页面查找安全组
ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询安全组列表”的内
容。
charge_info 否 Object 计费类型信息。
详情请参见表4-7。
time_zone 否 String UTC时区。
● 不选择时，GaussDB默认为UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且只支持整段
时间，如UTC+08:00，不支持UTC
+08:30。
solution 是 String GaussDB支持的部署模式，ha字段选择为
“ha”时必填，当前可选的有triset。
kms_tde_key_id 否 String GaussDB使用透明加密的KMS主密钥ID，填
写ID启用透明加密功能。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 12
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必 参数类型 说明
选
kms_project_na 否 String kms_tde_key_id不为空时必传。GaussDB使
me 用透明加密的KMS主密钥ID所在资源空间名
称。
获取方法请参见获取项目ID/名称。
表 4-3 datastore 字段数据结构说明
名称 是 参数类型 说明
否
必
选
type 是 String 数据库引擎，取值如下：
GaussDB。不区分大小写。
version 否 String 数据库版本。不填时，默认为当前最新版
本。
GaussDB支持如下版本：
● 1.3
● 1.4
● 2.1
● 2.2
● 2.3
● 2.5
● 2.7
● 2.8
● 3.200
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 13
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-4 ha 字段数据结构说明
名称 是 参数类型 说明
否
必
选
mode 是 String GaussDB当前只支持创建主备模式，取
值：
centralization_standard：主备模式，不区
分大小写。
说明
参数填写为ha，也可以下发主备模式的实例，
但是不建议使用，保留该取值是为了兼容历史取
值。
consistency 是 String 指定事务一致性类型，取值范围：strong
（强一致性） | eventual(最终一致性)，不
分区大小写。
replication_mode 是 String 备机同步参数。
取值：
GaussDB为“sync"
说明
“sync”为同步模式。
consistency_proto 否 String 指定副本一致性协议类型，取值范围：
col ● quorum：quorum模式是主备同步复制
机制，客户端发起事务后，必须要等待
对应的WAL日志复制到多个副本后，主
库才会响应给客户端，少数节点的宕机
不影响全局可用性，保证数据的一致
性。
● paxos：该模式解决了quorum模式下日
志复制过程中日志分叉的问题，提高日
志复制吞吐量，增加DN自仲裁能力。
不区分大小写。不填时，默认为quorum。
说明
开放
“gaussdb_feature_supportSetConsistencyProt
ocol”白名单后，支持创建paxos协议实例，且
仅支持3.200及以上版本的主备版实例。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 14
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-5 backup_strategy 字段数据结构说明
名称 是 参数类型 说明
否
必
选
start_time 是 String 备份时间段。自动备份将在该时间段内触
发。
取值范围：非空且非负，格式必须为
hh:mm-HH:MM且有效，当前时间指UTC
时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值必须
为00。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days 否 Integer 指定备份文件的可保存天数。
取值范围： 1-36500，开放
“gaussdb_feature_supportConsoleBack
upPolicyDay_36500”白名单后，支持备
份文件最长保留天数36500天。该参数缺
省时，默认填写为7天。
表 4-6 volume 字段数据结构说明
名称 是否 参数类型 说明
必选
type 是 String 磁盘类型。
LOCALSSD：主备模式都支持，表示本地
SSD盘。
ULTRAHIGH：仅ECS部署形态支持，表示
云磁盘。
size 是 Integer 磁盘大小。例如：该参数填写为“40”，
表示为创建的实例分配40GB的磁盘空间。
ECS部署方案：取值范围：（分片数
*40GB）~（分片数*16TB），且大小只能
为分片数*40的整数倍。
MCS部署方案：取值范围：（分片数
*40GB）~（分片数*16TB），且大小只能
为分片数*40的整数倍。
BMS部署方案：该参数由所选择的规格自
动计算，不可指定，即使填写，也不会生
效。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 15
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-7 chargeInfo 字段数据结构说明
名称 是否 参数类型 说明
必选
charge_mode 是 String 计费模式。
请求示例
创建主备版实例：
{
"name": "user_v3_ha_01",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"volume": {
"type": "LOCALSSD",
"size": "120"
},
"region": "sa-fb-1",
"availability_zone": "az4.dc0,az4.dc0,az4.dc0",
"vpc_id": "c0a17a45-5e4a-4166-9cd6-cf9846f776a2",
"subnet_id": "ba239f09-7b59-4233-80c9-af2b418803ae",
"security_group_id": "093807ac-4d7a-44c6-b554-b3460dab50cf",
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 7
},
"charge_info": {
"charge_mode": "postPaid"
},
"password": "xxxxxx",
"configuration_id": "26f22545846040d1a02163a068b6b3a3pr14",
"time_zone": "UTC+08:00",
"ha":{
"mode":"ha",
"consistency":"strong",
"replication_mode":"sync" ,
"consistency_protocol":"quorum"
},
"port": "8000",
"solution": "triset"
}
响应消息
● 正常响应要素说明
表 4-8 要素说明
名称 参数类型 说明
instance Object 实例信息。
详情请参见表4-9。
job_id String 实例创建的任务id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 16
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-9 instance 说明
名称 参数类型 说明
id String 实例id。
name String 实例名称。用于表示实例的名称，同一
租户下，同类型的实例名称可相同。
取值范围：4~64个字符之间，必须以
字母开头，不区分大小写，可以包含字
母、数字、中划线或者下划线，不能包
含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
datastore Object 数据库信息。
详情请参见表4-10。
ha Object 数据库部署形态。
详情请参见表4-11。
replica_num Integer 实例副本数。
configuration_id String 参数模板id，仅当您创建实例指定用户
自定义参数组时，该参数才可见。
port String 数据库端口信息，与请求参数相同。
backup_strategy Object 自动备份策略。
详情请参见表4-12。
flavor_ref String 规格码，取值范围：非空。参考数据库
实例规格中GaussDB的“规格编码”列
内容获取。
volume Object volume信息。
详情请参见表4-13。
region String 区域ID。
availability_zone String 可用区ID。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
security_group_id String 实例所属的安全组。
charge_info Object 付费方式信息。
详情请参见表4-14。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 17
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-10 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎，返回值如下：
GaussDB
version String 数据库版本。
表 4-11 ha 字段数据结构说明
名称 参数类型 说明
mode String GaussDB支持取值：ha(solution为triset
时选择)enterprise(企业版) ，不区分大小
写。
replication_ String 备机同步参数。
mode 取值：
GaussDB为“sync”。
说明
“sync”为同步模式。
consistency String GaussDB的预留参数：指定事务一致性类
型，取值范围：strong（强一致性） |
eventual(最终一致性)。
consistency_ String 指定副本一致性协议类型，取值范围：
protocol quorum | paxos。不填时，默认为
quorum。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 18
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-12 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内
触发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值必
须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
如果请求体中不填写
“backup_strategy”字段，则响应体中
“start_time”默认返回
“02:00-03:00”。
keep_days Integer 指定已生成备份文件的可保存天数。
取值范围：1～732。如果请求体中不填
写“backup_strategy”字段，则响应体
中 “keep_days”默认填写为30天。
表 4-13 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
取值如下，区分大小写：
● LOCALSSD，表示本地SSD盘。
● ULTRAHIGH，区分大小写，表示云磁
盘。
size Integer 磁盘大小。
GaussDB分布式实例创建时需指定大
小：要求必须为（分片数 * 40GB）的倍
数，取值范围：（分片数*40GB）~（分
片数*16TB）。
表 4-14 charge_Info 字段数据结构说明
名称 参数类型 说明
charge_mode String 计费模式。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 19
云数据库 GaussDB
API 参考 4 API（推荐）
● 正常响应样例
{
"instance": {
"id": "2afb68bc983742308f7a878581762a49in14",
"name": "user_v3_ha_01",
"status": "BUILD",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"ha": {
"mode": "centralization_standard",
"replication_mode": "sync",
"consistency": "strong",
"consistency_protocol":"quorum"
},
"port": "8000",
"volume": {
"type": "LOCALSSD",
"size": 120
},
"region": "sa-fb-1",
"replica_num": 3,
"configuration_id": "26f22545846040d1a02163a068b6b3a3pr14",
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 7
},
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"availability_zone": "az3.dc0,az3.dc0,az3.dc0",
"vpc_id": "aaefc937-c12e-449a-9907-604827337999",
"subnet_id": "ebeaece0-c16c-42aa-a546-0d42d0c68956",
"security_group_id": "290af3b6-289b-4014-a336-b98da9c4fa8e",
"charge_info": {
"charge_mode": "postPaid"
}
},
"job_id": "d7b73e60-4237-43d0-9007-097b7678495d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 20
云数据库 GaussDB
API 参考 4 API（推荐）
4.1.2 删除数据库实例
功能介绍
删除数据库实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14
● 参数说明
表 4-15 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项
目ID/名称。
instance_id 是 实例ID。
请求消息
无
响应消息
● 正常响应要素说明
表 4-16 要素说明
名称 参数类型 说明
job_id String 实例删除的任务id
● 正常响应样例：
{
"job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 21
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.3 查询数据库实例列表
功能介绍
根据指定条件查询实例列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/instances?
id={id}&name={name}&type={type}&datastore_type={datastore_type}&vpc_id
={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit}
● URI样例
– 查询所有实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/97b026aa9cc4417888c14c84a1ad9860/instances
– 根据指定条件查询实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/97b026aa9cc4417888c14c84a1ad9860/instances?
id=ed7cc6166ec24360a5ed5c5c9c2ed726in14&name=hy&type=Centralizat
ion_standard&datastore_type=GaussDB&vpc_id=19e5d45d-70fd-4a91-87e
9-
b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offs
et=0&limit=10
● 参数说明
表 4-17 参数说明
名称 参数类 是否 说明
型 必选
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 22
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类 是否 说明
型 必选
id String 否 实例ID。
“*”为系统保留字符，如果id是以“*”起
始，表示按照*后面的值模糊匹配，否则，按
照id精确匹配查询。不能只传入“*”。
name String 否 实例名称。
“*”为系统保留字符，如果name是以“*”
起始，表示按照*后面的值模糊匹配，否则，
按照name精确匹配查询。不能只传入“*”。
type String 否 按照实例类型查询。目前支持取值如下：
● Enterprise（区分大小写），对应分布式实
例（独立部署）（已废弃）。
● Centralization_standard（区分大小
写），对应主备版实例。
● Combined（区分大小写），对应分布式实
例（混合部署）。
datastore_ String 否 数据库类型，不区分大小写。
type GaussDB
vpc_id String 否 虚拟私有云ID，获取方法如下：。
● 方法1：登录虚拟私有云服务的控制台界
面，在虚拟私有云的详情页面查找VPC
ID。
● 方法2：获取方法请参见《虚拟私有云API
参考》中“查询VPC列表”的内容。
subnet_id String 否 子网的网络ID信息。
● 方法1：登录虚拟私有云服务的控制台界
面，单击VPC下的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚拟私有云
(VPC) 使用指南 》的API参考中“查询子
网列表”的内容。
offset Integer 否 索引位置，偏移量。从第一条数据偏移offset
条数据后开始查询，默认为0（偏移0条数
据，表示从第一条数据开始查询），必须为数
字，不能为负数。
limit Integer 否 查询记录数。默认为100，不能为负数，最小
值为1，最大值为100。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 23
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类 是否 说明
型 必选
charge_mo String 否 计费模式。
de 取值范围：
postPaid：后付费，即按需付费。
prePaid：预付费，即 包年/包月。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-18 参数说明
名称 参数类型 说明
instances Array of objects 实例信息。
详情请参见表4-19。
total_count Integer 总记录数。
表 4-19 instances 字段数据结构说明
名称 参数类型 说明
id String 实例ID。
name String 创建的实例名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 24
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
status String 实例状态。
取值：
值为“BUILD”，表示实例正在创建。
值为“ACTIVE”，表示实例正常。
值为“FAILED”，表示实例异常。
值为“MODIFYING”，表示实例正在
扩容磁盘或者变更规格。
值为“EXPANDING”，表示实例正在
扩容。
值为“REBOOTING”，表示实例正在
重启。
值为“UPGRADING”，表示实例正在
升级。
值为“RESTORING”，表示实例正在恢
复。
值为“SWITCHOVER”，表示实例正在
主备切换。
值为“MIGRATING”，表示实例正在
迁移。
值为“BACKING UP”，表示实例正在
进行备份。
值为“REBALANCING”，表示实例正
在进行主备分布均衡。
值为“UPGRADE TO BE
OBSERVED”，表示实例正在进行升级
待观察。
值为“STORAGE FULL”，表示实例磁
盘空间满。
值为”REPAIRING”，表示实例正在修
复。
private_ips List<String> 实例内网IP地址列表。分布式CN所在的
弹性云服务器创建成功后该值存在，主
备版DN所在的弹性云服务器创建成功
后该值存在，其他情况下为空字符串。
port Integer 数据库端口号。GaussDB数据库端口当
前只允许为8000。
type String 实例类型，取值为
"centralization_standard"，对应于主
备版实例。区分大小写。
ha Object 实例的高可用参数。
详情请参见表4-20。
replica_num Integer 实例副本数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 25
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
region String 实例所在区域。
datastore Object 数据库信息。
详情请参见表4-21。
created String 创建时间，格式为“yyyy-mm-dd
hh:mm:ss timezone”。
其中timezone是指时区。
说明：创建时该值为实例下发创建的时
间，创建完成后，该值为创建完成时
间。
updated String 更新时间，格式与“created”字段对应
格式完全相同。
说明：创建时返回值为空，数据库实例
创建成功后该值不为空。
db_user_name String 默认用户名。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
security_group_ String 安全组ID。
id
flavor_ref String 规格码。参考数据库实例规格中
GaussDB的“规格编码”列内容获取。
flavor_info Object 规格信息。
详情请参见表4-22
volume Object Volume信息。
详情请参见表4-23。
backup_strateg Object 备份策略。
y 详情请参见表4-24。
maintenance_w String 可维护时间窗，为UTC时间。
indow
nodes Array of objects 实例节点信息。
详情请参见表4-25。
enterprise_proje String 企业项目标签ID。0代表非企业项目。
ct_id
instance_mode String enterprise代表数据库版本为企业版。
time_zone String 时区。
charge_info Object 计费类型信息，支持按需。
详情请参见表4-26。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 26
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
kms_tde_key_id String kms秘钥ID。
kms_project_na String kms秘钥在某一region下的资源空间名
me 称。
表 4-20 ha 字段数据结构说明
名称 参数类型 说明
consistency String 事务一致性类型。取值为“strong”、
“eventual”，分别表示强一致性、最终
一致性。
replication_mo String 备机同步参数。
de 取值：非空。
GaussDB为 “sync”
说明
“sync”为同步模式。
consistency_pro String 副本一致性协议类型，取值范围：
tocol ● quorum：quorum模式是主备同步复
制机制，客户端发起事务后，必须要等
待对应的WAL日志复制到多个副本后，
主库才会响应给客户端，少数节点的宕
机不影响全局可用性，保证数据的一致
性。
● paxos：该模式解决了quorum模式下
日志复制过程中日志分叉的问题，提高
日志复制吞吐量，增加DN自仲裁能
力。
表 4-21 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎。
version String 数据库大版本，两位数。
complete_versi String 数据库小版本，三位数。
on
hotfix_versions String 数据库已升级的热补丁版本，当数据库热
补丁升级成功后，该值不为空。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 27
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-22 flavor_info 字段数据结构说明
名称 参数类型 说明
vcpu Integer cpu核数。
mem Integer 内存大小，单位GB。
表 4-23 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
size Integer 磁盘大小。
表 4-24 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内触
发。
当前时间指UTC时间。
keep_days Integer 已生成的备份文件可以保存的天数。
取值范围：1～732。
表 4-25 nodes 字段数据结构说明
名称 参数类型 说明
id String 节点ID。
name String 节点名称。
role String 节点类型，取值为“master”、
“slave”，分别对应于主节点、备节点。
status String 节点状态。
availability_zon String 可用区。
e
data_ip String 数据IP。
management_i String 管理IP。
p
bms_hs_ip String 高速网卡IP，bms实例特有的IP字段，用
于数据同步。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 28
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-26 charge_info 字段数据结构说明
名称 参数类型 说明
charge_mode String 计费模式。
postPaid：后付费，即按需付费。
● 正常响应样例
实例列表：
{
"instances": [
{
"id": "b331ed66cc3249f78bc20737308c01f4in14",
"status": "ACTIVE",
"name": "gauss-9e88",
"port": 8000,
"type": "Enterprise",
"ha": {
"consistency": "strong",
"replication_mode": "sync",
"consistency_protocol":"quorum"
},
"region": "eu-de",
"datastore": {
"type": "GaussDB",
"version": "2.7",
"complete_version": "2.7.2",
"hotfix_versions": "2.7.2.1,2.7.2.2"
},
"created": "2021-01-15 01:46:40 UTC",
"updated": "2021-01-15 02:05:03 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 120
},
"nodes": [
{
"id": "02ebf757aaf94074855f49cc6e0e4712no14",
"name": "gauss-9e88_gaussdbv5cn_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz",
"private_ip": "192.168.16.253"
},
{
"id": "0a87b8ecbfeb46aba1409cfc0f0d5c34no14",
"name": "gauss-9e88_gaussdbv5cn_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz",
"private_ip": "192.168.28.81"
},
{
"id": "2d9fec1ab3834936b074d63acf48b1f2no14",
"name": "gauss-9e88_gaussdbv5dn3_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 29
云数据库 GaussDB
API 参考 4 API（推荐）
{
"id": "48bb08a2d635435891ac0caa1c0bf2e3no14",
"name": "gauss-9e88_gaussdbv5dn1_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "5df830f652204827ada32f8bc28b107eno14",
"name": "gauss-9e88_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "8a97a246cee841b38c5b47290d4c9c38no14",
"name": "gauss-9e88_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz",
"private_ip": "192.168.27.52"
},
{
"id": "8c1a3f8eecca4d9e9974a868bb6dd942no14",
"name": "gauss-9e88_gaussdbv5dn2_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "9bd0c80b8a684cc9bd7d99dd5adffb07no14",
"name": "gauss-9e88_gaussdbv5dn3_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "9e2a3cd541e249d4af5aa57c5d3a7f39no14",
"name": "gauss-9e88_gaussdbv5dn1_2",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b046d28989ec4ae5a1a9ab20fe65f248no14",
"name": "gauss-9e88_gaussdbv5dn2_2",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b614cc12fd3742dbb230245f88a7bf00no14",
"name": "gauss-9e88_gaussdbv5dn3_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "caba8e88c3c84ae58202f1f589490611no14",
"name": "gauss-9e88_gaussdbv5dn2_1",
"role": "slave",
"status": "ACTIVE",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 30
云数据库 GaussDB
API 参考 4 API（推荐）
"availability_zone": "az2xahz"
}
],
"private_ips": [
"192.168.16.253 / 192.168.28.81 / 192.168.27.52"
],
"replica_num": 3,
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "prePaid"
},
"backup_strategy": {
"start_time": "19:00-20:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab",
"enterprise_project_id": "6e76681b-a2f5-4c5f-97c5-ba4fd3c0dfb2",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
},
{
"id": "226b4afcfcc84c86bf1b9cb345d3b00fin14",
"status": "ACTIVE",
"name": "UTS-gauss-ad53-2C3D",
"port": 8000,
"type": "Enterprise",
"ha": {
"consistency": "strong",
"replication_mode": "sync",
"consistency_protocol":"paxos"
},
"region": "cn-xianhz-1",
"datastore": {
"type": "GaussDB",
"version": "2.7",
"complete_version": "2.7.2",
"hotfix_versions": "2.7.2.1,2.7.2.2"
},
"created": "2021-01-08 09:18:27 UTC",
"updated": "2021-01-14 13:25:03 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 120
},
"nodes": [
{
"id": "07538a1def584cee99e2a5685eeab36ano14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 31
云数据库 GaussDB
API 参考 4 API（推荐）
},
{
"id": "21f41baba1e2454f82331b7cb5aeabe5no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "2909771a3b3e4e3998f9388e77d22391no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "2bd9a90a5da242a6b0743a7f597f6106no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "77092f1dadb74d3ea13d28269cdd3590no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "a46bfaa6d5a24355a60fce7432b964cano14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "aa5277736f3844e2a7adeb9de529e2b1no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b1d798e4ea7344dfa95032984bc6cfd7no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz",
"private_ip": "192.168.29.231"
},
{
"id": "b9a46540186f4c0781eabaa2a79594cbno14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "d283813030364060ab64371d50294977no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_0",
"role": "slave",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 32
云数据库 GaussDB
API 参考 4 API（推荐）
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "eb7bce29b2284cd290405eaddc1b1a1eno14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_0",
"role": "master",
"status": "FAILED",
"availability_zone": "az2xahz",
"private_ip": "192.168.30.44",
"public_ip": "10.154.217.248"
}
],
"private_ips": [
"192.168.29.231 / 192.168.30.44"
],
"public_ips": [
"10.154.217.248"
],
"replica_num": 3,
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "prePaid"
},
"backup_strategy": {
"start_time": "18:00-19:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
}
],
"total_count": 2
}
● 实例详情：
{
"instances": [
{
"id": "034fbefcf4bf4bd99d72cc396b8a32bein14",
"status": "ACTIVE",
"name": "gauss-ba01-llz",
"port": 8000,
"type": "centralization_standard",
"ha": {
"consistency": "strong",
"replication_mode": "sync",
"consistency_protocol":"quorum"
},
"region": "sa-fb-2",
"datastore": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 33
云数据库 GaussDB
API 参考 4 API（推荐）
"type": "GaussDB",
"version": "2.6"
},
"created": "2022-12-23 09:48:34 UTC",
"updated": "2022-12-25 14:10:31 UTC",
"volume": {
"type": "LOCALSSD",
"size": 160
},
"nodes": [
{
"id": "89e15cd8da28410590cd0257cc1012ffno14",
"name": "gauss-ba01-llz_root_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "mcsAZ3.dc2"
},
{
"id": "ed9a727be38545c5a2d1471f6d11ee77no14",
"name": "gauss-ba01-llz_root_2",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "mcsAZ3.dc2"
},
{
"id": "fc1f2540f0484b10adedd7ce6ae3eac4no14",
"name": "gauss-ba01-llz_root_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "mcsAZ3.dc2"
}
],
"private_ips": [
"172.168.1.163 / 172.168.1.10 / 172.168.1.22"
],
"replica_num": 3,
"db_user_name": "root",
"vpc_id": "4aed8010-b0bb-4e48-96c2-fbbbcaec9fa8",
"subnet_id": "44da393a-9813-4838-9bd8-c9e77443aa22",
"security_group_id": "0727106a-9cad-420d-9b1b-85953785bf4f",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"flavor_info": {
"vcpu": 8,
"mem": 64
},
"charge_info": {
"charge_mode": "postPaid"
},
"backup_strategy": {
"start_time": "19:00-20:00",
"keep_days": 30
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode": "enterprise"
}
],
"total_count": 1
}
● 异常响应
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 34
云数据库 GaussDB
API 参考 4 API（推荐）
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.4 同城切换 AZ
功能介绍
切换主DN组至对应AZ。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
注意事项
切换完成后，可能会导致集群主备分布不均衡，如果需要将集群重新切回均衡状态，
可以参考实例主备状态重置，将集群主备状态切回。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
switch-az
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/switch-az
● 参数说明
表 4-27 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 35
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-28 参数说明
名称 是否必选 参数类型 说明
availability_zone 是 String 需要将主DN切换到的AZ。
● 请求样例
{
"availability_zone": "az3.dc0"
}
响应消息
● 正常响应要素说明
表 4-29 要素说明
名称 参数类型 说明
job_id String 同城切换AZ的任务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.5 分片节点主备切换
功能介绍
支持用户对单个或多个DN分片做主备切换，同一分组内只能指定一个新的备节点进行
升主操作。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 36
云数据库 GaussDB
API 参考 4 API（推荐）
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
switch-shard
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/switch-shard
● 参数说明
表 4-30 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-31 参数说明
名称 是否必选 参数类型 说明
shards 是 Array 节点列表，支持对单个或者
多个DN分片做主备切换。
节点信息为将要升主的备
DN分片对应的节点
id(node_id)和组件
id(component_id)。具体请
参考表4-32。
表 4-32 shards 参数说明
名称 是否必选 参数类型 说明
node_id 是 String 将要升主的备DN的节点
Id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 37
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
component_id 是 String 将要升主的备DN的组件
Id。最大长度7个字符，不
能为null或者空字符串，不
能为空格，校验和使用之前
会自动过滤掉前后空格。至
少包含大写字母（A-Z），
小写字母（a-z），数字
（0-9），非字母数字字符
（限定为_）四类字符中的
三类字符。组件id通过查询
实例的组件列表获取。
请求示例
切换多个DN分片的主备。
{
"shards": [
{
"node_id": "0bc478b4d132494a8f7b804da521b4b2no14",
"component_id": "dn_6001"
},
{
"node_id": "53dee94c50574d36a0060db0a6b644f6no14",
"component_id": "dn_6004"
}
]
}
响应消息
● 正常响应要素说明
表 4-33 要素说明
名称 参数类型 说明
job_id String 分片节点主备切换的任
务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 38
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.6 查询实例的组件列表
功能介绍
查询实例的所有组件信息。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
components
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dd93e98e103b4fc4b5a978a6bd6f03a9in14/components
● 参数说明
表 4-34 参数说明
名称 参 是否必选 说明
数
类
型
project_id stri 是 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
instance_id stri 是 实例ID。
ng
limit int 否 查询记录数。默认为100，不能为负
ege 数，最小值为1，最大值为100。例如该
r 参数设定为10，则查询结果最多只显示
10条记录。
offset int 否 索引位置，偏移量。从第一条数据偏移
ege offset条数据后开始查询，默认为0（偏
r 移0条数据，表示从第一条数据开始查
询），必须为数字，不能为负数。例
如：该参数指定为0，limit指定为10，
则只展示第1-10条数据。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 39
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参 是否必选 说明
数
类
型
component_ty stri 否 组件类型，过滤拿到需要的组件类型的
pe ng 组件信息，默认为ALL。传参数会查询
对应组件信息， "ALL": 查询所有组件类
型。 "CM": 查询CMS组件类型。枚举
值：
● ALL
● CN
● DN
● CM
● GTM
● ETCD
availability_zo stri 否 主组件所在可用区编号，筛选符合条件
ne_id ng 的组件，默认为ALL，查询实例所有可
用区上的节点的组件信息。 当调用接口
传入可用区编号时： 相对于DN组件，
会查询出的DN分片中的主组件在该可用
区上的这个分片的所有副本的组件信
息。 相对于CN组件，CN组件没有主备
关系，会查询出该可用区上的CN组件信
息。 相对于其他组件，会查询该可用区
上有没有某个组件类型的主组件，有则
会返回该组件类型的所有组件信息，没
有则不返回该组件类型的信息。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-35 要素说明
名称 参数类型 说明
nodes Array of objects 组件详情。
详情请参见表4-36。
total_count integer 总记录数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 40
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-36 nodes 说明
名称 参数类型 说明
id string 节点id。
components Array of 该实例节点下的组件信息列表，详情请
objects 参见查询实例的组件列表。
name string 节点名字。
availability_zone_i string 节点所在可用区编码。
d
description string 可用区描述信息。
status string 节点状态。
表 4-37 components 说明
名称 参数类型 说明
id string 组件id。
GTM：Global Transaction Manager，
全局事务管理器。用于管理事务状态的
部件。
CMS：Cluster Management Server，
集群管理组件。是用于管理集群状态的
部件。
DN：Data Node，和CN对应的概念。
负责实际执行表数据的存储、查询操
作。
CN：Coordinator Node，负责数据库
系统元数据存储、查询任务的分解和部
分执行，以及将DN中查询结果汇聚在
一起。
ETCD：Editable Text Configuration
Daemon，分布式键值存储系统，用于
共享配置和服务发现（服务注册和查
找）。
role string 节点角色。
master：组件所在节点为主节点。
slave：组件所在节点为备节点。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 41
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
status string 组件状态。
Primary：该组件为主。
Normal：该组件状态正常。
Down：该组件处于宕机状态。
Standby：该组件为备。
StateFollower：该ETCD为备。
StateLeader：该ETCD为主。
StateCandidate：该ETCD为仲裁。
distributed_id string 分组ID，只有DN组件有分组DN，用于
区分是否是同一个分片下的组件。其他
组件为空字符串。
type string 节点类型，包括：DN, CN, GTM, CM,
ETCD。
detail string 详情。
● 正常响应样例
{
"nodes": [
{
"components": [
{
"id": "cm_1",
"role": "master",
"status": "Primary",
"distributed_id": ""，
"type" : "CM",
"detail" : ""
},
{
"id": "etcd_7001",
"role": "master",
"status": "StateLeader",
"distributed_id": ""，
"type" : "ETCD",
"detail" : ""
},
{
"id": "dn_6001",
"role": "master",
"status": "Primary",
"distributed_id": "60011"，
"type" : "DN",
"detail" : "Normal"
}
],
"id": "7d19f72f8f514564bd92962a6fbddb7dno14",
"name": "gauss-9e1a_root_0",
"availability_zone_id": "cn-southwest-244a",
"description": "az1",
"status": "normal"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 42
云数据库 GaussDB
API 参考 4 API（推荐）
{
"components": [
{
"id": "cm_3",
"role": "slave",
"status": "Standby",
"distributed_id": ""，
"type" : "CM",
"detail" : ""
},
{
"id": "etcd_7003",
"role": "slave",
"status": "StateFollower",
"distributed_id": ""，
"type" : "ETCD",
"detail" : ""
},
{
"id": "dn_6003",
"role": "slave",
"status": "Standby",
"distributed_id": "60011"，
"type" : "DN",
"detail" : "Normal"
}
],
"id": "aafc2e14234d4c9eadb481fb0a09a865no14",
"name": "gauss-9e1a_root_2",
"availability_zone_id": "cn-southwest-244a",
"description": "az1",
"status": "normal"
},
{
"components": [
{
"id": "cm_2",
"role": "slave",
"status": "Standby",
"distributed_id": ""，
"type" : "CM",
"detail" : ""
},
{
"id": "etcd_7002",
"role": "slave",
"status": "StateFollower",
"distributed_id": ""，
"type" : "ETCD",
"detail" : ""
},
{
"id": "dn_6002",
"role": "slave",
"status": "Standby",
"distributed_id": "60011"，
"type" : "DN",
"detail" : "Normal"
}
],
"id": "d6c6c6e6b48c41d79d99d7240751d744no14",
"name": "gauss-9e1a_root_1",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 43
云数据库 GaussDB
API 参考 4 API（推荐）
"availability_zone_id": "cn-southwest-244a",
"description": "az1",
"status": "normal"
}
],
"total_count": 3
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.7 实例主备状态重置
功能介绍
将数据库实例恢复为初始配置的主备状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 实例在创建、变更规格、异常等状态下不能执行该操作。
● 该功能不支持1.x版本的主备版实例。
URI
● URI格式
PUT https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
rebalance
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/rebalance
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 44
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-38 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
请求消息
无。
响应消息
● 正常响应要素说明
响应参数
表 4-39 要素说明
参数 参数类型 描述
job_id String 任务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 45
云数据库 GaussDB
API 参考 4 API（推荐）
4.1.8 查询实例主备平衡状态
功能介绍
查询实例是否发生过主备切换而导致主机负载不均衡。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
balance
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/balance
● 参数说明
表 4-40 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-41 要素说明
名称 参数类型 说明
balanced boolean 平衡状态。显示是否有
集群实例发生过主备切
换而导致主机负载不均
衡。
● 返回"true"，均衡。
● 返回"false"，不均
衡。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 46
云数据库 GaussDB
API 参考 4 API（推荐）
● 正常响应样例
{
"balanced": true
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.9 查询实例扩展信息
功能介绍
查询实例扩展信息。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
extend-info?key={key}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/extend-info?key=BackupSet
● 参数说明
表 4-42 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 47
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 说明
key 是 实例扩展信息key。
枚举值：
● BackupSet：备份集信息。
● XbsaRoute：Xbsa协议下对应的路由
信息。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-43 要素说明
名称 参数类型 说明
key String 实例扩展key，枚举值：
● “BackupSet”，备
份集信息。
● “XbsaRoute”，
Xbsa协议下对应的路
由信息。
value String 实例扩展信息value。
● 正常响应样例
{
"key" : "BackupSet",
"value" : "BackupSetExamples"
}
{
"key" : "XbsaRoute",
"value" : "{\"ip\":\"192.168.1.1\",\"port\":\"8009\"}"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 48
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.1.10 设置实例扩展信息
功能介绍
设置实例扩展信息。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
PUT https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
extend-info
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/extend-info
● 参数说明
表 4-44 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-45 参数说明
名称 是否必选 参数类型 说明
key 是 String 实例扩展key，枚举值：
● “BackupSet”，备份集
信息。
● “XbsaRoute”，Xbsa
协议下对应的路由信
息。
value 是 String 实例扩展信息。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 49
云数据库 GaussDB
API 参考 4 API（推荐）
● 请求示例
{
"key" : "BackupSet",
"value" : "BackupSetExamples"
}
{
"key" : "XbsaRoute",
"value" : "{\"ip\":\"192.168.1.1\",\"port\":\"8009\"}"
}
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.11 启动实例/节点
功能介绍
启动实例/节点。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{endpoint}/v3/{project_id}/instances/{instance_id}/db-startup
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3/
cc94568cb5a54e4a8ab5dff95e64a5e0br14/instances/
d8e6ca5a624745bcb546a227aa3ae1cfin14/db-startup
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 50
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-46 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-47 参数说明
名称 是否必选 参数类型 说明
X-Auth-Token 是 String 用户Token
X-Language 否 String 语言。
缺省值：en-us
枚举值：
● zh-cn
● en-us
表 4-48 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_ids 是 Array of 需要启动的节点的ID，取值
strings 不能为null，如果为空列
表，则启动整个实例
● 请求示例
{
"node_ids":
["187ff420e15c467eaaef226154eb1578no14","4ed9cbb0d61144e0802a82c0ab0e1de5no14"]
}
响应消息
● 正常响应要素说明
表 4-49 参数说明
参数 参数类型 描述
job_id String 启动实例或节点的异步任务ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 51
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-50 参数说明
参数 参数类型 描述
error_code String 错误码。
error_msg String 错误消息。
● 响应示例
{
"job_id" : "bf26cf3c-d046-4080-bb45-f114be7afa5f"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.12 停止实例/节点
功能介绍
停止数据库,同时支持节点级别的停止操作。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-stop
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054e292c9880d4992f02c0196d3ea468/instances/
d8e6ca5a624745bcb546a227aa3ae1cfin14/db-stop
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 52
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-51 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 需要停止的实例的ID。
请求消息
● 参数说明
表 4-52 参数说明
名称 是否必选 参数类型 说明
X-Auth-Token 是 String 用户Token
X-Language 否 String 语言。
缺省值：en-us
枚举值：
● zh-cn
● en-us
表 4-53 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_ids 是 Array of 需要停止的节点的ID，取值
strings 不能为null，如果为空列
表，则停止整个实例。
● 请求示例
{
"node_ids":
["187ff420e15c467eaaef226154eb1578no14","4ed9cbb0d61144e0802a82c0ab0e1de5no14"]
}
响应消息
● 正常响应要素说明
表 4-54 参数说明
参数 参数类型 描述
job_id String 停止实例或节点的异步任务ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 53
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-55 参数说明
参数 参数类型 描述
error_code String 错误码。
error_msg String 错误消息。
● 响应示例
{
"job_id" : "bf26cf3c-d046-4080-bb45-f114be7afa5f"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.13 切换透明加密
功能介绍
切换实例透明加密状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
PUT https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/kms-tde/
switch
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054e292c9880d4992f02c0196d3ea468/instances/
d8e6ca5a624745bcb546a227aa3ae1cfin14/kms-tde/switch
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 54
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-56 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例的ID。
请求消息
● 参数说明
表 4-57 请求 Body 参数说明
名称 是否必选 参数类型 说明
kms_tde_key_id 是 String KMS主密钥ID。
kms_tde_status 是 String 需要切换的状态。
枚举值：
● on：开启
kms_project_na 是 String GaussDB使用透明加密的
me KMS主密钥ID所在所在资源
空间名称。
获取方法请参见获取项目
ID/名称
● 请求示例
{
"kms_tde_key_id":"ca0da073-20a4-451d-812d-67f35d4d91f1",
"kms_tde_status":"on",
"kms_project_name":"kms_project_name"
}
响应消息
● 正常响应要素说明
表 4-58 参数说明
参数 参数类型 描述
job_id String 异步任务ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 55
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-59 参数说明
参数 参数类型 描述
error_code String 错误码。
error_msg String 错误消息。
● 响应示例
{
"job_id" : "bf26cf3c-d046-4080-bb45-f114be7afa5f"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.14 结束空闲会话
功能介绍
查杀空闲会话。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 仅支持包含有CN或DN（主、备）组件的节点。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/kill-free-
session
● URI样例
https://{Endpoint}/gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/
instances/cc6fd964d93f4003851dfc29d57d30a5in14/kill-free-session
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 56
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-60 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例的ID。
请求消息
● 参数说明
表 4-61 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_id 是 String 节点ID，仅支持包含有CN
或DN（主、备）组件的节
点。
component_id 是 String 组件ID，仅支持包含有CN
或DN（主、备）组件ID，
且需要是node_id参数上的
组件。
● 请求示例
{
"node_id": "52c25e148a4a48c293b66ca95565719cno14",
"component_id": "cn_5001"
}
响应消息
● 正常响应要素说明
表 4-62 参数说明
参数 参数类型 描述
success Boolean 是否成功。
● 响应示例
{
"success" : true
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 57
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.15 结束会话
功能介绍
查杀指定会话列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 仅支持包含有CN或DN（主、备）组件的节点。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/kill-
session
● URI样例
https://{Endpoint}/gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/
instances/cc6fd964d93f4003851dfc29d57d30a5in14/kill-session
● 参数说明
表 4-63 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例的ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 58
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-64 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_id 是 String 节点ID，仅支持包含有CN
或DN（主、备）组件的节
点。
component_id 是 String 组件ID，仅支持包含有CN
或DN（主、备）组件ID，
且需要是node_id参数上的
组件。
session_ids 是 Array of 查杀指定会话ID列表
strings
● 请求示例
{
"node_id": "52c25e148a4a48c293b66ca95565719cno14",
"component_id": "cn_5001",
"session_ids": ["10180"]
}
响应消息
● 正常响应要素说明
表 4-65 参数说明
参数 参数类型 描述
session_ids Array of 成功查杀指定会话ID列表。
strings
success Boolean 是否成功。
● 响应示例
{
"session_ids" : [ 10180 ],
"success" : true
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 59
云数据库 GaussDB
API 参考 4 API（推荐）
4.1.16 获取实时会话
功能介绍
查询数据库实例节点的实时会话列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 仅支持包含有CN或DN（主、备）组件的节点。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/real-time-
session
● URI样例
https://{Endpoint}/gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/
instances/cc6fd964d93f4003851dfc29d57d30a5in14/real-time-session
● 参数说明
表 4-66 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例的ID。
请求消息
● 参数说明
表 4-67 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_id 是 String 节点ID，仅支持包含有CN
或DN（主、备）组件的节
点。
component_id 是 String 组件ID，仅支持包含有CN
或DN（主、备）组件ID，
且需要是node_id参数上的
组件。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 60
云数据库 GaussDB
API 参考 4 API（推荐）
● 请求示例
{
"node_id": "52c25e148a4a48c293b66ca95565719cno14",
"component_id": "cn_5001"
}
响应消息
● 正常响应要素说明
表 4-68 响应 Body 参数
参数 参数类型 描述
sessions 表4-69 数据库实例的实时会话列表。
表 4-69 RealTimeSession 参数说明
参数 参数类型 描述
session_id String 会话ID。
pid String 线程ID。
unique_sql_id String SQL ID。
database_name String 数据库。
client_ip String 客户端IP。
user_name String 用户名。
wait String 是否等待。
block_session String 阻塞会话。
wait_event String 等待事件。
state String 状态。
query_runtime String 语句执行时长。
query String SQL文本。
back_end_start Long 会话开始时间。
transaction_start Long 事务开始时间。
query_start Long 语句开始时间。
application_name String 应用名称。
● 响应示例
{
"sessions" : {
"session_id" : "725",
"pid" : "140623987341056",
"unique_sql_id" : "3545025713",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 61
云数据库 GaussDB
API 参考 4 API（推荐）
"database_name" : "postgres",
"client_ip" : "23.100.74.131",
"user_name" : "root",
"wait" : "f",
"block_session" : "",
"wait_event" : "none",
"state" : "active",
"query_runtime" : "00:00:22.641774",
"query" : "select pg_sleep(100);",
"back_end_start" : 1690448618645,
"transaction_start" : 1690448618689,
"query_start" : 1690448618689,
"application_name" : "gsql"
}
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2 参数配置
4.2.1 获取参数模板列表
功能介绍
获取参数模板列表，包括所有数据库的默认参数模板和用户创建的参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/configurations?
offset={offset}&limit={limit}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/054ea741f700d4a32f1bc00f5c80dd4c/configurations?offset=1&limit=3
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 62
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-70 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。例如：该参数指定为0，
limit指定为10，则只展示第
1-10条数据。
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。例如该参数设定为
10，则查询结果最多只显示10
条记录。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-71 参数说明
参数 参数类型 描述
configuration Array of 参数模板信息，具体参数请参考表4-72。
s objects
count Integer 总记录数。
表 4-72 configurations 字段数据结构说明
参数 参数类型 描述
id String 参数组ID。
name String 参数组名称。
description String 参数组描述。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 63
云数据库 GaussDB
API 参考 4 API（推荐）
参数 参数类型 描述
datastore_ve String 引擎版本。
rsion
datastore_na String 引擎名称。
me
ha_mode String 实例类型。
created String 创建时间，格式为"yyyy-MM-dd
HH:mm:ss"。
updated String 更新时间，格式为"yyyy-MM-dd
HH:mm:ss"。
user_defined Boolean 是否是用户自定义参数模板：
● false，表示为系统默认参数模板。
● true，表示为用户自定义参数模板。
● 正常响应样例
{
"count": 3,
"configurations": [
{
"id": "b000d7c91f1749da87315700793a11d4pr14",
"name": "Default-GaussDB-EE-1.0-Dist-Combined (4 replicas)",
"description": "Default parameter template for GaussDB-Enterprise Edition-1.0-
Distributed-combined (4 replicas)",
"created": "2022-03-23 07:20:11",
"updated": "2022-03-23 07:20:11",
"datastore_version": "1.0",
"datastore_name": "GaussDB",
"ha_mode": "combined",
"user_defined": false
},
{
"id": "8d99f260ea1b4493a1b349e7abce5c09pr14",
"name": "Default-Finance-Edition-GaussDB-1.3-Combined",
"description": "Default parameter template for Finance Edition GaussDB 1.3-
Combined",
"created": "2022-03-23 07:20:11",
"updated": "2022-03-23 07:20:11",
"datastore_version": "1.1",
"datastore_name": "GaussDB",
"ha_mode": "combined",
"user_defined": false
},
{
"id": "0f44b65521a8414d8b8811df810d94ccpr14",
"name": "Default-Finance-Disaster-GaussDB-1.3-Combined",
"description": "Default parameter template for Finance Disaster GaussDB 1.3-
Combined",
"created": "2022-03-23 07:20:11",
"updated": "2022-03-23 07:20:11",
"datastore_version": "1.2",
"datastore_name": "GaussDB",
"ha_mode": "combined",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 64
云数据库 GaussDB
API 参考 4 API（推荐）
"user_defined": false
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.2 获取指定实例的参数
功能介绍
获取指定实例的参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
configurations
● URI样例
https://gaussdb-api.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/054ea741f700d4a32f1bc00f5c80dd4c/instances/dsfae23fsfdsae3435in14/
configurations
● 参数说明
表 4-73 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 65
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
无。
响应消息
● 正常响应要素说明
表 4-74 参数说明
参数 参数类型 描述
datastore_ve String 引擎版本。
rsion
datastore_na String 引擎名称。
me
created String 创建时间，格式为"yyyy-MM-dd
HH:mm:ss"。
updated String 更新时间，格式为"yyyy-MM-ddHH:mm:ss"。
configuration Array of 参数对象，用户基于默认参数模板自定义的参
_parameters objects 数配置，具体请参考表4-75。
表 4-75 configuration_parameters 字段数据结构说明
参数 参数类型 描述
name String 参数名称。
value String 参数值。
restart_requir Boolean 修改该参数是否需要重启实例。
ed
value_range String 参数取值范围。
type String 参数类型，取值为“string”、“integer”、
“boolean”、“list”或“float”之一。
枚举值：
● string
● integer
● boolean
● list
● float
description String 参数描述。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 66
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息示例
● 正常响应要素说明
{
"created": "2022-04-11 10:46:59",
"updated": "2022-04-11 10:46:59",
"datastore_version": "2.0",
"datastore_name": "GaussDB",
"configuration_parameters": [
{
"name": "audit_system_object",
"value": "12295",
"type": "integer",
"description": "Determines whether to audit the CREATE, DROP, and ALTER
operations on GaussDB Kernel database objects. GaussDB Kernel database objects include
databases, users, schemas, and tables. You can change the parameter value to audit only
the operations on required database objects. During a forcible primary/standby failover,
set audit_system_object to the maximum value and audit all DDL objects. If the parameter
value is incorrectly changed, DDL audit logs will be lost. Contact customer service
personnel to change it.",
"restart_required": false,
"value_range": "0-2097151"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.3 修改指定实例的参数
功能介绍
修改指定实例的参数模板参数。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
修改的参数必须在指定数据库版本的默认参数范围内。
URI
● URI格式
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 67
云数据库 GaussDB
API 参考 4 API（推荐）
PUT https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
configurations
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/configurations
● 参数说明
表 4-76 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-77 参数说明
名称 是否必选 参数类型 说明
values 是 Map<String,St 参数值对象，用户基于默认
ring> 参数模板自定义的参数值。
填写示例：对于
"failed_login_attempts":"4
"，其中
"failed_login_attempts"就
是需要修改的参数名，"4"
就是需要将参数修改的值。
请求示例
● 修改实例的参数failed_login_attempts的值为4。不需要重启。
{
"values": {
"failed_login_attempts": "4"
}
}
● 修改实例的参数track_activity_query_size的值为2048，修改参数
max_replication_slots的值为25。需要重启。
{
"values": {
"track_activity_query_size": "2048",
"max_replication_slots": "30"
}
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 68
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-78 要素说明
名称 参数类型 说明
restart_required Boolean 实例是否需要重启。
● “true”需要重启。
● “false”不需要重
启。
● 正常响应样例
– 不需要重启
{
"restart_required": false
}
– 需要重启
{
"restart_required": true
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.4 创建参数模板
功能介绍
创建参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/configurations
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/configurations
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 69
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-79 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
请求消息
● 参数说明
表 4-80 参数说明
名称 是否必选 参数类型 说明
name 是 String 参数模板名称。 取值范
围：长度1到64位之间，区
分大小写字母，可包含字
母、数字、中划线、下划线
或句点，不能包含其他特殊
字符。
description 否 String 参数模板描述，默认为空。
取值范围：长度超过256自
动截取，不能包含回车>!
<"&'=等特殊字符。
parameter_value 否 Map<String,St 参数名和参数值映射关系。
s ring> 用户可以基于默认参数模板
的参数，自定义参数值。
datastore 是 object 数据库引擎信息。可通过
【查询引擎列表】接口查
询。详情请参见表4-81。
表 4-81 datastore 参数说明
名称 是否必选 参数类型 说明
engine_version 是 String 数据库版本。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 70
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
instance_mode 是 String 部署形态。
枚举值：
● ha：主备版
● combined：分布式版
金融版（标准型）
● combined_hcs2：分布
式版 企业版
● combined_hcs3：分布
式版 金融版(标准型)
● combined_hcs4：分布
式版 金融版（数据计算
型，容灾主）
● combined_hcs5：分布
式版 金融版（数据计算
型，容灾备）
请求示例
● 创建一个2.3版本，主备版部署形态的参数模板。
{
"name": "paramTemplate",
"description": "",
"parameter_values": {
"audit_system_object": "12294"
},
"datastore": {
"engine_version": "2.3",
"instance_mode": "ha"
}
}
响应消息
● 正常响应要素说明
表 4-82 参数说明
参数 参数类型 描述
id String 参数模板ID。
name String 参数模板名称。
created_at String 创建时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。 其中，T指某个时间的开
始；Z指时区偏移量，例如北京时间偏移显示
为+0800。
● 正常响应样例
{
"id" : "137eeaf0cc884ca4adffa9ebd101c115pr14",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 71
云数据库 GaussDB
API 参考 4 API（推荐）
"name" : "paramTemplate-del",
"created_at" : "2022-08-09T03:06:52+0800"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.5 删除参数模板
功能介绍
删除参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14
● 参数说明
表 4-83 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
请求消息
无。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 72
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.6 查询参数模板详情
功能介绍
查询参数模板详情，根据参数模板ID获取指定参数模板详情。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14
● 参数说明
表 4-84 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 73
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
无。
响应消息
● 正常响应要素说明
表 4-85 参数说明
参数 参数类型 描述
id String 参数模板ID。
name String 参数模板名称。
description String 参数模板描述。
engine_versi String 引擎版本。
on
instance_mo String 部署形态。
de 枚举值：
● ha：主备版
● combined：分布式版 金融版（标准型）
● combined_hcs2：分布式版 企业版
● combined_hcs3：分布式版 金融版(标准
型)
● combined_hcs4：分布式版 金融版（数据
计算型，容灾主）
● combined_hcs5：分布式版 金融版（数据
计算型，容灾备）
created_at String 创建时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量，
例如北京时间偏移显示为+0800。
updated_at String 修改时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量，
例如北京时间偏移显示为+0800。
configuration Array of 参数详情，具体请参考 表
_parameters objects configuration_parameters字段数据结构说
明。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 74
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-86 configuration_parameters 字段数据结构说明
参数 参数类型 描述
name String 特定参数名称。
value String 特定参数值。
need_restart Boolean 参数是否需要重启。
- 取值为"true"，需要重启。
- 取值为"false"，不需要重启。
readonly Boolean 该参数是否只读。
true：只读
false：可编辑
value_range String 参数取值范围。
data_type String 参数类型，取值为“string”、“integer”、
“boolean”、“list”或“float”之一。
description String 参数描述。
● 正常响应样例
{
"id": "3ca44134a16d4bbab8eb701e025b19f7pr14",
"name": "GaussDB_2b87a799-515",
"description": "ParamGroup for instance.",
"engine_version": "2.3",
"instance_mode": "ha",
"created_at": "2022-08-05T08:15:07+0800",
"updated_at": "2022-08-09T03:06:52+0800",
"configuration_parameters": [
{
"name": "audit_system_object",
"value": "12294",
"need_restart": false,
"readonly": false,
"value_range": "1-65536",
"data_type": "integer",
"description": "该参数决定是否对GaussDB Kernel数据库对象的CREATE、
DROP、ALTER操作进行审计。GaussDB Kernel数据库对象包括DATABASE、USER、schema、
TABLE等。通过修改该配置参数的值，可以只审计需要的数据库对象的操作，在主备强制选主
场景建议audit_system_object取最大值，所有DDL对象全部审计，不当修改该参数会导致丢失
DDL审计日志，请在客服人员指导下进行修改。"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 75
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.7 复制参数模板
功能介绍
复制参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
copy
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/copy
● 参数说明
表 4-87 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 被复制的参数模板ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 76
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-88 参数说明
名称 是否必选 参数类型 说明
name 是 String 复制后的参数模板名称。取
值范围：长度1到64位之
间，区分大小写字母，可包
含字母、数字、中划线、下
划线或句点，不能包含其他
特殊字符。
description 否 String 参数模板描述，默认为空。
取值范围：长度不能超过
256，不能包含回车>!<"&'=
等特殊字符。
请求示例
复制一个参数模板
{
"name" : "paramTemplate-1233",
"description" : "描述"
}
响应消息
● 正常响应要素说明
表 4-89 参数说明
参数 参数类型 描述
config_id String 复制后的参数模板ID。
● 正常响应样例
{
"config_id" : "3ca44134a16d4bbab8eb701e025b19f7pr14"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 77
云数据库 GaussDB
API 参考 4 API（推荐）
4.2.8 重置参数组
功能介绍
重置参数组。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
仅自定义模版才可以重置。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
reset
● URI样例
https://gaussdb.sa-
fb-2.hcsglobal.com/v3/599628f2665841b2a66fa2780fadc025/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/reset
● 参数说明
表 4-90 参数说明
名称 参数类 是否 说明
型 必选
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
config_id String 是 参数模板ID。
请求消息
无。
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 78
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.9 比较两个参数组模板之间的差异
功能介绍
获取两个参数配置模板的差异列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/configurations/comparison
● URI样例
https://gaussdb.sa-
fb-2.hcsglobal.com/v3/0483b6b16e954cb88930a360d2c4e663/configurations/
comparison
● 参数说明
表 4-91 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
请求消息
● 参数说明
表 4-92 参数说明
名称 是否必选 参数类型 说明
source_id 是 String 需要进行比较的参数组模板
ID。
target_id 是 String 需要进行比较的参数组模板
ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 79
云数据库 GaussDB
API 参考 4 API（推荐）
请求示例
查询两个参数组模板的差异列表。
{
"source_id" : "3e9f722f27c9477089bdf576b33f9d8epr14",
"target_id" : "a51fcdde022a4ea8a016a3c4671644f4pr14"
}
响应消息
● 正常响应要素说明
表 4-93 参数说明
参数 参数类型 描述
differences Array of 参数组之间的差异集合。
objects 详情请参见表 differences字段数据结构说明
表 4-94 differences 字段数据结构说明
参数 参数类型 描述
name String 参数名称。
source_value String 比较参数组的参数值。
target_value String 目标参数组的参数值。
● 正常响应样例
{
"differences" : [ {
"name" : "audit_system_object",
"source_value" : "12289",
"target_value" : "12295"
} ]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 80
云数据库 GaussDB
API 参考 4 API（推荐）
4.2.10 查询可应用实例列表
功能介绍
查询可应用当前参数组模板的实例列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
applicable-instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/applicable-instances
● 参数说明
表 4-95 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。例如：该参数指定为0，
limit指定为10，则只展示第
1-10条数据。
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。例如该参数设定为
10，则查询结果最多只显示10
条记录。
请求消息
无。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 81
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-96 参数说明
参数 参数类型 描述
instances Array of 参数模板信息，具体参数请参考表4-97。
objects
total_count Integer 总记录数。
表 4-97 instances 字段数据结构说明
参数 参数类型 描述
instance_id String 实例ID。
instance_na String 实例名称。
me
● 正常响应样例
{
"total_count": 2,
"instances": [
{
"instance_id": "1995a67680474481b3e42ac1474e32e0in14",
"instance_name": "gauss-a283"
},
{
"instance_id": "8303819fd8744ef69f34595e9710a33din14",
"instance_name": "gauss-2423-lt-master"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 82
云数据库 GaussDB
API 参考 4 API（推荐）
4.2.11 校验参数组名称是否存在
功能介绍
校验参数组名称是否存在。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/name-
validation?name={name}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/configurations/name-
validation?name=paramTemplate-a9f3
● 参数说明
表 4-98 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
name 是 String 参数模板名称。 取值范围：
长度1到64位之间，区分大小
写字母，可包含字母、数字、
中划线、下划线或句点，不能
包含其他特殊字符。
请求消息
● 参数说明
无。
响应消息
● 正常响应要素说明
表 4-99 参数说明
参数 参数类型 描述
exist Boolean 校验结果。true为已存在，false为不存在。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 83
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息示例
● 正常响应要素说明
{
"exist" : false
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.12 应用参数模板
功能介绍
应用参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
PUT https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
apply
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/apply
● 参数说明
表 4-100 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 84
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
● 参数说明
表 4-101 参数说明
参数 是否必选 参数类型 描述
instance_ids 是 Array of 实例ID列表。
strings
请求示例
应用参数模板
{
"instance_ids" : [ "5362449138da4e408dbae5152ca26640in14",
"ea926816f0154066830d12ebebc8562din14" ]
}
响应消息
● 正常响应要素说明
表 4-102 参数说明
参数 参数类型 描述
job_id String 应用参数模板的异步任务ID。
响应消息示例
● 正常响应要素说明
{
"job_id" : "bf26cf3c-d046-4080-bb45-f114be7afa5f"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 85
云数据库 GaussDB
API 参考 4 API（推荐）
4.2.13 查询参数模板的应用记录
功能介绍
查询参数模板的应用记录。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
applied-histories
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/applied-histories
● 参数说明
表 4-103 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。例如：该参数指定为0，
limit指定为10，则只展示第
1-10条数据。
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。例如该参数设定为
10，则查询结果最多只显示10
条记录。
请求消息
无。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 86
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-104 参数说明
参数 参数类型 描述
histories Array of 应用记录列表，具体参数请参考表4-105。
objects
total_count Integer 总记录数。
表 4-105 histories 字段数据结构说明
参数 参数类型 描述
instance_id String 实例ID。
instance_na String 实例名称。
me
apply_result String 应用状态 (SUCCESS | FAILED | APPLYING)。
applied_at String 应用时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。 其中，T指某个时间的开
始；Z指时区偏移量，例如北京时间偏移显示
为+0800。
error_code String 失败原因错误码，如DBS.280005。
● 正常响应样例
{
"total_count": 2,
"histories": [
{
"instance_id": "1995a67680474481b3e42ac1474e32e0in14",
"instance_name": "gauss-a283",
"apply_result" : "SUCCESS",
"applied_at" : "2022-08-09T03:06:52+0800",
"error_code" : null
},
{
"instance_id": "8303819fd8744ef69f34595e9710a33din14",
"instance_name": "gauss-2423-lt-master",
"apply_result" : "FAILED",
"applied_at" : "2022-08-09T03:06:52+0800",
"error_code" : "DBS.280005"
}
]
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 87
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.14 查询参数模板的修改历史
功能介绍
查询参数模板的修改历史记录。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
histories
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/histories
● 参数说明
表 4-106 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。例如：该参数指定为0，
limit指定为10，则只展示第
1-10条数据。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 88
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。例如该参数设定为
10，则查询结果最多只显示10
条记录。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-107 参数说明
参数 参数类型 描述
histories Array of 参数模板信息，具体参数请参考表4-108。
objects
total_count Integer 总记录数。
表 4-108 histories 字段数据结构说明
参数 参数类型 描述
parameter_n String 参数名称。
ame
old_value String 修改前参数值。
new_value String 修改后参数值。
update_resul String 修改状态 (SUCCESS | FAILED)。
t
updated_at String 修改时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量，
例如北京时间偏移显示为+0800。
● 正常响应样例
{
"histories" : [ {
"parameter_name" : "audit_system_object",
"old_value" : "12295",
"new_value" : "12298",
"update_result" : "SUCCESS",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 89
云数据库 GaussDB
API 参考 4 API（推荐）
"updated_at" : "2022-08-09T03:06:52+0800"
} ],
"total_count" : 1
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3 备份管理
4.3.1 查询备份列表
功能介绍
获取备份列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
该接口仅支持查询GaussDB的手动全量备份及自动全量备份(包括XBSA手动全量备份
类型、手动增量备份类型)。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/backups?
instance_id={instance_id}&backup_id={backup_id}&backup_type={backup_typ
e}&offset={offset}&limit={limit}&begin_time={begin_time}&end_time={end_ti
me}
● URI样例
– 查询所有备份列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/054ea741f700d4a32f1bc00f5c80dd4c/backups
– 根据指定条件查询实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/backups?
instance_id=88be33e4c5a64ceba42b42da89310111in14&backup_id=88be1234
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 90
云数据库 GaussDB
API 参考 4 API（推荐）
c5a64ceba42b42da89310111br14&backup_type=auto&begin_time=2022-05-0
9T16:15:50+0800&end_time=2022-05-09T16:20:45+0800&limit=1&offset=1
● 参数说明
表 4-109 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 否 String 实例ID，严格匹配UUID规
则。增备列表查询时实例IDid
必选。
backup_id 否 String 备份ID，严格匹配UUID规
则。
backup_type 否 String 备份类型，取值范围：
● auto：实例级自动全量备
份
● manual：实例级手动全量
备份
● Snapshot_Xbsa：xbsa手
动全量备份
● Log_Xbsa xbsa：增量备
份(该类型仅支持3.301及以
上版本实例)
● auto_database_table：
表级自动备份
● manual_database_table
：表级手动备份
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。
最小值：0
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。
最小值：1
最大值：100
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 91
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
begin_time 否 String 查询开始时间，格式为
“yyyy-mm-
ddThh:mm:ssZ”。其中，T指
某个时间的开始；Z指时区偏
移量。与end_time必须同时使
用。
end_time 否 String 查询结束时间，格式为
“yyyy-mm-
ddThh:mm:ssZ”，且大于查
询开始时间。其中，T指某个
时间的开始；Z指时区偏移
量。与begin_time必须同时使
用。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-110 参数说明
参数 参数类型 描述
backups Array of 备份信息。
objects 详情请参见表4-111。
total_count Long 备份文件的总数。
表 4-111 backups 字段数据结构说明
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
description String 备份文件描述信息。
begin_time String 备份开始时间，格式为"yyyy-mm-
ddThh:mm:ssZ"。 其中，T指某个时间的开
始；Z指时区偏移量。
end_time String 备份结束时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。 其中，T指某个时间的开
始；Z指时区偏移量。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 92
云数据库 GaussDB
API 参考 4 API（推荐）
参数 参数类型 描述
detail_messa String 备份详情信息，备份成功为 ‘success’或者
ge 为空；备份失败的时候会返回GaussDB生成失
败的错误信息。
status String 备份状态
枚举值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
size Double 备份大小(单位：MB)。
type String 备份类型
取值：
● auto：实例级自动全量备份。
● manual：实例级手动全量备份。
● auto_database_table：表级自动备份
● manual_database_table：表级手动备份
● Log_Xbsa：Xbsa增量备份
datastore Object 数据库信息。
详情请参见表4-112
instance_id String 实例ID。
表 4-112 datastore 字段数据结构说明
参数 参数类型 描述
type String 数据库引擎，不区分大小写，取值如下：
GaussDB。
version String 数据库版本。不填时，默认为当前最新版本。
● 正常响应样例
{
"backups": [
{
"id": "a696cd25e4fc453aa503650225cece8bbr14",
"name": "GaussDB-hly-ha-20220509080110906",
"description": null,
"status": "FAILED",
"size": 0.0,
"type": "auto",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 93
云数据库 GaussDB
API 参考 4 API（推荐）
"begin_time": "2022-05-09T16:01:10+0800",
"end_time": "2022-05-09T16:04:31+0800",
"detail_message": "success",
"instance_id": "164abc6d35114095bb849d007b19db3bin14"
},
{
"id": "5651c62a7f12461c98020dd3abfe24ccbr14",
"name": "GaussDB-hly-master-20220509022658257",
"description": null,
"status": "FAILED",
"size": 0.0,
"type": "auto",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"begin_time": "2022-05-09T10:26:58+0800",
"end_time": "2022-05-09T10:30:17+0800",
"instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
}
],
"total_count": 167
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.2 创建手动备份
功能介绍
创建手动备份。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/backups
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 94
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-113 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
请求消息
● 参数说明
表 4-114 参数说明
参数 是否必选 参数类型 描述
instance_id 是 String 实例ID。
name 是 String 备份名称，4~64个字符，必须
以英文字母开头，区分大小
写，可以包含英文字母、数
字、中划线或者下划线，不能
包含其他特殊字符。
最小长度：4
最大长度：64
description 否 String 备份描述，不能包含>!<"&'=
特殊字符，不大于256个字
符。
最大长度：256
backup_type 否 String 创建备份的类型，缺省值为
"completed" 。
取值：
● completed: 全备。
● differential: 差备，仅支持
xbsa实例。
● log: 增备，仅支持xbsa实
例(该类型仅支持3.301及以
上版本实例)。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 95
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
depend_back 否 Array of 增备时依赖的全备、差备的备
upIds String 份id列表，仅支持xbsa实例。
注意
由于PITR恢复时间由第三方维
护，因此字段由第三方自行计算
得出，计算为当前PITR最大可恢
复时间之前最近一次备份所对应
的BACKUPID的ENDTIME之后所
有备份对应的BACKUPID。
table_list 否 Array 表级备份信息。填写该参数会
创建表级备份，不填写则不会
创建实例级备份。详情参见表
4-115。
说明
● 仅支持3.200以上实例。
● 最多支持100个库或100个表
同时创建备份，超出建议使
用实例级备份。
表 4-115 table_list 字段数据结构说明
名称 是否必选 参数类型 说明
db_name 是 String 库名。
schema_name 是 String schema名。
table_name 是 String 表名。
请求示例
创建GaussDB手动全量备份。
{
"instance_id" : "7e01ac5ac5274957ba506f3851d11d51in14",
"name" : "backupwqwq3",
"description" : "manual backup",
"table_list": [
{
"db_name": "table_backup_db",
"schema_name": "myschema1",
"table_name": "test"
}
]
}
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 96
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-116 响应 Body 参数
参数 参数类型 描述
backup Object 备份信息。
详情请参见表4-117
job_id String 任务ID。
表 4-117 backup 字段数据结构说明
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
description String 备份描述。
begin_time String 备份开始时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量。
status String 备份状态，取值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
type String 备份类型，“manual”表示手动全量备份
instance_id String 实例ID。
● 正常响应样例
{
"backup": {
"id": "e76112bfb2074871bf54cb8df5af7f64br14",
"name": "backupwqwq32",
"description": "mannual backup",
"status": "BUILDING",
"type": "manual",
"begin_time": "2022-05-09T18:02:31+0800",
"instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
},
"job_id": "e4733090-b2c8-4ea7-a33a-f55f65723fb3"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 97
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.3 删除手动备份
功能介绍
删除手动备份。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/gaussdb/v3/{project_id}/backups/{backup_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups/
e28d08754b1a490fb2b3540ed013a7fbbr14
● 参数说明
表 4-118 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
backup_id 是 String 备份ID。
请求消息
无。
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 98
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.4 查询可恢复时间段
功能介绍
查询可恢复时间段。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
restore-time?date={date}
● URI样例
https://gaussdb-opengauss-api.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
d2113b7c60154636b94bea1320b6a874in14/restore-time?date=2022-04-17
● 参数说明
表 4-119 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
date 是 String 所需查询的日期，为yyyy-
mm-dd字符串格式，时区为
UTC。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 99
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
schema_type 否 String 备份类别取值, 默认值：
INSTANCE。
枚举值：
● INSTANCE：实例级备份。
● DATABASE_TABLE：表级
备份。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-120 参数说明
参数 参数类型 描述
restore_time Array of 可恢复时间段列表。
objects 详情请参见表4-121
表 4-121 restore_time 字段数据结构说明
参数 参数类型 描述
start_time Long 可恢复时间段的起始时间点，UNIX时间戳格
式，单位是毫秒，时区是UTC+8。
end_time Long 可恢复时间段的结束时间点，UNIX时间戳格
式，单位是毫秒，时区是UTC+8。
● 正常响应样例
{
"restore_time": [
{
"start_time": 1652084311000,
"end_time": 1652092839000
},
{
"start_time": 1652092847000,
"end_time": 1652094792000
}
]
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 100
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.5 恢复到新实例
功能介绍
根据备份恢复新实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 目标实例与源实例的数据库版本和实例类型必须一致。
● 目标实例规格必须大于等于源实例规格。
● 支持金融版（标准型）、1主3备、1主2备和BMS的金融版计算型形态的实例。
● 支持实例在资源类型BMS、ECS、MCS之间恢复到新实例，当前仅支持恢复到相
同的部署形态。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances
● 参数说明
表 4-122 参数说明
参数 是否必选 描述
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 101
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
表 4-123 参数说明
参数 是否必选 参数类型 描述
name 是 String 实例名称。
用于表示实例的名称，同一租户
下，同类型的实例名可重名。
取值范围：4~64个字符之间，
必须以字母开头，区分大小写，
可以包含字母、数字、中划线或
者下划线，不能包含其他的特殊
字符。
availability_zo 是 String 可用区ID。
ne GaussDB取值范围：非空，可选
部署在同一可用区或三个不同可
用区，可用区之间用逗号隔开。
详见示例。
● 部署在同一可用区：需要输
入三个相同的可用区。
● 部署在三个不同可用区：需
要分别输入三个不同的可用
区。
取值范围：非空，请向企业管理
员获取。
flavor_ref 是 String 规格码，取值范围：非空。参考
数据库实例规格中GaussDB的
“规格编码”列内容获取。
volume 是 Object volume信息。
详情请参见表4-124
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务
的控制台界面，在虚拟私有
云的详情页面查找VPC ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
VPC列表”的内容。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 102
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
subnet_id 是 String 子网的网络ID信息，获取方法如
下：
● 方法1：登录虚拟私有云服务
的控制台界面，单击VPC下
的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
子网列表”的内容。
security_grou 是 String 指定实例所属的安全组。
p_id ● 方法1：登录虚拟私有云服务
的控制台界面，在安全组的
详情页面查找安全组ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
安全组列表”的内容。
password 是 String 数据库密码。
GaussDB密码取值范围:
非空； 至少包含大写字母（A-
Z），小写字母（a-z），数字
（0-9），非字母数字字符（限
定为~!@#%^*-_=+?,）四类字符
中的三类字符；长度8~32个字
符。
建议您输入高强度密码，以提高
安全性，防止出现密码被暴力破
解等安全风险。
charge_info 否 Object 付费方式信息，支持按需。
详情请参见表4-125。
backup_strate 否 Object 自动备份策略。
gy 详情请参见表4-128。
restore_point 是 Object 恢复数据源对象。
详情请参见表4-126。
configuration_ 否 String 参数组ID。当不传该参数时，使
id 用系统默认的参数模板。
port 否 String GaussDB数据库端口当前只支持
设置为8000，当不传该参数
时，默认端口为8000。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 103
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
time_zone 否 String UTC时区。
● 不选择时，GaussDB默认为
UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且
只支持整段时间，如UTC
+08:00，不支持UTC
+08:30。
master_az 否 String 主可用区ID。取值为
availability_zone三个可用区ID
其一。当原实例存在单独的仲裁
可用区时必传，金融版（数据计
算型）和其他情况不需要填写。
arbitration_az 否 String 仲裁可用区ID。取值为
availability_zone三个可用区ID
其一。当原实例存在单独的仲裁
可用区时必传，其他情况不需要
填写。
xbsa_ssl_certs 否 Object xbsa SSL证书信息。
详情请参见表4-129。
kms_tde_key_i 否 String GaussDB使用透明加密的KMS主
d 密钥ID，填写ID启用透明加密功
能。需要填写为原实例KMS主密
钥ID。
kms_project_n 否 String kms_tde_key_id不为空时必传。
ame GaussDB使用透明加密的KMS主
密钥ID所在资源空间名称。
需要填写为原实例KMS主密钥ID
所在资源空间名称。
获取方法请参见获取项目ID/名
称。
表 4-124 volume 字段数据结构说明
参数 是否必选 参数类型 描述
type 是 String 磁盘类型。
仅支持LOCALSSD，
ULTRAHIGH。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 104
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
size 是 Integer 磁盘大小,需要大于等于原实
例。例如：该参数填写为
“40”，表示为恢复的实例分
配40GB的磁盘空间。
ECS部署方案取值范围：（分片
数*40GB）~（分片数*16TB），
且大小只能为分片数*40的整数
倍。
MCS部署方案：取值范围：（分
片数*40GB）~（分片数
*16TB），且大小只能为分片数
*40的整数倍。
BMS部署方案：该参数由所选择
的规格自动计算，不可指定，即
使填写，也不会生效。
表 4-125 charge_info 字段数据结构说明
参数 是否必选 参数类型 描述
charge_mode 是 String 计费模式。支持postPaid，后付
费，即按需付费。
表 4-126 restore_point 字段数据结构说明
参数 是否必选 参数类型 描述
instance_id 是 String 源实例ID。
backup_id 否 String 用于恢复的备份ID。
restore_time 否 String PITR用于恢复的时间戳，obs恢
复可通过 【查询可恢复时间
段】接口查询。详情请参见查询
可恢复时间段。xbsa恢复可通过
第三方文件解析查询。
type 是 String 表示恢复方式，缺省值为
backup，枚举值：
“backup”，表示使用备份文
件恢复，按照此方式恢复时，
“backup_id”必选。
“timestamp”，表示按时间
点恢复，按照此方式恢复时，
“restore_time”必选。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 105
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
table_list 否 Array 表级备份信息。仅恢复到库或恢
复到表需要填写。详情参见表
4-127。
说明
● 仅支持3.200以上实例。
● 最多支持100个库或100个表同
时恢复，超出建议使用实例级
恢复。
schema_type 否 String 源备份类别，默认值：
INSTANCE
枚举值：
● INSTANCE：实例级备份
● DATABASE_TABLE：表级备
份
表 4-127 table_list 字段数据结构说明
名称 是否必选 参数类型 说明
db_name 是 String 源备份库名
说明
不支持恢复模板库以及系统用
户。
模板库包括postgres、
template0 、template1。
系统用户包括rdsAdmin、
rdsMetric、rdsBackup、
rdsRepl。
schema_name 否 String 源备份schema
恢复到表时，该参数必传，
恢复到库时，该参数无效。
说明
不支持恢复系统级的如
dbe_application_info、rdsRepl
等schema。
table_name 否 String 源备份表名
恢复到表时，该参数必传，
恢复到库时，该参数无效。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 106
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
new_db_name 否 String 恢复到的新库名
不填时与源备份库名一致。
说明
● 数据库名称长度可在1～63
个字符之间，由字母、数
字、或下划线组成，不能包
含其他特殊字符，不能以
“pg”和数字开头，且不能
和模板库重名。 模板库包括
postgres、 template0 、
template1。也不能以系统
用户rdsAdmin、
rdsMetric、rdsBackup、
rdsRepl命名。
● 不使用保留或非保留关键字
命名数据库对象，具体请参
考《开发指南》中的"开发设
计建议 - 数据库对象命名"
章节。
new_schema_nam 否 String 恢复到的新schema
e 恢复到库时，该参数无效，
恢复到表不填时与源备份
schema一致。
说明
● schema名称在1到63个字符
之间，由字母、数字、或下
划线组成，不能包含其他特
殊字符，不能以“pg”和数
字开头，且不能和模板库、
已存在的schema重名，模板
库包括postgres、
template0 、template1，
已存在的schema包括
public、
information_schema，另外
不支持恢复系统级的如
dbe_application_info、
rdsRepl等schema。
● 不使用保留或非保留关键字
命名数据库对象，具体请参
考《开发指南》中的"开发设
计建议 - 数据库对象命名"
章节。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 107
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
new_table_name 否 String 恢复到的新表名
恢复到库时，该参数无效，
恢复到表不填时与备份的表
名一致。
说明
● 表名在1到63个字符之间，
由字母、数字、或下划线组
成，不能包含其他特殊字
符，不能以“pg”和数字开
头，具体请参考《开发指
南》中的"开发设计建议 -
数据库对象命名"章节。
表 4-128 backup_strategy 字段数据结构说明
参数 是否必选 参数类型 描述
start_time 是 String 备份时间段。自动备份将在该时
间段内触发。
取值范围：非空，格式必须为
hh:mm-HH:MM且有效，当前
时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且
取值必须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days 否 Integer 指定备份文件的可保存天数。
取值范围：0～732，开放
“gaussdb_feature_supportCo
nsoleBackupPolicyDay_36500
”白名单后，支持备份文件最长
保留天数36500天。该参数缺省
或为0时，默认填写为30天。
表 4-129 xbsa_ssl_certs 字段数据结构说明
参数 是否必选 参数类型 描述
ca_cert_pem 是 String 根证书文件内容。base64编
码。
client_crt 是 String 用户证书内容。base64编码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 108
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
client_key 是 String 用户私钥内容。base64编码。
rand_pass 是 String 私钥文件的密码。
● 请求示例
恢复实例：
{
"name": "targetInst",
"availability_zone": "aaa,bbb,ccc",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.x868.co",
"volume": {
"type": "LOCALSSD",
"size": 160
},
"vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
"subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
"security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
"password": "******",
"restore_point": {
"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin14",
"backup_id": "2f4ddb93b9014b0893d81d2e472f30febr14",
"table_list": [
{
"db_name": "table_backup_db",
"schema_name": "myschema1",
"table_name": "test"
}
],
"schema_type": "DATABASE_TABLE"
},
"configuration_id": "52e86e87445847a79bf807ceda213165pr01",
"port": 8000,
"time_zone": "UTC+04:00",
"master_az": "aaa",
"arbitration_az": "bbb"
}
响应消息
● 正常响应要素说明
表 4-130 要素说明
参数 参数类型 描述
instance Object 实例信息。
详情请参见表4-131。
job_id String 恢复新实例的任务id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 109
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-131 instance 说明
参数 参数类型 描述
id String 实例id。
name String 实例名称。 用于表示实例的名称，同一租户
下，同类型的实例名可重名。
取值范围：4~64个字符之间，必须以字母开
头，区分大小写，可以包含字母、数字、中划
线或者下划线，不能包含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
datastore Object 数据库信息。
详情请参见表4-132
ha Object 实例部署形态。
详情请参见表4-133
port String 数据库端口信息。 当不传该参数时，默认端口
8000。
volume Object volume信息。
详情请参见表4-134
backup_strat Object 自动备份策略。
egy 详情请参见表4-135
replica_num Integer 实例副本数。
region String 区域ID。
flavor_ref String 规格码。
availability_z String 可用区ID。可选部署在同一可用区或三个不同
one 可用区，可用区之间用逗号隔开。
取值范围：非空，请向企业管理员获取。
vpc_id String 虚拟私有云ID。
subnet_id String 子网ID。
security_grou String 安全组ID。
p_id
charge_info Object 付费方式信息，支持按需。
详情请参见表4-136。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 110
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-132 datastore 字段数据结构说明
参数 参数类型 描述
type String 数据库引擎，返回值如下： GaussDB
枚举值：
● GaussDB
version String 数据库版本。
表 4-133 ha 字段数据结构说明
参数 参数类型 描述
mode String GaussDB 分布式模式，返回值为：enterprise
（企业版）；主备版，返回值为：
centralization_standard(主备版)。
replication_ String 备机同步参数。
mode 取值：
GaussDB为“sync”。
说明
“sync”为同步模式。
枚举值：
● sync
consistency String GaussDB的预留参数：指定实例一致性类型，
取值范围：strong（强一致性） | eventual(最
终一致性)。
枚举值：
● strong
● eventual
表 4-134 volume 字段数据结构说明
参数 参数类型 描述
type String 磁盘类型。
取值如下，区分大小写：
● ULTRAHIGH，表示SSD。
● LOCALSSD
枚举值：
● ULTRAHIGH
● LOCALSSD
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 111
云数据库 GaussDB
API 参考 4 API（推荐）
参数 参数类型 描述
size Integer 磁盘大小。
GaussDB分布式实例恢复时需指定大小：要求
必须为（分片数 * 40GB）的倍数，取值范围：
（分片数40GB）~（分片数16TB）。
表 4-135 backup_strategy 字段数据结构说明
参数 参数类型 描述
start_time String 备份时间段。自动备份将在该时间段
内触发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时
间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值
必须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days Integer 指定备份文件的可保存天数。
取值范围：0～732，开放
“gaussdb_feature_supportConsoleB
ackupPolicyDay_36500”白名单后，
支持备份文件最长保留天数36500天。
该参数缺省时，默认填写为30天。
表 4-136 charge_info 字段数据结构说明
参数 参数类型 描述
charge_mode String 计费模式。支持postPaid，后付费，即按需付
费。
● 正常响应样例
{
"instance": {
"id": "2gfdsh844a4023a776fc5c5fb71fb4in14",
"name": "gaussdb-instance-rep2",
"status": "BUILD",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"ha": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 112
云数据库 GaussDB
API 参考 4 API（推荐）
"mode": "enterprise",
"consistency": "strong",
"replication_mode": "sync"
},
"volume": {
"type": "LOCALSSD",
"size": 160
},
"port": "8000",
"replica_num": 3,
"region": "regionA",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.x868.co",
"availability_zone": "aaa,bbb,ccc",
"vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
"subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
"security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
"charge_info": {
"charge_mode": "postPaid"
},
},
"job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.6 恢复到当前实例
功能介绍
将数据库恢复到当前实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{endpoint}/gaussdb/v3/{project_id}/instances/recovery
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/recovery
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 113
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-137 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
请求消息
● 参数说明
表 4-138 参数说明
参数 是否必选 参数类型 描述
source 是 Objects 恢复数据源对象。详情见表
4-139
target 是 Objects 恢复目标对象。详情见表
4-140
表 4-139 source 字段数据结构说明
参数 是否必选 参数类型 描述
instance_id 是 String 实例ID。
type 是 String 表示恢复方式，缺省值为
backup，枚举值：
“backup”，表示使用备份
文件恢复，按照此方式恢复
时，“backup_id”必选。
“timestamp”，表示按时间
点恢复，按照此方式恢复时，
“restore_time”必选。
backup_id 否 String 用于恢复的备份ID。当使用备
份文件恢复时需要指定该参
数。
xbsa可支持差量备份ID 恢复
restore_time 否 String Pitr用于恢复的时间戳，obs恢
复可通过 【查询可恢复时间
段】接口查询。详情请参见查
询可恢复时间段。xbsa恢复可
通过第三方文件解析查询。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 114
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
table_list 否 Array 表级备份信息。仅恢复到库或
恢复到表需要填写。详情参见
表4-141
说明
● 仅支持3.200以上实例。
● 最多支持100个库或100个表
同时恢复，超出建议使用实
例级恢复。
schema_type 否 String 源备份类别，默认值：
INSTANCE
枚举值：
● INSTANCE：实例级备份
● DATABASE_TABLE：表级
备份
表 4-140 target 字段数据结构说明
参数 是否必选 参数类型 描述
instance_id 是 String 恢复目标实例ID。
表 4-141 table_list 字段数据结构说明
名称 是否必选 参数类型 说明
db_name 是 String 源备份库名
说明
不支持恢复模板库以及系统用
户。
模板库包括postgres、
template0 、template1。
系统用户包括rdsAdmin、
rdsMetric、rdsBackup、
rdsRepl。
schema_name 否 String 源备份schema
恢复到表时，该参数必传，
恢复到库时，该参数无效。
说明
不支持恢复系统级的如
dbe_application_info、
rdsRepl等schema。
table_name 否 String 源备份表名
恢复到表时，该参数必传，
恢复到库时，该参数无效。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 115
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
new_db_name 否 String 恢复到的新库名
不填时与源备份库名一致。
说明
● 不能与当前实例已有库同
名。
● 数据库名称长度可在1～
63个字符之间，由字母、
数字、或下划线组成，不
能包含其他特殊字符，不
能以“pg”和数字开头，
且不能和模板库重名。 模
板库包括postgres、
template0 、
template1。也不能以系
统用户rdsAdmin、
rdsMetric、rdsBackup、
rdsRepl命名。
● 不使用保留或非保留关键
字命名数据库对象，具体
请参考《开发指南》中的"
开发设计建议 - 数据库对
象命名"章节。
new_schema_na 否 String 恢复到的新schema
me 恢复到库时，该参数无效，
恢复到表不填时与源备份
schema一致。
说明
● 不能与当前实例已有
schema同名。
● schema名称在1到63个字
符之间，由字母、数字、
或下划线组成，不能包含
其他特殊字符，不能以
“pg”和数字开头，且不
能和模板库、已存在的
schema重名，模板库包括
postgres、 template0 、
template1，已存在的
schema包括public、
information_schema，另
外不支持恢复系统级的如
dbe_application_info、
rdsRepl等schema。
● 不使用保留或非保留关键
字命名数据库对象，具体
请参考《开发指南》中的"
开发设计建议 - 数据库对
象命名"章节。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 116
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
new_table_name 否 String 恢复到的新表名
恢复到库时，该参数无效，
恢复到表不填时与备份的表
名一致。
说明
● 不能与当前实例已有表同
名。
● 表名在1到63个字符之
间，由字母、数字、或下
划线组成，不能包含其他
特殊字符，不能以“pg”
和数字开头，具体请参考
《开发指南》中的"开发设
计建议 - 数据库对象命名"
章节。
● 请求样例
恢复到当前实例
{
"source" : {
"instance_id" : "5362449138da4e408dbae5152ca26640in14",
"type" : "backup",
"backup_id" : "cc94568cb5a54e4a8ab5dff95e64a5e0br14" ,
"table_list": [
{
"db_name": "table_backup_db",
"schema_name": "myschema",
"table_name": "test"
}
],
"schema_type": "DATABASE_TABLE"
},
"target" : {
"instance_id" : "5362449138da4e408dbae5152ca26640in14"
}
}
响应消息
● 正常响应要素说明
表 4-142 响应 Body 参数
参数 参数类型 描述
job_id String 任务ID。
● 正常响应样例
{
"job_id" : "a03b1b8a-b756-467c-8a49-38720c3d23ec"
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 117
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.7 备份恢复后执行数据确认
功能介绍
确认备份恢复后的数据是否正常，仅需要在恢复到当前实例后调用。数据确认后会删
除本次恢复时间点后的归档日志，并重新开启日志归档。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
confirm-restore-data
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/confirm-restore-data
● 参数说明
表 4-143 参数说明
名称 类型 是否必 描述
选
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id String 是 实例ID。
请求消息
无
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 118
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-144 响应 Body 参数
名称 类型 描述
job_id String 任务ID
● 正常响应样例
{
"job_id" : "a03b1b8a-b756-467c-8a49-38720c3d23ec"
}
– 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.8 查询差量备份列表
功能介绍
查询差量备份列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
differential-backups
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
2e642f2861004f659bc567858936160ein14/differential-backups
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 119
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-145 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
limit 否 String 查询记录数。默认为10，不能
为负数，最小值为1，最大值
为100。
最小值：1
最大值：100
offset 否 String 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。
最小值：0
begin_time 否 String 查询开始时间，默认为当前时
刻格式为“yyyy-mm-
ddThh:mm:ssZ”。其中，T指
某个时间的开始；Z指时区偏
移量，例如北京时间偏移显示
为+0800。
end_time 否 String 查询结束时间，默认为当前时
间格式为“yyyy-mm-
ddThh:mm:ssZ”，且大于查
询开始时间。其中，T指某个
时间的开始；Z指时区偏移
量，例如北京时间偏移显示为
+0800
请求消息
无。
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 120
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-146 响应 Body 参数
参数 参数类型 描述
differential_b String 差量备份列表，详情见表4-147。
ackups
total_count Integer 查询结果总数。
表 4-147 响应 differential_backups 参数
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
begin_time String 备份开始时间，格式为"yyyy-mm-
ddThh:mm:ssZ"。其中，T指某个时间的开
始；Z指时区偏移量，例如北京时间偏移显示
为+0800。
end_time String 备份结束时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。其中，T指某个时间的开
始；Z指时区偏移量，例如北京时间偏移显示
为+0800。
status String 备份状态
枚举值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
size Double 备份大小(单位：MB)。
● 正常响应样例
{
"differential_backups": [
{
"id": "2fc14f56ef074d9cbc3005626870acddbr14",
"name": "hc_test1230",
"status": "Active",
"size": 0.840538025390625,
"begin_time": "2023-03-06T22:28:06+0800",
"end_time": "2023-03-06T22:30:12+0800"
}
],
"total_count": 1
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 121
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.9 安装三方备份 SSL 证书
功能介绍
XBSA备份实例安装SSL证书。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
backups/ssl-certs
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
2e642f2861004f659bc567858936160ein14/backups/ssl-certs
● 参数说明
表 4-148 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 122
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-149 参数说明
参数 是否必选 参数类型 描述
ca_cert_pem 是 String 根证书文件内容，采用base64
编码格式。
client_crt 是 String 用户证书内容，采用base64编
码格式。
client_key 是 String 用户私钥内容，采用base64编
码格式。
rand_pass 是 String 客户端私钥密码字符串。
● 请求示例
安装SSL 证书
{
"ca_cert_pem" : "Q2VydGlmaWNhdGU6CiAgICBEYXRhOgogICAgIC***************************",
"client_crt" : "Q2VydGlmaWNhdGU6CiAgICBEYXRhOgogICAgIC***************************",
"client_key" : "Q2VydGlmaWNhdGU6CiAgICBEYXRhOgogICAgIC***************************",
"rand_pass" : "pass"
}
响应消息
● 正常响应要素说明
表 4-150 响应 Body 参数
参数 参数类型 描述
job_id String Job_id 任务ID。
● 正常响应样例
{
"job_id":"a03b1b8a-b756-467c-8a49-38720c3d23eo"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 123
云数据库 GaussDB
API 参考 4 API（推荐）
4.4 引擎版本和规格
4.4.1 查询引擎列表
功能介绍
查询引擎列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/datastores
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/datastores
● 参数说明
表 4-151 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
请求消息
● 请求示例
无。
响应消息
● 正常响应要素说明
表 4-152 要素说明
名称 参数类型 说明
datastores Array of objects 数据库引擎列表。
详情请参见表4-153。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 124
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-153 dataStores 字段数据结构说明
参数 参数类型 描述
supported_ve Array of 部署形态支持的引擎版本列表。
rsions strings
instance_mo String 部署形态。
de 枚举值：
● ha：主备版
● combined：分布式版 金融版（标准型）
● combined_hcs2：分布式版 企业版
● combined_hcs3：分布式版 金融版(标准
型)
● combined_hcs4：分布式版 金融版（数据
计算型，容灾主）
● combined_hcs5：分布式版 金融版（数据
计算型，容灾备）
● 正常响应样例
{
"datastores": [
{
"instance_mode": "ha",
"supported_versions": [
"2.0",
"2.3",
"2.6",
"2.9"
]
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5 管理数据库和用户
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 125
云数据库 GaussDB
API 参考 4 API（推荐）
4.5.1 创建数据库
功能介绍
在指定实例中创建数据库。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
该接口只支持单个数据库创建，实例在创建、变更规格、冻结、异常等状态下不能执
行该操作。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
database
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/{instance_id}/
database
● 参数说明
表 4-154 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-155 参数说明
名称 是否必选 参数类型 说明
name 是 String 数据库名称。
数据库名称长度可在1～63
个字符之间，由字母、数
字、或下划线组成，不能包
含其他特殊字符，不能以
“pg”和数字开头，且不
能和模板库重名。 模板库
包括postgres，
template0，template1。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 126
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
character_set 否 String 数据库字符集。默认
UTF8。
owner 否 String 数据库所属用户，缺省时默
认是root，不能和系统用户
重名，且必须是已存在的用
户。
系统用户包括
“rdsAdmin”,
“ rdsMetric”,
“rdsBackup”,
“rdsRepl”。
template 否 String 数据库模板名称，仅支持为
template0。
lc_collate 否 String 数据库排序集。默认C。
须知
不同的排序规则下，相同字符
串的比较其结果可能是不同
的。 例如，在en_US.utf8
下， select 'a'>'A';执行结果为
false，但在'C'下，select
'a'>'A';结果为true。如果数据
库从“O”迁移到GaussDB，
数据库排序集需使用'C'才能得
到一致的预期。支持的排序规
则可以查询系统表
pg_collation。
lc_ctype 否 String 数据库分类集。默认C。
请求示例
创建一个GaussDB数据库，库名为gaussdb_test。
{
"name" : "gaussdb_test",
"owner" : "test",
"template" : "template0",
"character_set" : "UTF8",
"lc_collate" : "en_US.UTF-8",
"lc_ctype" : "en_US.UTF-8"
}
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 127
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.2 创建数据库用户
功能介绍
在指定实例中创建数据库用户。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
● 实例在创建、变更规格、冻结、异常等状态下不能执行该操作。
● 该接口只支持创建单个用户接口。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-
user
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
{instance_id}/db-user
● 参数说明
表 4-156 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 128
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-157 参数说明
名称 是否必选 参数类型 说明
name 是 String 数据库用户名称。
数据库用户名称在1到63个
字符之间，由字母、数字、
或下划线组成，不能包含其
他特殊字符，不能以
“pg”和数字开头，不能
和系统用户名称相同。
系统用户包括
“rdsAdmin”,
“ rdsMetric”,
“rdsBackup”,
“rdsRepl”, “root”。
password 是 String 数据库用户密码。
取值范围：非空，密码长度
在8到32个字符之间，至少
包含大写字母、小写字母、
数字、特殊字符~!@#%^*-
_=+?,三种字符的组合，不
能和数据库帐号“name”
或“name”的逆序相同。
建议您输入高强度密码，以
提高安全性，防止出现密码
被暴力破解等安全风险。
请求示例
创建一个GaussDB数据库用户，用户名为dbs。
{
"name" : "dbs",
"password" : "******"
}
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 129
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.5.3 创建数据库 SCHEMA
功能介绍
在指定实例的数据库中, 创建数据库schema。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
实例在创建、变更规格、冻结、异常等状态下不能执行该操作。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
schema
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/{instance_id}/
schema
● 参数说明
表 4-158 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 130
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-159 参数说明
名称 是否必选 参数类型 说明
db_name 是 String 数据库名称。
数据库名称在1到63个字符
之间，由字母、数字、或下
划线组成，不能包含其他特
殊字符，不能以“pg”和
数字开头，且不能和模板库
重名。
模板库包括postgres，
template0 ，template1。
schemas 是 Array of 每个元素都是与数据库相关
objects 联的schema信息。单次请
求最多支持20个元素。详情
请参见表4-160
表 4-160 schemas 字段数据结构说明
名称 是否必选 参数类型 说明
name 是 String schema名称。
schema名称在1到63个字
符之间，由字母、数字、或
下划线组成，不能包含其他
特殊字符，不能以“pg”
和数字开头，且不能和模板
库和已存在的schema重
名。模板库包括postgres，
template0 ，template1。
已存在的schema包括
public，
information_schema。
owner 是 String 数据库属主用户。
数据库属主名称在1到63个
字符之间，不能以“pg”
和数字开头，不能和系统用
户名称相同。
系统用户包括
“rdsAdmin”,
“ rdsMetric”,
“rdsBackup”,
“rdsRepl”。
请求示例
在gaussdb_test数据库中创建多个SCHEMA。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 131
云数据库 GaussDB
API 参考 4 API（推荐）
{
"db_name" : "gaussdb_test",
"schemas" : [ {
"name" : "rds",
"owner" : "teste123"
}, {
"name" : "rds001",
"owner" : "teste123"
} ]
}
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.4 授权数据库帐号
功能介绍
在指定实例的数据库中, 设置帐号的权限。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
● 实例在创建、变更规格、冻结、异常等状态下不能执行该操作。
● 创建的只读用户对public模式默认具有create和usage权限。
● 同一schema不能同时授权。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-
privilege
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
{instance_id}/db-privilege
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 132
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-161 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-162 参数说明
名称 是否必选 参数类型 说明
db_name 是 String 数据库名称。
数据库名称在1到63个字符
之间，由字母、数字、或下
划线组成，不能包含其他特
殊字符，不能以“pg”和
数字开头，且不能和模板库
重名。
模板库包括postgres，
template0 ，template1。
users 是 Array of 每个元素都是与数据库相关
objects 联的帐号。单次请求最多支
持50个元素。详情请参见表
4-163。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 133
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-163 users 字段数据结构说明
名称 是否必选 参数类型 说明
name 是 String 数据库帐号名称。
数据库帐号名称在1到63个
字符之间，由字母、数字、
或下划线组成，不能包含其
他特殊字符，不能以
“pg”和数字开头，不能
和系统用户名称相同且帐号
名称必须存在。
系统用户包括
“rdsAdmin”,
“rdsMetric”,
“rdsBackup”,
“rdsRepl”, “root”。
readonly 是 Boolean 数据库帐号权限。
● true：只读。
● false：可读可写。
schema_name 是 String schema名称。
schema名称在1到63个字
符之间，由字母、数字、或
下划线组成，不能包含其他
特殊字符，不能以“pg”
和数字开头，不能和模板库
重名，且schema名称必须
存在。
模板库包括postgres，
template0 ，template1,
public，
information_schema。
请求示例
设置gaussdb_test数据库多个帐号的权限。
{
"db_name" : "gaussdb_test",
"users" : [ {
"name" : "rds",
"readonly" : false,
"schema_name" : "teste123"
}, {
"name" : "rds001",
"readonly" : true,
"schema_name" : "teste134"
}, {
"name" : "rds002",
"readonly" : false,
"schema_name" : "teste135"
} ]
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 134
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.5 重置数据库帐号密码
功能介绍
重置指定数据库帐号的密码。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
● 实例在创建、变更规格、冻结、异常等状态下不能执行该操作。
● 该接口只支持重置单个用户。
URI
● URI格式
PUT https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-
user/password
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
{instance_id}/db-user/password
● 参数说明
表 4-164 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 135
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
● 参数说明
表 4-165 参数说明
名称 是否必选 参数类型 说明
name 是 String 数据库帐号名称，不能为系
统帐号用户。系统用户包括
“rdsAdmin”,
“rdsMetric”,
“rdsBackup”,
“rdsRepl”。
password 是 String 数据库帐号密码。
取值范围：
非空，至少包含以下字符中
的三种：大写字母、小写字
母、数字和特殊符号~!@#
%^*-_=+?,组成，长度8~32
个字符，不能和数据库帐号
“name”或“name”的
逆序相同。
建议您输入高强度密码，以
提高安全性，防止出现密码
被暴力破解等安全风险。
请求示例
重置数据库root帐号的密码。
{
"name" : "root",
"password" : "*******"
}
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 136
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.5.6 查询数据库列表
功能介绍
查询指定实例中的数据库列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
databases
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/instances/{instance_id}/
databases
● 参数说明
表 4-166 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
offset 否 Integer 分页符。从第一条数据偏移
offset页数据后开始查询，默
认为0（偏移0页数据，表示从
第一条数据开始查询），必须
为数字，不能为负数。例如：
该参数指定为1，limit指定为
10，则只展示第11-20条数
据。
limit 否 Integer 每页显示的条目数量,取值范围
[1, 100]，默认10。
请求消息
无。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 137
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-167 参数说明
参数 参数类型 描述
databases Array of 列表中每个元素表示一个数据库。详情参见表
objects 4-168。
total_count Integer 总记录数。
表 4-168 databases 字段数据结构说明
参数 参数类型 描述
name String 数据库名称。
owner String 数据库所属用户。
character_set String 数据库使用的字符集，例如UTF8。
collate_set String 数据库排序集，例如en_US.UTF-8等。
size String 数据库大小。
● 正常响应样例
{
"databases" : [ {
"name" : "rds-test",
"character_set" : "utf8",
"owner" : "root",
"collate_set" : "en_US.UTF-8",
"size" : 10777247
}, {
"name" : "testdb1",
"character_set" : "utf8",
"owner" : "root",
"collate_set" : "en_US.UTF-8",
"size" : 10777247
}, {
"name" : "tt",
"character_set" : "utf8",
"owner" : "root",
"collate_set" : "en_US.UTF-8",
"size" : 10777247
} ],
"total_count" : 3
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 138
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.7 查询数据库用户列表
功能介绍
指定实例中查询数据库用户列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-
users
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/instances/{instance_id}/db-
users
● 参数说明
表 4-169 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
offset 否 Integer 分页符。从第一条数据偏移
offset页数据后开始查询，默
认为0（偏移0页数据，表示从
第一条数据开始查询），必须
为数字，不能为负数。例如：
该参数指定为1，limit指定为
10，则只展示第11-20条数
据。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 139
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
limit 否 Integer 每页显示的条目数量,取值范围
[1, 100]，默认10。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-170 参数说明
参数 参数类型 描述
users Array of 列表中每个元素表示一个数据库用户，详情参
objects 见表4-171。
total_count Integer 数据库用户总数。
表 4-171 users 字段数据结构说明
参数 参数类型 描述
name String 数据库名称。
attribute Object 用户的权限属性，详情参见表4-172。
memberof String 用户的默认权限。
表 4-172 attributes 字段数据结构说明
参数 参数类型 描述
rolsuper Boolean 用户是否具有管理员权限，取值为“true”或
“false”。
rolinherit Boolean 用户是否自动继承其所属角色的权限，取值为
“true”或“false”。
rolcreaterole Boolean 用户是否支持创建其他子用户，取值为
“true”或“false”。
rolcreatedb Boolean 用户是否可以创建数据库，取值为“true”或
“false”。
rolcanlogin Boolean 用户是否可以登录数据库，取值为“true”或
“false”。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 140
云数据库 GaussDB
API 参考 4 API（推荐）
参数 参数类型 描述
rolconnlimit Integer 用户连接实例的最大并发连接数。-1表示没有
限制。
rolreplication Boolean 用户是否属于复制角色，取值为“true”或
“false”。
rolbypassrls Boolean 用户是否绕过每个行级安全策略，取值为
“true”或“false”。
● 正常响应样例
{
"users": [
{
"name": "root",
"attribute": {
"rolsuper": false,
"rolinherit": true,
"rolcreaterole": true,
"rolcreatedb": true,
"rolcanlogin": true,
"rolconnlimit": -1,
"rolreplication": false,
"rolbypassrls": false
},
"memberof":
"{gs_role_copy_files,gs_role_signal_backend,gs_role_tablespace,gs_role_replication,gs_role_a
ccount_lock}"
}
],
"total_count": 1
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.8 查询数据库 SCHEMA 列表
功能介绍
查询指定实例的数据库SCHEMA列表。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 141
云数据库 GaussDB
API 参考 4 API（推荐）
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
实例在异常或冻结状态下不能执行该操作。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
schemas?db_name={db_name}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/instances/{instance_id}/
schemas?db_name=dbname
● 参数说明
表 4-173 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
db_name 是 String 数据库名称。不能和模板库重
名。模板库包括postgres，
template0 ，template1。
offset 否 Integer 分页符。从第一条数据偏移
offset页数据后开始查询，默
认为0（偏移0页数据，表示从
第一条数据开始查询），必须
为数字，不能为负数。例如：
该参数指定为1，limit指定为
10，则只展示第11-20条数
据。
limit 否 Integer 每页显示的条目数量,取值范围
[1, 100]，默认10。
请求消息
无。
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 142
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-174 参数说明
参数 参数类型 描述
database_sch Array of 列表中每个元素表示一个数据库schema，详
emas objects 情参见表4-175。
total_count Integer 数据库schema总数。
表 4-175 database_schemas 字段数据结构说明
参数 参数类型 描述
schema_nam String schema名称。
e
owner String schema所属用户。
● 正常响应样例
{
"database_schemas" : [ {
"schema_name" : "rds-test",
"owner" : "root"
}, {
"schema_name" : "testdb1",
"owner" : "root"
} ],
"total_count" : 2
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.6 容灾管理
仅在特性白名单gaussdb_feature_supportDisasterApiGlobal处于开启状态下，容灾管
理API可用。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 143
云数据库 GaussDB
API 参考 4 API（推荐）
4.6.1 查询容灾集群监控状态
功能介绍
查询实例搭建容灾后实时容灾状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/monitor?disaster_type={disaster_type}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
a7d62bf77aa04fceb52fbd57181c9e3ein14/disaster-recovery/monitor?
disaster_type={disaster_type}
● 参数说明
表 4-176 参数说明
名称 是否必选 参 说明
数
类
型
project_id 是 Stri 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
instance_id 是 Stri 实例ID。
ng
disaster_type 是 Stri 容灾类型：
ng ● stream
● dorado
请求消息
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3.5/4a52a8a8f63d4c6d966dff0e20b69738/
instances/4d653d1caf0e4a49b4753713fac679e3in14/disaster-recovery/monitor?
disaster_type=stream
响应消息
表 4-177 响应 Body 参数列表
名称 参数类型 说明
instance_id String 实例id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 144
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
status String 容灾状态。
rpo String 数据恢复点目标。
rto String 数据恢复时间目标。
rpo_threshold String rpo阈值。
rto_threshold String rto阈值。
switchover_pro String 主从切换进度。该值为一个百分数。例
gress 如：40%
failover_progr String 容灾升主进度。该值为一个百分数。例
ess 如：40%
● 正常响应样例
{
"rpo":"0",
"rto":"0",
"status":"archive",
"instance_id":"b3692282395340c5b5421ecf3d7bd6adin14",
"rto_threshold":"900",
"rpo_threshold":"10",
"failover_progress":"",
"switchover_ progress ":""
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.2 查询容灾关系列表
功能介绍
查询容灾关系列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 145
云数据库 GaussDB
API 参考 4 API（推荐）
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.5/{project_id}/disaster-recovery/relations
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/disaster-recovery/relations
● 参数说明
表 4-178 参数说明
名称 参 是否必选 说明
数
类
型
project_id Stri 是 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
instance_nam Stri 否 实例名称，可查询过滤本端实例。
e ng
instance_id Stri 否 实例id，可查询过滤本端实例id。
ng
limit Int 否 查询记录数。为空时，默认为100。最
ege 小值为1，最大值为100。
r
offset Int 否 索引位置，偏移量。从第一条数据偏移
ege offset条数据后开始查询，默认为0（偏
r 移0条数据，表示从第一条数据开始查
询），必须为数字，不能为负数。
请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/4a52a8a8f63d4c6d966dff0e20b69738/disaster-recovery/relations?
limit=&offset=0&instance_name=test
请求消息
无
响应消息
表 4-179 响应 Body 参数列表
名称 参数类型 说明
total Integer 总记录数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 146
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
relations Array of Object 容灾关系详情。
表 4-180 relations 字段数据结构说明
名称 参数类型 说明
disaster_type String 容灾类型。
枚举值:
● stream
name String 容灾任务名称。
disaster_role String 容灾角色。
枚举值:
● disaster
● master
created String 创建时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移
量，例如北京时间偏移显示为+0800。
updated String 更新时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移
量，例如北京时间偏移显示为+0800。
slave_region_in Object 备region实例信息。
stance_info
master_region_i Object 主region实例信息。
nstance_info
synchronization String 容灾关系唯一id。
_id
id String 容灾记录id。
instance_id String 当前region实例id。
instance_name String 当前region实例名称。
instance_status String 当前region实例状态。
precheck_failed String 预校验失败原因。
_reason
status String 容灾记录状态。
actions Array of String 实例当前正在执行的action列表。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 147
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-181 region_instance_info 字段数据结构说明
名称 参数类型 说明
instance_id String 实例id。
project_id String 实例项目id。
project_name String 实例项目名称。
region_code String regionCode编码。
ip_address String 数据ip地址列表“,”分割。
● 正常响应样例
{
"total" : 1,
"relations" : [ {
"name" : "DR-task-0962",
"created" : "2022-06-16 09:39:51",
"updated" : "2022-06-16 09:44:55",
"id" : "30b74120-4b50-495d-8174-7eeddf7feac5",
"synchronization_id" : "9446f822-ccd2-43dc-929c-0b78ba7fdf64",
"status" : "normal",
"precheck_failed_reason" : "",
"disaster_type" : "stream",
"disaster_role" : "disaster",
"slave_region_instance_info" : {
"region_code" : "sa-fb-1",
"instance_id" : "d1060faf0d3743dd8830b39e7423bc9ain14",
"project_id" : "4a52a8a8f63d4c6d966dff0e20b69738",
"project_name" : "sa-fb-1_GaussDB",
"ip_address" : "172.166.1.192,172.166.0.6,172.166.1.135"
},
"master_region_instance_info" : {
"region_code" : "sa-fb-1",
"instance_id" : "54d4b9fb131745fcba32cb90a05cabb8in14",
"project_id" : "4a52a8a8f63d4c6d966dff0e20b69738",
"project_name" : "sa-fb-1_GaussDB",
"ip_address" : "172.167.1.86,172.167.0.89,172.167.1.229"
},
"instance_id" : "d1060faf0d3743dd8830b39e7423bc9ain14",
"instance_name" : "hly-0609-02",
"instance_status" : "normal",
"actions" : [ "STREAM_DISASTER_RELATION_MASTER_TAG" ]
} ]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 148
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.6.3 搭建容灾关系
功能介绍
搭建容灾关系。
两地三中心添加流灾备实例也将调用此接口。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
从主实例端下发。
支持数据库版本大于等于3.209。
两地三中心场景下仅支持数据库版本大于等于3.209。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/construct
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
9089bbf7377442daa55bc28d514c08bdin14/disaster-recovery/construct
● 参数说明
表 4-182 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 149
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-183 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream：代表流式容灾
● dorado：代表Dorado
容灾
dr_ip 是 String 对端实例任意数据ip。
dr_user_name 是 String 对端实例账户名称。
dr_user_passwor 是 String 对端实例账户密码。
d
– 请求示例
{
"disaster_type" : "stream",
"dr_ip" : "127.0.0.1",
"dr_user_name" : "root",
"dr_user_password" : "password"
}
响应消息
表 4-184 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 150
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.6.4 备实例容灾升主
功能介绍
容灾升主（failover），灾备实例端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
在灾备region下发。
支持数据库版本大于等于3.209。
两地三中心场景下仅支持数据库版本大于等于3.209。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/failover
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
c04c789b6baa4b6dbcc139c5226f3a2cin14/disaster-recovery/failover
● 参数说明
表 4-185 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
表 4-186 参数说明
名称 是否必选 参数类型 说明
is_support_restore 否 Boolean 是否支持容灾回切(仅支持数
据库版本大于等于3.200)
● true支持
● false不支持(默认false)
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 151
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
● dorado
● 正常响应样例
{
"is_support_restore": true,
"disaster_type": "stream"
}
响应消息
表 4-187 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.5 解除容灾关系
功能介绍
解除容灾关系，从容灾主实例端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 152
云数据库 GaussDB
API 参考 4 API（推荐）
约束限制
● 仅支持从主Region下发解除容灾关系操作。
● 两地三中心场景下，主实例A和同城备实例B和异地备实例C搭建容灾关系，不能
在异地集群C为主的情况下，下发解除容灾操作，需要在异地集群C降备后才能解
除。
● 主实例A和备实例B搭建容灾关系，在备实例B进行容灾演练场景时，禁止在主实
例A下发容灾解除操作。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/release
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
c04c789b6baa4b6dbcc139c5226f3a2cin14/disaster-recovery/release
● 参数说明
表 4-188 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-189 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
● dorado
– 请求示例
{
"disaster_type" : "stream"
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 153
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
表 4-190 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.6 灾备实例主从切换
功能介绍
灾备实例主从切换（switchover），可在主备任意一端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
支持数据库版本大于等于3.209。
两地三中心场景下仅支持数据库版本大于等于3.209。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/switchover
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/instances/c04c789b6baa4b6dbcc139c5226f3a2cin14/
disaster-recovery/switchover
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 154
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-191 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-192 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
● dorado
– 请求示例
{
"disaster_type" : "stream"
}
响应消息
表 4-193 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 155
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.7 重建容灾关系
功能介绍
流容灾备升主选择支持容灾回切，实现容灾关系的重建任务。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
支持数据库版本大于等于3.209。
两地三中心场景下仅支持数据库版本大于等于3.209。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/restore
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/restore
● 参数说明
表 4-194 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 156
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-195 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
● dorado
– 请求示例
{
"disaster_type" : "stream"
}
响应消息
表 4-196 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.8 开启容灾演练
功能介绍
灾备实例开始容灾演练。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 157
云数据库 GaussDB
API 参考 4 API（推荐）
演练开启后，主实例会对增量数据进行暂存，此处可以指定保留增量数据大小的上限
值，演练结束后，备实例可以根据暂存的增量数据进行增量回放。如果增量数据超过
此处设定值，演练结束后备实例会进行全量数据回放。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
仅支持数据库版本大于等于3.209的实例。
两地三中心场景下不支持此接口。
URI
● URI格式
POST
https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/disaster-
recovery/simulation-start
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/simulation-start
● 参数说明
表 4-197 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-198 参数说明
名称 是否必选 参数类型 说明
xlog_keep_ratio 否 Integer 灾备实例该字段不生效，主
实例默认10：
● 日志保留空间占可使用
剩余磁盘容量的比例, 可
设置范围为1-99。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 158
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
– 请求示例
{
"xlog_keep_ratio":50,
"disaster_type" : "stream"
}
响应消息
表 4-199 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.9 结束容灾演练
功能介绍
灾备实例结束容灾演练。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 159
云数据库 GaussDB
API 参考 4 API（推荐）
约束限制
仅支持数据库版本大于等于3.209的实例。
两地三中心场景下不支持此接口。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/simulation-stop
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/simulation-stop
● 参数说明
表 4-200 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-201 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
– 请求示例
{
"disaster_type" : "stream"
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 160
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
表 4-202 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.10 开启日志保持
功能介绍
主实例开始容灾日志保持。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
仅支持数据库版本大于等于3.209的实例。
两地三中心场景下不支持此接口。
URI
● URI格式
POST
https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/disaster-
recovery/keep-log-start
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/keep-log-start
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 161
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-203 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-204 参数说明
名称 是否必选 参数类型 说明
xlog_keep_ratio 否 Integer 主实例默认10：
● 日志保留空间占可使用
剩余磁盘容量的比例, 可
设置范围为1-99。
disaster_type 是 String 容灾类型。
枚举值：
● stream
– 请求示例
{
"xlog_keep_ratio":50,
"disaster_type" : "stream"
}
响应消息
表 4-205 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 162
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.11 结束日志保持
功能介绍
主实例结束容灾日志保持。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
仅支持数据库版本大于等于3.209的实例。
两地三中心场景下不支持此接口。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/keep-log-stop
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/keep-log-stop
● 参数说明
表 4-206 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 163
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-207 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
– 请求示例
{
"disaster_type" : "stream"
}
响应消息
表 4-208 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.12 重置容灾配置
功能介绍
重置容灾网络等配置。
1. 将自动“创建委托”以授权DBS云服务访问VPC资源信息、查询IAAS接口。
2. 重置实例容灾网络等配置。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 164
云数据库 GaussDB
API 参考 4 API（推荐）
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/reset-
dr-config
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
reset-dr-config
● 参数说明
表 4-209 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
无
响应消息
无
● 正常响应样例
无
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 165
云数据库 GaussDB
API 参考 4 API（推荐）
4.7 任务管理
4.7.1 获取任务信息
功能介绍
获取指定任务ID的任务信息。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/jobs?id={id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/jobs?
id=5cbb8a90-2253-4cff-8a13-49aa8f31dfb5
● 参数说明
表 4-210 请求参数
名称 类型 是否必 描述
选
project_id string 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
id string 是 任务ID。支持通过API接口（除“应用参数模
板”、“增备任务”以外的）返回的异步任
务id查询任务结果。
请求消息
无
响应消息
● 正常响应参数说明
表 4-211 参数说明
名称 参数类型 描述
job Object 任务信息，请参见表job字段数据结
构说明。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 166
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-212 job 字段数据结构说明
名称 参数类型 描述
id String 任务ID。
name String 任务名称。
status String 任务执行状态。
取值：
● 值为“Running”，表示任务正在
执行。
● 值为“Completed”，表示任务执
行成功。
● 值为“Failed”，表示任务执行失
败。
created String 创建时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区
偏移量。
ended String 结束时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区
偏移量。
progress String 任务执行进度。
说明
执行中状态才返回执行进度，例如
“60%”，表示任务执行进度为60%，否
则返回“”。
instance Object 执行任务的实例信息。
请参见表4-213。
fail_reason String 任务执行失败时的错误信息。
表 4-213 instance 字段数据结构说明
名称 参数类型 描述
id String 实例ID。
name String 实例名称。
● 正常响应样例
参数模板列表：
{
"job" : {
"id" : "5cbb8a90-2253-4cff-8a13-49aa8f31dfb5",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 167
云数据库 GaussDB
API 参考 4 API（推荐）
"name" : "CreateGaussDBV5Instance",
"status" : "Completed",
"created" : "2021-07-12T09:22:04+0800",
"ended" : "2021-07-12T10:10:13+0800",
"progress" : "",
"instance" : {
"id" : "b34f8c791f2643578510c093aa2351a8in14",
"name" : "gauss-c1a3"
},
"fail_reason" : null
}
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 168
云数据库 GaussDB
API 参考 5 历史 API
5 历史 API
5.1 实例管理
5.1.1 创建数据库实例
功能介绍
创建GaussDB实例。GaussDB支持创建和主备版实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/opengauss/v3/{project_id}/instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
opengauss/v3/054ea741f700d4a32f1bc00f5c80dd4c/instances
● 参数说明
表 5-1 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项
目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 169
云数据库 GaussDB
API 参考 5 历史 API
请求消息
表 5-2 参数说明
名称 是否必 参数类型 说明
选
name 是 String 实例名称。
用于表示实例的名称，同一租户下，同类型
的实例名可重名。
取值范围：4~64个字符之间，必须以字母
开头，区分大小写，可以包含字母、数字、
中划线或者下划线，不能包含其他的特殊字
符。
datastore 是 Object 数据库信息。
详情请参见表5-3。
ha 是 Object 实例部署形态。详情请参见表5-4。
configuration_i 否 String 参数模板ID。当不传该参数时，使用系统默
d 认的参数模板。
port 否 String 数据库端口信息。
GaussDB数据库端口当前只支持设置为
8000，当不传该参数时，默认端口为
8000。
password 是 String 数据库密码。
GaussDB密码取值范围:
非空； 至少包含大写字母（A-Z），小写字
母（a-z），数字（0-9），非字母数字字符
（限定为~!@#%^*-_=+?,）四类字符中的三
类字符；长度8~32个字符。
建议您输入高强度密码，以提高安全性，防
止出现密码被暴力破解等安全风险。
backup_strateg 否 Object 备份策略。
y 详情请参见表5-5。
flavor_ref 是 String 规格码，取值范围：非空。参考数据库实例
规格中GaussDB的“规格编码”列内容获
取。
volume 是 Object volume信息。
详情请参见表5-6。
region 是 String 区域ID。
取值范围：非空，请向企业管理员获取。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 170
云数据库 GaussDB
API 参考 5 历史 API
名称 是否必 参数类型 说明
选
availability_zon 是 String 可用区ID。
e GaussDB取值范围：非空，可选部署在同一
可用区或三个不同可用区，可用区之间用逗
号隔开。详见示例。
● 部署在同一可用区：需要输入三个相同
的可用区。
● 部署在三个不同可用区：需要分别输入
三个不同的可用区。
取值范围：非空，请向企业管理员获取。
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界
面，在虚拟私有云的详情页面查找VPC
ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询VPC列表”的内容。
subnet_id 是 String 子网的网络ID信息，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界
面，单击VPC下的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询子网列表”的内容。
security_group_ 是 String 指定实例所属的安全组。
id ● 方法1：登录虚拟私有云服务的控制台界
面，在安全组的详情页面查找安全组
ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询安全组列表”的内
容。
charge_info 否 Object 计费类型信息，仅支持按需。
详情请参见表5-7。
time_zone 否 String UTC时区。
● 不选择时，GaussDB默认为UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且只支持整段
时间，如UTC+08:00，不支持UTC
+08:30。
solution 是 String GaussDB支持的部署模式，当前可选的有
triset。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 171
云数据库 GaussDB
API 参考 5 历史 API
表 5-3 datastore 字段数据结构说明
名称 是 参数类型 说明
否
必
选
type 是 String 数据库引擎，取值如下：
GaussDB。
version 否 String 数据库版本。不填时，默认为当前最新版
本。
GaussDB支持如下版本：
● 1.4
● 2.3
表 5-4 ha 字段数据结构说明
名称 是 参数类型 说明
否
必
选
mode 是 String GaussDB当前只支持主备模式，取值：
ha(solution为triset时选择) ，不区分大小
写。
replication_mode 是 String 备机同步参数。
取值：
GaussDB为“sync"
说明
“sync”为同步模式。
consistency 是 String 指定事务一致性类型，取值范围：strong
（强一致性） | eventual(最终一致性)，不
分区大小写。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 172
云数据库 GaussDB
API 参考 5 历史 API
表 5-5 backup_strategy 字段数据结构说明
名称 是 参数类型 说明
否
必
选
start_time 是 String 备份时间段。自动备份将在该时间段内触
发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值必须
为00、15、30或45。
取值示例：
● 08:15-09:15
● 23:00-00:00
keep_days 否 Integer 指定备份文件的可保存天数。
取值范围：1～732。该参数缺省时，默认
填写为7天。
表 5-6 volume 字段数据结构说明
名称 是否 参数类型 说明
必选
type 是 String 磁盘类型。
仅支持LOCALSSD，区分大小写，表示本
地SSD盘。
size 是 Integer 磁盘大小。例如：该参数填写为“40”，
表示为创建的实例分配40GB的磁盘空间。
MCS部署方案：取值范围：（分片数
*40GB）~（分片数*16TB），且大小只能
为分片数*40的整数倍。
BMS部署方案：该参数由所选择的规格自
动计算，不可指定，即使填写，也不会生
效。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 173
云数据库 GaussDB
API 参考 5 历史 API
表 5-7 chargeInfo 字段数据结构说明
名称 是 参数类型 说明
否
必
选
charge_mode 是 String 计费模式。仅支持postPaid，后付费，即
按需付费。
● 请求样例
创建主备版实例：
{
"name": "user_v3_ha_01",
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.3"
},
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"volume": {
"type": "LOCALSSD",
"size": "120"
},
"region": "sa-fb-1",
"availability_zone": "az4.dc0,az4.dc0,az4.dc0",
"vpc_id": "c0a17a45-5e4a-4166-9cd6-cf9846f776a2",
"subnet_id": "ba239f09-7b59-4233-80c9-af2b418803ae",
"security_group_id": "093807ac-4d7a-44c6-b554-b3460dab50cf",
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 7
},
"charge_info": {
"charge_mode": "postPaid"
},
"password": "******",
"configuration_id": "26f22545846040d1a02163a068b6b3a3pr14",
"enterprise_project_id": "",
"time_zone": "UTC+08:00",
"ha":{
"mode":"ha",
"consistency":"strong",
"replication_mode":"sync"
},
"port": "8000",
"solution": "triset"
}
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 174
云数据库 GaussDB
API 参考 5 历史 API
表 5-8 要素说明
名称 参数类型 说明
instance Object 实例信息。
详情请参见表5-9。
job_id String 实例创建的任务id。
仅创建按需实例时会返回该参数。
表 5-9 instance 说明
名称 参数类型 说明
id String 实例id。
name String 实例名称。用于表示实例的名称，同一
租户下，同类型的实例名称可相同。
取值范围：4~64个字符之间，必须以
字母开头，不区分大小写，可以包含字
母、数字、中划线或者下划线，不能包
含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
仅创建按需实例时会返回该参数。
datastore Object 数据库信息。
详情请参见表5-10。
ha Object 数据库部署形态。
详情请参见表5-11。
replica_num Integer 实例副本数。
port String 数据库端口信息，与请求参数相同。
backup_strategy Object 自动备份策略。
详情请参见表5-12。
flavor_ref String 规格码，取值范围：非空。参考数据库
实例规格中GaussDB的“规格编码”列
内容获取。
volume Object volume信息。
详情请参见表5-13。
region String 区域ID。
availability_zone String 可用区ID。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 175
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
security_group_id String 实例所属的安全组。
charge_info Object 付费方式信息，仅支持按需。
详情请参见表5-14。
表 5-10 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎，返回值如下：
GaussDB
version String 数据库版本。
表 5-11 ha 字段数据结构说明
名称 参数类型 说明
mode String GaussDB当前只支持主备模式，取值：
ha(solution为triset时选择) ，不区分大小
写。
replication_ String 备机同步参数。
mode 取值：
● GaussDB为“sync”。
说明
● “sync”为同步模式。
consistency String GaussDB的预留参数：指定事务一致性类
型，取值范围：strong（强一致性） |
eventual(最终一致性)。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 176
云数据库 GaussDB
API 参考 5 历史 API
表 5-12 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内
触发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值必
须为00、15、30或45。
取值示例：
● 08:15-09:15
● 23:00-00:00
如果请求体中不填写
“backup_strategy”字段，则响应体中
“start_time”默认返回
“02:00-03:00”。
keep_days Integer 指定已生成备份文件的可保存天数。
取值范围：1～732。如果请求体中不填
写“backup_strategy”字段，则响应体
中 “keep_days”默认返回“7”。
表 5-13 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
取值如下，区分大小写：
● LOCALSSD，表示本地SSD盘。
size Integer 磁盘大小。
GaussDB分布式实例创建时需指定大
小：要求必须为（分片数 * 40GB）的倍
数，取值范围：（分片数*40GB）~（分
片数*16TB）。
表 5-14 chargeInfo 字段数据结构说明
名称 参数类型 说明
charge_mode String 创建类型，支持按需。
● 正常响应样例
{
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 177
云数据库 GaussDB
API 参考 5 历史 API
"instance": {
"id": "2afb68bc983742308f7a878581762a49in14",
"name": "user_v3_ha_01",
"status": "BUILD",
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.3"
},
"ha": {
"mode": "ha",
"replication_mode": "sync",
"consistency": "strong"
},
"port": "8000",
"volume": {
"type": "LOCALSSD",
"size": 120
},
"region": "sa-fb-1",
"replica_num": 3,
"configuration_id": "26f22545846040d1a02163a068b6b3a3pr14",
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 0
},
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"availability_zone": "az3.dc0,az3.dc0,az3.dc0",
"vpc_id": "aaefc937-c12e-449a-9907-604827337999",
"subnet_id": "ebeaece0-c16c-42aa-a546-0d42d0c68956",
"security_group_id": "290af3b6-289b-4014-a336-b98da9c4fa8e",
"charge_info": {
"charge_mode": "postPaid"
}
},
"job_id": "d7b73e60-4237-43d0-9007-097b7678495d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.1.2 删除数据库实例
功能介绍
删除数据库实例。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 178
云数据库 GaussDB
API 参考 5 历史 API
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/opengauss/v3/{project_id}/instances/{instance_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in01
● 参数说明
表 5-15 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项
目ID/名称。
instance_id 是 实例ID。
请求消息
无
响应消息
● 正常响应要素说明
表 5-16 要素说明
名称 参数类型 说明
job_id String 实例删除的任务id
● 正常响应样例：
{
"job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 179
云数据库 GaussDB
API 参考 5 历史 API
请参见状态码。
错误码
请参见错误码。
5.1.3 查询数据库实例列表
功能介绍
根据指定条件查询实例列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/opengauss/v3/{project_id}/instances?
id={id}&name={name}&type={type}&datastore_type={datastore_type}&vpc_id
={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit}
● URI样例
– 查询所有实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
opengauss/v3/97b026aa9cc4417888c14c84a1ad9860/instances
– 根据指定条件查询实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/97b026aa9cc4417888c14c84a1ad9860/instances?
id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datast
ore_type=GaussDB&vpc_id=19e5d45d-70fd-4a91-87e9-
b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offs
et=0&limit=10
● 参数说明
表 5-17 参数说明
名称 参数类 是否 说明
型 必选
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
id String 否 实例ID。
“*”为系统保留字符，如果id是以“*”起
始，表示按照*后面的值模糊匹配，否则，按
照id精确匹配查询。不能只传入“*”。
name String 否 实例名称。
“*”为系统保留字符，如果name是以“*”
起始，表示按照*后面的值模糊匹配，否则，
按照name精确匹配查询。不能只传入“*”。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 180
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类 是否 说明
型 必选
type String 否 按照实例类型查询。当前支持取值"Ha"（区
分大小写），对应主备式实例。
datastore_ String 否 数据库类型，不区分大小写。
type GaussDB
vpc_id String 否 虚拟私有云ID。
● 方法1：登录虚拟私有云服务的控制台界
面，在虚拟私有云的详情页面查找VPC
ID。
● 方法2：获取方法请参见《虚拟私有云
(VPC) 使用指南》的API参考中“查询VPC
列表”的内容。
subnet_id String 否 子网的网络ID信息。
● 方法1：登录虚拟私有云服务的控制台界
面，单击VPC下的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚拟私有云
(VPC) 使用指南 》的API参考中“查询子
网列表”的内容。
offset Integer 否 索引位置，偏移量。从第一条数据偏移offset
条数据后开始查询，默认为0（偏移0条数
据，表示从第一条数据开始查询），必须为数
字，不能为负数。
limit Integer 否 查询记录数。默认为100，不能为负数，最小
值为1，最大值为100。
请求消息
无。
响应消息
● 正常响应要素说明
表 5-18 参数说明
名称 参数类型 说明
instances Array of objects 实例信息。
详情请参见表5-19。
total_count Integer 总记录数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 181
云数据库 GaussDB
API 参考 5 历史 API
表 5-19 instances 字段数据结构说明
名称 参数类型 说明
id String 实例ID。
name String 创建的实例名称。
status String 实例状态。
取值：
值为“BUILD”，表示实例正在创建。
值为“ACTIVE”，表示实例正常。
值为“FAILED”，表示实例异常。
值为“EXPANDING”，表示实例正在
扩容。
值为“REBOOTING”，表示实例正在
重启。
值为“UPGRADING”，表示实例正在
升级。
值为“RESTORING”，表示实例正在恢
复。
值为“BACKING UP”，表示实例正在
进行备份。
值为“STORAGE FULL”，表示实例磁
盘空间满。
private_ips List<String> 实例内网IP地址列表。CN在的弹性云服
务器创建成功后该值存在，其他情况下
为空字符串。
port Integer 数据库端口号。GaussDB数据库端口当
前只允许为8000。
当不传该参数时，默认端口如下：
8000。
type String 实例类型，取值为"Ha"，对应于主备版
实例。
ha Object 获取分布式实例时返回。
详情请参见表5-20。
region String 实例所在区域。
datastore Object 数据库信息。
详情请参见表5-21。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 182
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
created String 创建时间，格式为“yyyy-mm-dd
hh:mm:ss timezone”。
其中timezone是指时区。
说明：创建时该值为实例下发创建的时
间，创建完成后，该值为创建完成时
间。
updated String 更新时间，格式与“created”字段对应
格式完全相同。
说明：创建时返回值为空，数据库实例
创建成功后该值不为空。
db_user_name String 默认用户名。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
security_group_ String 安全组ID。
id
flavor_ref String 规格码。参考数据库实例规格中
GaussDB的“规格编码”列内容获取。
flavor_info Object 规格信息。
详情请参见表5-22
volume Object Volume信息。
详情请参见表5-23。
backup_strateg Object 备份策略。
y 详情请参见表5-24。
maintenance_w String 可维护时间窗，为UTC时间。
indow
nodes Array of objects 实例节点信息。
详情请参见表5-25。
related_instanc Array of objects 所关联的数据库实例列表。GaussDB不
e 涉及该参数。
instance_mode String enterprise为企业版
time_zone String 时区。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 183
云数据库 GaussDB
API 参考 5 历史 API
表 5-20 ha 字段数据结构说明
名称 参数类型 说明
consistency String 事务一致性类型。取值为“strong”、
“eventual”，分别表示强一致性、最终
一致性。
replication_mo String 备机同步参数。
de 取值：非空。
GaussDB为 “sync”
说明
“sync”为同步模式。
表 5-21 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎。
version String 数据库版本。
表 5-22 flavor_info 字段数据结构说明
名称 参数类型 说明
vcpu Integer cpu核数。
mem Integer 内存大小。
表 5-23 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
size Integer 磁盘大小。
表 5-24 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内触
发。
当前时间指UTC时间。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 184
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
keep_days Integer 已生成的备份文件可以保存的天数。
取值范围：0～732。为0时，表示未设置
自动备份策略或备份策略已关闭。
表 5-25 nodes 字段数据结构说明
名称 参数类型 说明
id String 节点ID。
name String 节点名称。
role String 节点类型，取值为“master”、
“slave”，分别对应于主节点、备节点。
status String 节点状态。
availability_zon String 可用区。
e
● 正常响应样例
实例列表：
{
"instances": [
{
"id": "b331ed66cc3249f78bc20737308c01f4in14",
"status": "ACTIVE",
"name": "gauss-9e88",
"port": 8000,
"type": "enterprise",
"ha": {
"consistency": "strong",
"replication_mode": "sync"
},
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.4"
},
"created": "2021-01-15 01:46:40 UTC",
"updated": "2021-01-15 02:05:03 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 120
},
"nodes": [
{
"id": "02ebf757aaf94074855f49cc6e0e4712no14",
"name": "gauss-9e88_gaussdbv5cn_2",
"role": "master",
"status": "ACTIVE",
},
{
"id": "0a87b8ecbfeb46aba1409cfc0f0d5c34no14",
"name": "gauss-9e88_gaussdbv5cn_0",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 185
云数据库 GaussDB
API 参考 5 历史 API
"role": "master",
"status": "ACTIVE",
},
{
"id": "2d9fec1ab3834936b074d63acf48b1f2no14",
"name": "gauss-9e88_gaussdbv5dn3_2",
"role": "master",
"status": "ACTIVE",
},
{
"id": "48bb08a2d635435891ac0caa1c0bf2e3no14",
"name": "gauss-9e88_gaussdbv5dn1_0",
"role": "master",
"status": "ACTIVE",
},
{
"id": "5df830f652204827ada32f8bc28b107eno14",
"name": "gauss-9e88_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "8a97a246cee841b38c5b47290d4c9c38no14",
"name": "gauss-9e88_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
},
{
"id": "8c1a3f8eecca4d9e9974a868bb6dd942no14",
"name": "gauss-9e88_gaussdbv5dn2_0",
"role": "master",
"status": "ACTIVE",
},
{
"id": "9bd0c80b8a684cc9bd7d99dd5adffb07no14",
"name": "gauss-9e88_gaussdbv5dn3_1",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "9e2a3cd541e249d4af5aa57c5d3a7f39no14",
"name": "gauss-9e88_gaussdbv5dn1_2",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "b046d28989ec4ae5a1a9ab20fe65f248no14",
"name": "gauss-9e88_gaussdbv5dn2_2",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "b614cc12fd3742dbb230245f88a7bf00no14",
"name": "gauss-9e88_gaussdbv5dn3_0",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "caba8e88c3c84ae58202f1f589490611no14",
"name": "gauss-9e88_gaussdbv5dn2_1",
"role": "slave",
"status": "ACTIVE",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 186
云数据库 GaussDB
API 参考 5 历史 API
}
],
"private_ips": [
"192.168.28.81 / 192.168.27.52 / 192.168.16.253"
],
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "prePaid"
},
"backup_strategy": {
"start_time": "19:00-20:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "6e76681b-a2f5-4c5f-97c5-ba4fd3c0dfb2",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
"order_id": "CS2101150917EUW8N"
},
{
"id": "226b4afcfcc84c86bf1b9cb345d3b00fin14",
"status": "ACTIVE",
"name": "UTS-gauss-ad53-2C3D",
"port": 8000,
"type": "enterprise",
"ha": {
"consistency": "strong",
"replication_mode": "sync"
},
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"created": "2021-01-08 09:18:27 UTC",
"updated": "2021-01-14 13:25:03 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 120
},
"nodes": [
{
"id": "07538a1def584cee99e2a5685eeab36ano14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "21f41baba1e2454f82331b7cb5aeabe5no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 187
云数据库 GaussDB
API 参考 5 历史 API
{
"id": "2909771a3b3e4e3998f9388e77d22391no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "2bd9a90a5da242a6b0743a7f597f6106no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "77092f1dadb74d3ea13d28269cdd3590no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "a46bfaa6d5a24355a60fce7432b964cano14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "aa5277736f3844e2a7adeb9de529e2b1no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b1d798e4ea7344dfa95032984bc6cfd7no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b9a46540186f4c0781eabaa2a79594cbno14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "d283813030364060ab64371d50294977no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "eb7bce29b2284cd290405eaddc1b1a1eno14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_0",
"role": "master",
"status": "FAILED",
"availability_zone": "az2xahz"
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 188
云数据库 GaussDB
API 参考 5 历史 API
}
],
"private_ips": [
"192.168.30.44 / 192.168.29.231"
],
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "prePaid"
},
"backup_strategy": {
"start_time": "18:00-19:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
},
{
"id": "706c65c3dd7d497ab16f5b3a113690abin14",
"status": "ACTIVE",
"name": "UTS-gauss-7362",
"port": 8000,
"type": "enterprise",
"ha": {
"replication_mode": "sync"
},
"region": "cn-xianhz-1",
"datastore": {
"type": "GaussDB",
"version": "1.2"
},
"created": "2020-12-23 03:21:41 UTC",
"updated": "2021-01-15 02:32:13 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 80
},
"nodes": [
{
"id": "25b7f16ee4084b7884d52f1bdfab4e68no14",
"name": "UTS-gauss-7362_gaussdbv5dn1_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "ad6f02f31744422fa8ce487e81c9e7afno14",
"name": "UTS-gauss-7362_gaussdbv5cn_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 189
云数据库 GaussDB
API 参考 5 历史 API
{
"id": "b30c56582bf44a548e3bb5b5af6c4773no14",
"name": "UTS-gauss-7362_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "f79ea0600cba42b2888bd9bd67e52a79no14",
"name": "UTS-gauss-7362_gaussdbv5dn1_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
}
],
"private_ips": [
"192.168.26.70"
],
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "postPaid"
},
"backup_strategy": {
"start_time": "16:00-17:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
},
{
"id": "4ad42d079a3948d88c28d6236211b21ein14",
"status": "ACTIVE",
"name": "UTS-gauss-4336",
"port": 8000,
"type": "enterprise",
"ha": {
"replication_mode": "sync"
},
"region": "cn-xianhz-1",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"created": "2020-12-03 14:28:53 UTC",
"updated": "2021-01-14 13:20:10 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 40
},
"nodes": [
{
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 190
云数据库 GaussDB
API 参考 5 历史 API
"id": "254dbda6f03643519ad64b39481bd11cno14",
"name": "UTS-gauss-4336_gaussdbv5dn1_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az1xahz"
},
{
"id": "6ad76d4db26443c2a93b280739a31558no14",
"name": "UTS-gauss-4336_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az1xahz"
},
{
"id": "9fdebf821bdf444a8689b19c0ff588ceno14",
"name": "UTS-gauss-4336_gaussdbv5cn_0",
"role": "master",
"status": "FAILED",
"availability_zone": "az1xahz"
},
{
"id": "dd64bdbc02a542d88823b1582f772d25no14",
"name": "UTS-gauss-4336_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az1xahz"
},
{
"id": "de3c41461045466faf6c2b96eb709540no14",
"name": "UTS-gauss-4336_gaussdbv5dn1_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az1xahz"
}
],
"private_ips": [
"192.168.30.93 / 192.168.29.232"
],
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "postPaid"
},
"backup_strategy": {
"start_time": "18:00-19:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
}
],
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 191
云数据库 GaussDB
API 参考 5 历史 API
"total_count": 4
}
● 实例详情：
{
"instances": [
{
"id": "bab2fb1fc43a4b3e9c288fef9cd60b69in14",
"status": "BUILD",
"name": "user_v3_ha_01",
"port": 8000,
"type": "Ha",
"ha": {
"consistency": "strong",
"replication_mode": "sync"
},
"region": "sa-fb-1",
"datastore": {
"type": "GaussDB(for opengauss)",
"version": "1.4"
},
"created": "2021-03-02 09:30:30 UTC",
"updated": "2021-03-14 13:20:00 UTC",
"volume": {
"type": "LOCALSSD",
"size": 120
},
"nodes": [
{
"id": "2d4f4215ef27453daf8b144c32ac3a9dno14",
"name": "user_v3_ha_01_root_2",
"role": "slave",
"status": "FAILED",
"availability_zone": "az4.dc0"
},
{
"id": "9a6645a190134f61884be0cb450143dbno14",
"name": "user_v3_ha_01_root_0",
"role": "master",
"status": "FAILED",
"availability_zone": "az4.dc0"
},
{
"id": "a1017382f3994b028ab1fae5dc999decno14",
"name": "user_v3_ha_01_root_1",
"role": "slave",
"status": "FAILED",
"availability_zone": "az4.dc0"
}
],
"tags": [],
"private_ips": [
"192.168.0.107 / 192.168.0.187 / 192.168.0.201"
],
"public_ips": [],
"db_user_name": "root",
"vpc_id": "c0a17a45-5e4a-4166-9cd6-cf9846f776a2",
"subnet_id": "ba239f09-7b59-4233-80c9-af2b418803ae",
"security_group_id": "093807ac-4d7a-44c6-b554-b3460dab50cf",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"flavor_info": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 192
云数据库 GaussDB
API 参考 5 历史 API
"vcpu": 8,
"mem": 64
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "postPaid"
},
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00"
"instance_mode":"enterprise"
}
],
"total_count": 1
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.1.4 同城切换 AZ
功能介绍
切换主DN组至对应AZ。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
注意事项
切换完成后，可能会导致集群主备分布不均衡，如果需要将集群重新切回均衡状态，
可以参考实例主备状态重置，将集群主备状态切回。
URI
● URI格式
POST https://{Endpoint}/opengauss/v3/{project_id}/instances/{instance_id}/
switch-az
● URI样例
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 193
云数据库 GaussDB
API 参考 5 历史 API
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/switch-az
● 参数说明
表 5-26 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 5-27 参数说明
名称 是否必选 参数类型 说明
availability_zone 是 String 需要将主DN切换到的AZ。
● 请求样例
{
"availability_zone": "az3.dc0"
}
响应消息
● 正常响应要素说明
表 5-28 要素说明
名称 参数类型 说明
job_id String 同城切换AZ的任务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 194
云数据库 GaussDB
API 参考 5 历史 API
● 异常
请参见状态码。
错误码
请参见错误码。
5.1.5 实例主备状态重置
功能介绍
将数据库实例恢复为初始配置的主备状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 实例在创建、变更规格、异常等状态下不能执行该操作。
● 该功能不支持1.x版本的主备版实例。
URI
● URI格式
PUT https://{Endpoint}/opengauss/v3/{project_id}/instances/{instance_id}/
rebalance
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/rebalance
表 5-29 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。在实例详情页获取。
请求消息
无。
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 195
云数据库 GaussDB
API 参考 5 历史 API
响应参数
表 5-30 要素说明
参数 参数类型 描述
job_id String 任务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.1.6 查询实例主备平衡状态
功能介绍
查询实例是否发生过主备切换而导致主机负载不均衡。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/opengauss/v3/{project_id}/instances/{instance_id}/
balance
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/balance
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 196
云数据库 GaussDB
API 参考 5 历史 API
表 5-31 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
无。
响应消息
● 正常响应要素说明
表 5-32 要素说明
名称 参数类型 说明
balanced boolean 平衡状态。显示是否有
集群实例发生过主备切
换而导致主机负载不均
衡。
● 返回"true"，均衡。
● 返回"false"，不均
衡。
● 正常响应样例
{
"balanced": true
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 197
云数据库 GaussDB
API 参考 5 历史 API
5.2 备份管理
5.2.1 查询备份列表
功能介绍
获取备份列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
该接口仅支持查询GaussDB的手动全量备份及自动全量备份。
URI
● URI格式
GET https://{Endpoint}/opengauss/v3/{project_id}/backups?
instance_id={instance_id}&backup_id={backup_id}&backup_type={backup_typ
e}&offset={offset}&limit={limit}&begin_time={begin_time}&end_time={end_ti
me}
● URI样例
– 查询所有备份列表
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups
– 根据指定条件查询实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0483b6b16e954cb88930a360d2c4e663/backups?
instance_id=88be33e4c5a64ceba42b42da89310111in14&backup_id=88be1234
c5a64ceba42b42da89310111br14&backup_type=auto&begin_time=2022-05-0
9T16:15:50+0800&end_time=2022-05-09T16:20:45+0800&limit=1&offset=1
● 参数说明
表 5-33 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 否 String 实例ID。
backup_id 否 String 备份ID，严格匹配UUID规
则。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 198
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
backup_type 否 String 备份类型，取值范围：
● auto 自动全量备份
● manual 手动全量备份
● Snapshot_Xbsa xbsa 手动
全量备份
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。
最小值：0
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。
最小值：1
最大值：100
begin_time 否 String 查询开始时间，格式为
“yyyy-mm-
ddThh:mm:ssZ”。其中，T指
某个时间的开始；Z指时区偏
移量。与end_time必须同时使
用。
end_time 否 String 查询结束时间，格式为
“yyyy-mm-
ddThh:mm:ssZ”，且大于查
询开始时间。其中，T指某个
时间的开始；Z指时区偏移
量。与begin_time必须同时使
用。
请求消息
无。
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 199
云数据库 GaussDB
API 参考 5 历史 API
表 5-34 参数说明
参数 参数类型 描述
backups Array of 备份信息。
objects 详情请参见表5-35。
total_count Long 备份文件的总数。
表 5-35 backups 字段数据结构说明
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
description String 备份文件描述信息。
begin_time String 备份开始时间，格式为"yyyy-mm-
ddThh:mm:ssZ"。 其中，T指某个时间的开
始；Z指时区偏移量。
end_time String 备份结束时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。 其中，T指某个时间的开
始；Z指时区偏移量。
status String 备份状态
枚举值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
size Double 备份大小(单位：MB)。
type String 备份类型
取值：
● auto：自动全量备份。
● manual：手动全量备份。
datastore Object 数据库信息。
详情请参见表5-36
instance_id String 实例ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 200
云数据库 GaussDB
API 参考 5 历史 API
表 5-36 datastore 字段数据结构说明
参数 参数类型 描述
type String 数据库引擎，不区分大小写，取值如下：
GaussDB。
version String 数据库版本。不填时，默认为当前最新版本。
● 正常响应样例
{
"backups": [
{
"id": "a696cd25e4fc453aa503650225cece8bbr14",
"name": "GaussDB-hly-ha-20220509080110906",
"description": null,
"status": "FAILED",
"size": 0.0,
"type": "auto",
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.4"
},
"begin_time": "2022-05-09T16:01:10+0800",
"end_time": "2022-05-09T16:04:31+0800",
"instance_id": "164abc6d35114095bb849d007b19db3bin14"
},
{
"id": "5651c62a7f12461c98020dd3abfe24ccbr14",
"name": "GaussDB-hly-master-20220509022658257",
"description": null,
"status": "FAILED",
"size": 0.0,
"type": "auto",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"begin_time": "2022-05-09T10:26:58+0800",
"end_time": "2022-05-09T10:30:17+0800",
"instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
}
],
"total_count": 167
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 201
云数据库 GaussDB
API 参考 5 历史 API
错误码
请参见错误码。
5.2.2 创建手动备份
功能介绍
创建手动备份。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/opengauss/v3/{project_id}/backups
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups
● 参数说明
表 5-37 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
请求消息
● 参数说明
表 5-38 参数说明
参数 是否必选 参数类型 描述
instance_id 是 String 实例ID。
name 是 String 备份名称，4~64个字符，必须
以英文字母开头，区分大小
写，可以包含英文字母、数
字、中划线或者下划线，不能
包含其他特殊字符。
最小长度：4
最大长度：64
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 202
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
description 否 String 备份描述，不能包含>!<"&'=
特殊字符，不大于256个字
符。
最大长度：256
backup_type 否 String 创建备份的类型，缺省值为
"completed" 。
取值：
● completed: 全备。
● differential: 增备。
● 请求样例
创建手动备份
{
"instance_id" : "7e01ac5ac5274957ba506f3851d11d51in14",
"name" : "backupwqwq3",
"description" : "manual backup"
}
响应消息
● 正常响应要素说明
表 5-39 响应 Body 参数
参数 参数类型 描述
backup Object 备份信息。
详情请参见表5-40
job_id String 任务ID。
表 5-40 backup 字段数据结构说明
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
description String 备份描述。
begin_time String 备份开始时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 203
云数据库 GaussDB
API 参考 5 历史 API
参数 参数类型 描述
status String 备份状态，取值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
● DELETING：备份删除中。
type String 备份类型，“manual”表示手动全量备份
instance_id String 实例ID。
● 正常响应样例
{
"backup": {
"id": "e76112bfb2074871bf54cb8df5af7f64br14",
"name": "backupwqwq32",
"description": "mannual backup",
"status": "BUILDING",
"type": "manual",
"begin_time": "2022-05-09T18:02:31+0800",
"instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
},
"job_id": "e4733090-b2c8-4ea7-a33a-f55f65723fb3"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.2.3 删除手动备份
功能介绍
删除手动备份。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/opengauss/v3/{project_id}/backups/{backup_id}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 204
云数据库 GaussDB
API 参考 5 历史 API
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups/
e28d08754b1a490fb2b3540ed013a7fbbr14
● 参数说明
表 5-41 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
backup_id 是 String 备份ID，严格匹配UUID规
则。
请求消息
无。
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.2.4 恢复到新实例
功能介绍
根据备份恢复新实例。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 205
云数据库 GaussDB
API 参考 5 历史 API
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
目标实例与源实例的数据库版本和实例类型必须一致。
目标实例规格必须大于等于源实例规格。
仅支持ECS和MCS的金融版（标准型）和1主3备形态的实例。
URI
● URI格式
POST https://{Endpoint}/opengauss/v3/{project_id}/instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0483b6b16e954cb88930a360d2c4e663/instances
● 参数说明
表 5-42 参数说明
参数 是否必选 描述
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
请求消息
表 5-43 参数说明
参数 是否必选 参数类型 描述
name 是 String 实例名称。
用于表示实例的名称，同一租户
下，同类型的实例名可重名。
取值范围：4~64个字符之间，
必须以字母开头，区分大小写，
可以包含字母、数字、中划线或
者下划线，不能包含其他的特殊
字符。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 206
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
availability_zo 是 String 可用区ID。
ne GaussDB取值范围：非空，可选
部署在同一可用区或三个不同可
用区，可用区之间用逗号隔开。
详见示例。
● 部署在同一可用区：需要输
入三个相同的可用区。
● 部署在三个不同可用区：需
要分别输入三个不同的可用
区。
取值范围：非空，请向企业管理
员获取。
flavor_ref 是 String 规格码，取值范围：非空。参考
数据库实例规格中GaussDB的
“规格编码”列内容获取。
volume 是 Object volume信息。
详情请参见表5-44
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务
的控制台界面，在虚拟私有
云的详情页面查找VPC ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
VPC列表”的内容。
subnet_id 是 String 子网的网络ID信息，获取方法如
下：
● 方法1：登录虚拟私有云服务
的控制台界面，单击VPC下
的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
子网列表”的内容。
security_grou 是 String 指定实例所属的安全组。
p_id ● 方法1：登录虚拟私有云服务
的控制台界面，在安全组的
详情页面查找安全组ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
安全组列表”的内容。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 207
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
password 是 String 数据库密码。
GaussDB密码取值范围:
非空； 至少包含大写字母（A-
Z），小写字母（a-z），数字
（0-9），非字母数字字符（限
定为~!@#%^*-_=+?,）四类字符
中的三类字符；长度8~32个字
符。
建议您输入高强度密码，以提高
安全性，防止出现密码被暴力破
解等安全风险。
charge_info 否 Object 付费方式信息，支持按需。
详情请参见表5-45。
backup_strate 否 Object 自动备份策略。
gy 详情请参见表5-47。
restore_point 是 Object 恢复数据源对象。
详情请参见表5-46。
configuration_ 否 String 参数组ID。当不传该参数时，使
id 用系统默认的参数模板。
port 否 String GaussDB数据库端口当前只支持
设置为8000，当不传该参数
时，默认端口为8000。
time_zone 否 String UTC时区。
● 不选择时，GaussDB默认为
UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且
只支持整段时间，如UTC
+08:00，不支持UTC
+08:30。
master_az 否 String 主可用区ID。取值为
availability_zone三个可用区ID
其一。当原实例存在单独的仲裁
可用区时必传，其他情况不需要
填写。
arbitration_az 否 String 仲裁可用区ID。取值为
availability_zone三个可用区ID
其一。当原实例存在单独的仲裁
可用区时必传，其他情况不需要
填写。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 208
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
xbsa_ssl_certs 否 Object xbsa证书信息。
详情请参见表5-48。
表 5-44 volume 字段数据结构说明
参数 是否必选 参数类型 描述
type 是 String 磁盘类型。
仅支持LOCALSSD，
ULTRAHIGH。
size 是 Integer 磁盘大小,需要大于等于原实
例。例如：该参数填写为
“40”，表示为恢复的实例分
配40GB的磁盘空间。
MCS部署方案：取值范围：（分
片数*40GB）~（分片数
*16TB），且大小只能为分片数
*40的整数倍。
表 5-45 charge_info 字段数据结构说明
参数 是否必选 参数类型 描述
charge_mode 是 String 计费模式。支持postPaid，后付
费，即按需付费。
表 5-46 restore_point 字段数据结构说明
参数 是否必选 参数类型 描述
instance_id 是 String 源实例ID。
backup_id 是 String 用于恢复的备份ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 209
云数据库 GaussDB
API 参考 5 历史 API
表 5-47 backup_strategy 字段数据结构说明
参数 是否必选 参数类型 描述
start_time 是 String 备份时间段。自动备份将在该时
间段内触发。
取值范围：非空，格式必须为
hh:mm-HH:MM且有效，当前
时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且
取值必须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days 否 Integer 指定备份文件的可保存天数。
取值范围：0～732，开放
“gaussdb_feature_supportCo
nsoleBackupPolicyDay_36500
”白名单后，支持备份文件最长
保留天数36500天。该参数缺省
或为0时，默认填写为30天。
表 5-48 xbsa_ssl_certs 字段数据结构说明
参数 是否必选 参数类型 描述
ca_cert_pem 是 String 根证书文件内容。base64 编
码。
client_crt 是 String 用户证书内容。base64 编码。
client_key 是 String 用户私钥内容。base64 编码。
rand_pass 是 String 私钥文件的密码。
● 请求样例
恢复实例：
{
"name": "targetInst",
"availability_zone": "aaa,bbb,ccc",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.x868.co",
"volume": {
"type": "LOCALSSD",
"size": 160
},
"vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
"subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
"security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 210
云数据库 GaussDB
API 参考 5 历史 API
"password": "******",
"restore_point": {
"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin14",
"backup_id": "2f4ddb93b9014b0893d81d2e472f30febr14"
},
"configuration_id": "52e86e87445847a79bf807ceda213165pr01",
"port": 8000,
"time_zone": "UTC+04:00",
"master_az": "aaa",
"arbitration_az": "bbb"
}
响应消息
● 正常响应要素说明
表 5-49 要素说明
参数 参数类型 描述
instance Object 实例信息。
详情请参见表5-50。
job_id String 恢复新实例的任务id。
表 5-50 instance 说明
参数 参数类型 描述
id String 实例id。
name String 实例名称。 用于表示实例的名称，同一租户
下，同类型的实例名可重名。
取值范围：4~64个字符之间，必须以字母开
头，区分大小写，可以包含字母、数字、中划
线或者下划线，不能包含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
datastore Object 数据库信息。
详情请参见表5-51
ha Object 实例部署形态。
详情请参见表5-52
port String 数据库端口信息。 当不传该参数时，默认端口
8000。
volume Object volume信息。
详情请参见表5-53
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 211
云数据库 GaussDB
API 参考 5 历史 API
参数 参数类型 描述
backup_strat Object 自动备份策略。
egy 详情请参见表5-54
replica_num Integer 实例副本数。
region String 区域ID。
flavor_ref String 规格码。
availability_z String 可用区ID。可选部署在同一可用区或三个不同
one 可用区，可用区之间用逗号隔开。
取值范围：非空，请向企业管理员获取。
vpc_id String 虚拟私有云ID。
subnet_id String 子网ID。
security_grou String 安全组ID。
p_id
charge_info Object 付费方式信息，支持按需。
详情请参见表5-55。
表 5-51 datastore 字段数据结构说明
参数 参数类型 描述
type String 数据库引擎，返回值如下： GaussDB。
枚举值：
● GaussDB。
version String 数据库版本。
表 5-52 ha 字段数据结构说明
参数 参数类型 描述
mode String GaussDB 分布式模式，返回值为：enterprise
（企业版）；主备版，返回值为：
centralization_standard(主备版)。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 212
云数据库 GaussDB
API 参考 5 历史 API
参数 参数类型 描述
replication_ String 备机同步参数。
mode 取值：
GaussDB为“sync”。
说明
“sync”为同步模式。
枚举值：
● sync
consistency String GaussDB的预留参数：指定实例一致性类型，
取值范围：strong（强一致性） | eventual(最
终一致性)。
枚举值：
● strong
● eventual
表 5-53 volume 字段数据结构说明
参数 参数类型 描述
type String 磁盘类型。
取值如下，区分大小写：
● LOCALSSD
枚举值：
● LOCALSSD
size Integer 磁盘大小。
GaussDB分布式实例恢复时需指定大小：要求
必须为（分片数 * 40GB）的倍数，取值范围：
（分片数40GB）~（分片数16TB）。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 213
云数据库 GaussDB
API 参考 5 历史 API
表 5-54 backup_strategy 字段数据结构说明
参数 参数类型 描述
start_time String 备份时间段。自动备份将在该时间段
内触发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时
间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值
必须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days Integer 指定备份文件的可保存天数。
取值范围：0～732，开放
“gaussdb_feature_supportConsoleB
ackupPolicyDay_36500”白名单后，
支持备份文件最长保留天数36500天。
该参数缺省时，默认填写为30天。
表 5-55 charge_info 字段数据结构说明
参数 参数类型 描述
charge_mode String 计费模式。支持postPaid，后付费，即按需付
费。
● 正常响应样例
{
"instance": {
"id": "2gfdsh844a4023a776fc5c5fb71fb4in14",
"name": "gaussdb-instance-rep2",
"status": "BUILD",
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.4"
},
"ha": {
"mode": "enterprise",
"consistency": "strong",
"replication_mode": "sync"
},
"volume": {
"type": "LOCALSSD",
"size": 160
},
"port": "8000",
"replica_num": 3,
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 214
云数据库 GaussDB
API 参考 5 历史 API
"region": "regionA",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.x868.co",
"availability_zone": "aaa,bbb,ccc",
"vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
"subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
"security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
"charge_info": {
"charge_mode": "postPaid"
},
},
"job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3 容灾管理（V3.1）
5.3.1 查询可搭建容灾实例列表
功能介绍
根据主实例查询可搭建容灾的实例列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/disaster/instances/
candidates
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/4a52a8a8f63d4c6d966dff0e20b69738/disaster/instances/candidates
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 215
云数据库 GaussDB
API 参考 5 历史 API
表 5-56 参数说明
名称 是否必选 参 说明
数
类
型
project_id 是 Stri 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
disaster_type 是 Stri 容灾类型，枚举值:
ng stream；
dorado；
slave_region 是 Stri 备region。
ng
slave_project_ 是 Stri 备端项目id。
id ng
master_instan 是 Stri 主实例id。
ce_id ng
limit 否 Int 查询记录数。为空时，默认为100。最
ege 小值为1，最大值为100。
r
offset 否 Int 索引位置，偏移量。从第一条数据偏移
ege offset条数据后开始查询，默认为0（偏
r 移0条数据，表示从第一条数据开始查
询），必须为数字，不能为负数。
● 请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3.1/4a52a8a8f63d4c6d966dff0e20b69738/
disaster/instances/candidates?disaster_type=&slave_region=sa-
fb-1&slave_project_id=4a52a8a8f63d4c6d966dff0e20b69738&master_instance_id=d1060faf
0d3743dd8830b39e7423bc9ain14&offset=0&limit=10
请求消息
无
响应消息
表 5-57 响应 Body 参数列表
名称 参数类型 说明
id String 主实例id。
name String 主实例名称。
total Integer 总记录数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 216
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
slave_instance Array of Object 可搭建容灾备实例列表。
_candidates
表 5-58 slave_instance_candidates 字段数据结构说明
名称 参数类型 说明
id String 实例id。
name String 实例名称。
● 正常响应样例
{
"id": "d1060faf0d3743dd8830b39e7423bc9ain14",
"name": "test-1",
"total": 1,
"slave_instance_candidates": [
{
"id": "fe55ba437e8f4e1a836c866ec7cf3f8cin14",
"name": "slave-test-1"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.2 容灾操作校验
功能介绍
容灾操作前校验操作是否可以执行。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 217
云数据库 GaussDB
API 参考 5 历史 API
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/operation-precheck
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
a7d62bf77aa04fceb52fbd57181c9e3ein14/disaster/operation-precheck
● 参数说明
表 5-59 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
● 请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3.1/4a52a8a8f63d4c6d966dff0e20b69738/
instances/234b7837d830484890f6a1e55b732401in14/disaster/operation-precheck
请求消息
● 参数说明
表 5-60 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
dest_region 是 String 对端region。
dest_instance_id 是 String 对端region实例id。
dest_project_id 是 String 对端region项目id。
operate 是 String 操作类型。
枚举值:
● construct
● switchover
● failover
● stop
● simulation_start
● simulation_end
● dr_log_keep_start
● dr_log_keep_end
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 218
云数据库 GaussDB
API 参考 5 历史 API
– 请求示例
{
"disaster_type":"stream",
"dest_region":"sa-fb-1",
"dest_instance_id":"e23ba4d51161428a8b6a0f435aff16d8in13",
"dest_project_id":"4a52a8a8f63d4c6d966dff0e20b69738",
"operate":"construct"
}
响应消息
表 5-61 响应 Body 参数列表
名称 参数类型 说明
enable Boolean 是否可操作。
deny_reason String 不可操作原因。
● 正常响应样例
{
"enable":true,
"deny_reason":""
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.3 查询容灾集群监控状态
功能介绍
查询实例搭建容灾后实时容灾状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 219
云数据库 GaussDB
API 参考 5 历史 API
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/monitor
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
a7d62bf77aa04fceb52fbd57181c9e3ein14/disaster/monitor
● 参数说明
表 5-62 参数说明
名称 是否必选 参 说明
数
类
型
project_id 是 Stri 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
instance_id 是 Stri 实例ID。
ng
dest_region 是 Stri 对端region。
ng
dest_project_i 是 Stri 对端region项目id。
d ng
dest_instance 是 Stri 对端region实例id。
_id ng
请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3.1/4a52a8a8f63d4c6d966dff0e20b69738/
instances/4d653d1caf0e4a49b4753713fac679e3in14/disaster/monitor?dest_region=sa-
fb-1&dest_project_id=4a52a8a8f63d4c6d966dff0e20b69738&dest_instance_id=d1060faf0d3
743dd8830b39e7423bc9ain14
请求消息
无
响应消息
表 5-63 响应 Body 参数列表
名称 参数类型 说明
instance_id String 实例id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 220
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
status String 容灾状态。
rpo String 数据恢复点目标。
rto String 数据恢复时间目标。
rpo_threshold String rpo阈值。
rto_threshold String rto阈值。
switchover_pro String 主从切换进度。该值为一个百分数。例
gress 如：40%
failover_progr String 容灾升主进度。该值为一个百分数。例
ess 如：40%
dest_disaster_s Object 对端region实例容灾状态
tatus
表 5-64 dest_disaster_status 字段数据结构说明
名称 参数类型 说明
instance_id String 实例id。
status String 容灾状态。
rpo String 数据恢复点目标。
rto String 数据恢复时间目标。
rpo_threshold String rpo阈值。
rto_threshold String rto阈值。
switchover_ String 主从切换进度。该值为一个百分数。例
progress 如：40%
failover_progr String 主从切换进度。该值为一个百分数。例
ess 如：40%
● 正常响应样例
{
"rpo":"0",
"rto":"0",
"status":"archive",
"instance_id":"b3692282395340c5b5421ecf3d7bd6adin14",
"rto_threshold":"900",
"rpo_threshold":"10",
"failover_progress":"",
"switchover_ progress ":"",
"dest_disaster_status":{
"rpo":"0",
"rto":"0",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 221
云数据库 GaussDB
API 参考 5 历史 API
"status":"failover",
"instance_id":"dd93e98e103b4fc4b5a978a6bd6f03a9in14",
"rto_threshold":"900",
"rpo_threshold":"10",
"failover_ progress":"40%",
"switchover_ progress":"",
}
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.4 查询容灾关系列表
功能介绍
查询容灾关系列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/disaster/relations
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/disaster/relations
● 参数说明
表 5-65 参数说明
名称 参 是否必选 说明
数
类
型
project_id Stri 是 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 222
云数据库 GaussDB
API 参考 5 历史 API
名称 参 是否必选 说明
数
类
型
instance_nam Stri 否 实例名称，可查询过滤两端实例。
e ng
limit Int 否 查询记录数。为空时，默认为100。最
ege 小值为1，最大值为100。
r
offset Int 否 索引位置，偏移量。从第一条数据偏移
ege offset条数据后开始查询，默认为0（偏
r 移0条数据，表示从第一条数据开始查
询），必须为数字，不能为负数。
请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/4a52a8a8f63d4c6d966dff0e20b69738/disaster/relations?
limit=&offset=0&instance_name=test
请求消息
无
响应消息
表 5-66 响应 Body 参数列表
名称 参数类型 说明
total Integer 总记录数。
relations Array of Object 容灾关系详情。
表 5-67 relations 字段数据结构说明
名称 参数类型 说明
disaster_type String 容灾类型。
枚举值:
● stream
name String 容灾任务名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 223
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
disaster_role String 容灾角色。
枚举值:
● disaster
● master
created String 创建时间，格式为“yyyy-mm-dd
hh:mm:ss”。
updated String 更新时间，格式为“yyyy-mm-dd
hh:mm:ss”。
slave_region_in Object 备region实例信息。
stance_info
master_region_i Object 主region实例信息。
nstance_info
synchronization String 容灾关系唯一id。
_id
id String 容灾记录id。
instance_id String 当前region实例id。
status String 容灾记录状态。
表 5-68 region_instance_info 字段数据结构说明
名称 参数类型 说明
instance_id String 实例id。
instance_name String 实例名称。
project_id String 实例项目id。
project_name String 实例项目名称。
region String 实例所属region。
instance_statu String 实例状态。
s
action Array of String 实例当前正在执行的action列表。
● 正常响应样例
{
"total": 1,
"relations": [
{
"name": "DR-task-0962",
"created": "2022-06-16 09:39:51",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 224
云数据库 GaussDB
API 参考 5 历史 API
"updated": "2022-06-16 09:44:55",
"id": "30b74120-4b50-495d-8174-7eeddf7feac5",
"status": "normal",
"disaster_type": "stream",
"disaster_role": "disaster",
"slave_region_instance_info": {
"region": "sa-fb-1",
"action": [
"STREAM_DISASTER_RELATION_SLAVE_TAG"
],
"instance_id": "d1060faf0d3743dd8830b39e7423bc9ain14",
"instance_name": "hly-0609-02",
"project_id": "4a52a8a8f63d4c6d966dff0e20b69738",
"project_name": "sa-fb-1_GaussDB",
"instance_status": "normal"
},
"master_region_instance_info": {
"region": "sa-fb-1",
"action": [
"STREAM_DISASTER_RELATION_MASTER_TAG"
],
"instance_id": "54d4b9fb131745fcba32cb90a05cabb8in14",
"instance_name": "hly-0609-01",
"project_id": "4a52a8a8f63d4c6d966dff0e20b69738",
"project_name": "sa-fb-1_GaussDB",
"instance_status": "normal"
},
"synchronization_id": "81da4032-1402-4b3e-b0e0-54c2f234a842",
"instance_id": "d1060faf0d3743dd8830b39e7423bc9ain14"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.5 搭建容灾关系
功能介绍
搭建容灾关系。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
从主实例端下发。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 225
云数据库 GaussDB
API 参考 5 历史 API
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/construct
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
9089bbf7377442daa55bc28d514c08bdin14/disaster/construct
● 参数说明
表 5-69 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 5-70 参数说明
名称 是否必选 参数类型 说明
disaster_construc 是 Array of 搭建容灾请求参数
t_list Object
表 5-71 disaster_construct_list 参数结构说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
slave_region 是 String 备region。
slave_project_id 是 String 备端项目id。
slave_instance_id 是 String 备实例id。
– 请求示例
{
"disaster_construct_list":[
{
"disaster_type":"stream",
"slave_region":"sa-fb-1",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 226
云数据库 GaussDB
API 参考 5 历史 API
"slave_project_id":"4a52a8a8f63d4c6d966dff0e20b69738",
"slave_instance_id":"54d4b9fb131745fcba32cb90a05cabb8in14"
}
]
}
响应消息
表 5-72 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
synchronizatio String 容灾关系唯一id。
n_id
● 正常响应样例
{
"master_job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7",
"slave_job_id":"f88479d2-e2af-4585-a0b8-6e66966d7484",
"synchronization_id":"2d03c2d1-e113-4784-9581-6b66d038817d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.6 备实例容灾升主
功能介绍
容灾升主（failover），灾备实例端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 227
云数据库 GaussDB
API 参考 5 历史 API
约束限制
在灾备region下发。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.2/{project_id}/instances/{instance_id}/
failover
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.2/0483b6b16e954cb88930a360d2c4e663/instances/
c04c789b6baa4b6dbcc139c5226f3a2cin14/failover
● 参数说明
表 5-73 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
表 5-74 参数说明
名称 是否必选 参数类型 说明
is_support_restore 否 Boolean 是否支持容灾回切(仅支持数
据库版本大于等于3.200)
● true支持
false不支持(默认false)
● 正常响应样例
{
"is_support_restore": true
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 228
云数据库 GaussDB
API 参考 5 历史 API
响应消息
表 5-75 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.7 解除容灾关系
功能介绍
解除容灾关系，从容灾主实例端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
从容灾主region端下发。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/relations/{synchronization_id}/release
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
c04c789b6baa4b6dbcc139c5226f3a2cin14/disaster/relations/2d03c2d1-
e113-4784-9581-6b66d038817d/release
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 229
云数据库 GaussDB
API 参考 5 历史 API
● 参数说明
表 5-76 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
synchronization 是 容灾关系唯一id。
_id
请求消息
● 参数说明
无
响应消息
表 5-77 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
"slave_job_id":"e5d837c9-161d-44ca-8cd2-a302409a5ee5"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 230
云数据库 GaussDB
API 参考 5 历史 API
5.3.8 灾备实例主从切换
功能介绍
灾备实例主从切换（switchover），可在主备任意一端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/relations/{synchronization_id}/switchover
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/disaster/relations/e4b98979-5d3b-4805-
a804-47158bcec818/switchover
● 参数说明
表 5-78 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
synchronization 是 容灾关系唯一id。
_id
请求消息
● 参数说明
无
响应消息
表 5-79 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 231
云数据库 GaussDB
API 参考 5 历史 API
"slave_job_id":"8c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.9 重建容灾关系
功能介绍
● 流容灾备升主选择支持容灾回切，实现容灾关系的重建任务。
● 仅支持数据库版本大于等于3.200.。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/relations/{synchronization_id}/restore
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster/relations/e4b98979-5d3b-4805-a804-47158bcec818/restore
● 参数说明
表 5-80 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
synchronization 是 容灾关系唯一id。
_id
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 232
云数据库 GaussDB
API 参考 5 历史 API
请求消息
● 参数说明
无
响应消息
表 5-81 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
"slave_job_id":"8c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.10 开启容灾演练
功能介绍
● 灾备实例开始容灾演练。
● 仅支持数据库版本大于等于3.200的实例
URI
● URI格式
POST
https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/disaster-
simulation/start
● URL样例
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 233
云数据库 GaussDB
API 参考 5 历史 API
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-simulation/start
● 参数说明
表 5-82 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 5-83 参数说明
名称 是否必选 参数类型 说明
xlog_keep_ratio 否 Integer 灾备实例该字段不生效，主
实例默认10：
● 日志保留空间占可使用
剩余磁盘容量的比例, 可
设置范围为1-99。
– 请求示例
{
"xlog_keep_ratio":50
}
响应消息
表 5-84 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
"slave_job_id":"8c242441-fdcc-404f-ba78-f7856aed3edf"
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 234
云数据库 GaussDB
API 参考 5 历史 API
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.11 结束容灾演练
功能介绍
● 灾备实例结束容灾演练。
● 仅支持数据库版本大于等于3.200的实例
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster-simulation/stop
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-simulation/stop
● 参数说明
表 5-85 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
无
● 请求示例
{}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 235
云数据库 GaussDB
API 参考 5 历史 API
响应消息
表 5-86 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
"slave_job_id":"8c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.12 开启日志保持
功能介绍
● 主实例开始容灾日志保持。
● 仅支持数据库版本大于等于3.200的实例
URI
● URI格式
POST
https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/disaster-data-
cache/start
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/disaster-data-cache/start
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 236
云数据库 GaussDB
API 参考 5 历史 API
表 5-87 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 5-88 参数说明
名称 是否必选 参数类型 说明
xlog_keep_ratio 否 Integer 灾备实例该字段不生效，主
实例默认10：
● 日志保留空间占可使用
剩余磁盘容量的比例, 可
设置范围为1-99。
– 请求示例
{
"xlog_keep_ratio":50
}
响应消息
表 5-89 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 237
云数据库 GaussDB
API 参考 5 历史 API
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.13 结束日志保持
功能介绍
● 主实例结束容灾日志保持。
● 仅支持数据库版本大于等于3.200的实例
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/disaster-
data-cache/stop
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/disaster-data-cache/stop
● 参数说明
表 5-90 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
无
● 请求示例
{}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 238
云数据库 GaussDB
API 参考 5 历史 API
响应消息
表 5-91 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 239
云数据库 GaussDB
API 参考 6 附录
6 附录
6.1 异常请求结果
异常响应要素说明
表 6-1 异常响应要素说明
名称 参数类型 说明
error_code String 提交任务异常时返回的错误编码。
error_msg String 提交任务异常时返回的错误描述信息。
响应样例
{
"error_code": "DBS.200022",
"error_msg": "实例名称已存在。"
}
6.2 状态码
状态码如表6-2所示：
表 6-2 状态码
状态码 编码 错误码说明
100 Continue 继续请求。
这个临时响应用来通知客户端，它的部分请求已经
被服务器接收，且仍未被拒绝。
101 Switching 切换协议。只能切换到更高级的协议。
Protocols 例如，切换到HTTP的新版本协议。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 240
云数据库 GaussDB
API 参考 6 附录
状态码 编码 错误码说明
200 OK 请求成功。
201 Created 创建类的请求完全成功。
202 Accepted 已经接受请求，但未处理完成。
203 Non- 非授权信息，请求成功。
Authoritative
Information
204 NoContent 请求完全成功，同时HTTP响应不包含响应体。
在响应OPTIONS方法的HTTP请求时返回此状态
码。
205 Reset Content 重置内容，服务器处理成功。
206 Partial Content 服务器成功处理了部分GET请求。
300 Multiple Choices 多种选择。请求的资源可包括多个位置，相应可返
回一个资源特征与地址的列表用于用户终端（例
如：浏览器）选择。
301 Moved 永久移动，请求的资源已被永久的移动到新的
Permanently URI，返回信息会包括新的URI。
302 Found 资源被临时移动。
303 See Other 查看其它地址。
使用GET和POST请求查看。
304 Not Modified 所请求的资源未修改，服务器返回此状态码时，不
会返回任何资源。
305 Use Proxy 所请求的资源必须通过代理访问。
306 Unused 已经被废弃的HTTP状态码。
400 BadRequest 非法请求。
建议直接修改该请求，不要重试该请求。
401 Unauthorized 在客户端提供认证信息后，返回该状态码，表明服
务端指出客户端所提供的认证信息不正确或非法。
402 Payment 保留请求。
Required
403 Forbidden 请求被拒绝访问。
返回该状态码，表明请求能够到达服务端，且服务
端能够理解用户请求，但是拒绝做更多的事情，因
为该请求被设置为拒绝访问，建议直接修改该请
求，不要重试该请求。
404 NotFound 所请求的资源不存在。
建议直接修改该请求，不要重试该请求。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 241
云数据库 GaussDB
API 参考 6 附录
状态码 编码 错误码说明
405 MethodNotAllow 请求中带有该资源不支持的方法。
ed 建议直接修改该请求，不要重试该请求。
406 Not Acceptable 服务器无法根据客户端请求的内容特性完成请求。
407 Proxy 请求要求代理的身份认证，与401类似，但请求者
Authentication 应当使用代理进行授权。
Required
408 Request Time-out 服务器等候请求时发生超时。
客户端可以随时再次提交该请求而无需进行任何更
改。
409 Conflict 服务器在完成请求时发生冲突。
返回该状态码，表明客户端尝试创建的资源已经存
在，或者由于冲突请求的更新操作不能被完成。
410 Gone 客户端请求的资源已经不存在。
返回该状态码，表明请求的资源已被永久删除。
411 Length Required 服务器无法处理客户端发送的不带Content-Length
的请求信息。
412 Precondition 未满足前提条件，服务器未满足请求者在请求中设
Failed 置的其中一个前提条件。
413 Request Entity 由于请求的实体过大，服务器无法处理，因此拒绝
Too Large 请求。为防止客户端的连续请求，服务器可能会关
闭连接。如果只是服务器暂时无法处理，则会包含
一个Retry-After的响应信息。
414 Request-URI Too 请求的URI过长（URI通常为网址），服务器无法处
Large 理。
415 Unsupported 服务器无法处理请求附带的媒体格式。
Media Type
416 Requested range 客户端请求的范围无效。
not satisfiable
417 Expectation 服务器无法满足Expect的请求头信息。
Failed
422 UnprocessableEnt 请求格式正确，但是由于含有语义错误，无法响
ity 应。
429 TooManyRequest 表明请求超出了客户端访问频率的限制或者服务端
s 接收到多于它能处理的请求。建议客户端读取相应
的Retry-After首部，然后等待该首部指出的时间后
再重试。
500 InternalServerErr 表明服务端能被请求访问到，但是不能理解用户的
or 请求。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 242
云数据库 GaussDB
API 参考 6 附录
状态码 编码 错误码说明
501 Not Implemented 服务器不支持请求的功能，无法完成请求。
502 Bad Gateway 充当网关或代理的服务器，从远端服务器接收到了
一个无效的请求。
503 ServiceUnavailabl 被请求的服务无效。
e 建议直接修改该请求，不要重试该请求。
504 ServerTimeout 请求在给定的时间内无法完成。客户端仅在为请求
指定超时（Timeout）参数时会得到该响应。
505 HTTP Version not 服务器不支持请求的HTTP协议的版本，无法完成
supported 处理。
6.3 错误码
错误码列表：
表 6-3 错误码列表
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 Parameter error. 参数错误。 检查传入的参数或URL是否全
0001 部正确。
400 DBS.20 Parameter error. 参数错误。 检查传入的参数或URL是否全
0004 部正确。
400 DBS.20 The request is 请求为空，请 请输入请求参数后重试。
0006 null. Enter a 输入请求参
request 数。
parameter.
400 DBS.20 Invalid DB 实例名非法。 请参考对应实例名的参数说
0021 instance name. 明输入符合要求的实例名后
重试。
400 DBS.20 Storage space is 卷大小超出允 检查磁盘大小的值是否正
0023 out of range. 许范围。 确。
400 DBS.20 Invalid region. Region非法。 请输入正确的 Region ID。
0024
400 DBS.20 Invalid AZ. 可用区取值非 检查可用区的参数是否正
0025 法。 确，可用区是否存在。
400 DBS.20 Invalid storage 卷类型非法。 检查磁盘的类型是否正确，
0026 type. 是否符合要求。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 243
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 Storage space 卷大小不是10 检查磁盘大小是否是10的倍
0027 must be a 的整数倍。 数。
multiple of 10.
400 DBS.20 The DB engine 不支持的数据 检查数据库引擎或版本是否
0040 or version is not 库类型或版 支持。
supported. 本。
400 DBS.20 Invalid database 数据库版本非 检查数据库的版本号是否支
0041 version. 法。 持。
400 DBS.20 The DB engine 不支持的数据 检查数据库类型或版本是否
0042 does not exist. 库类型或版 正确。
本。
400 DBS.20 Invalid HA同步模式非 检查同步模式是否正确。
0043 synchronize 法。
model.
400 DBS.20 Invalid VPC ID. VPC id非法。 检查VPC id是否正确。
0048
400 DBS.20 Invalid subnet 子网的网络id 检查子网ID是否正确。
0049 ID. 非法。
400 DBS.20 Invalid HA 不合法的ha模 检查HA模式是否正确。
0051 mode. 式。
400 DBS.20 Invalid database 数据库root密 检查数据库root密码是否符合
0052 root password. 码非法。 要求。
400 DBS.20 The selected 所选规格不存 检查所选规格是否正确。
0053 specifications 在。
do not exist.
400 DBS.20 Invalid 所选规格非 检查规格码是否正确，规格
0054 specifications. 法。 在当前可用区是否存在，规
格是否支持。
400 DBS.20 The maximum 节点个数达到 检查节点个数是否已达到最
0056 number of 最大值。 大值。
nodes has been
reached.
400 DBS.20 Invalid cluster 集群模式非 检查集群模式是否合法。
0063 mode. 法。
400 DBS.20 This is a weak 这是一个弱密 请参考对应的密码参数说
0068 password. 码，请输入一 明，输入符合密码复杂度要
Please enter a 个强度大一些 求，且强度更高的密码。
strong 的密码.
password.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 244
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 The DB instance 实例或节点非 检查实例或节点状态。
0076 and node must 正常状态。
be in the
Available state.
400 DBS.20 This operation is 实例状态不允 检查实例的状态或实例正在
0086 not allowed by 许做该操作。 进行的操作是否与请求冲
the DB instance 突。
status.
400 DBS.20 The number of 单个实例标签 检查实例标签数量是否达到
0087 tags added for 数量达到最大 了最大配额。
the DB instance 配额。
has reached the
quota.
400 DBS.20 The tag already 该资源标签已 检查标签是否已存在。
0098 exists. 存在。
400 DBS.20 The engine 该引擎版本不 检查该引擎版本是否高于
0175 version is not 支持设置切换 1.2.2。
permitted to 策略。
enable force
switch.
400 DBS.20 Failed to query 查询实例失 检查查询的实例是否存在或
0203 the DB instance. 败。 重试。
400 DBS.20 Storage space 卷大小不是10 检查磁盘大小是否是10的倍
0302 must be a 的整数倍。 数。
multiple of 10.
400 DBS.20 The scale-up 扩容次数达到 检查扩容次数是否达到最大
0303 times have 最大限制。 限制。
reached the
maximum
value.
400 DBS.20 The new 扩容参数不合 检查扩容参数是否合法。
0306 storage space 法。
must be greater
than or equal to
the original
storage space.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 245
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 The new 备机扩容后的 检查备机扩容后的大小是否
0308 storage space 大小不能超过 超过了主机。
after scaling up 主机。
cannot be
greater than
that of the
primary DB
instance.
400 DBS.20 Parameter error. 参数错误 检查传入的参数或URL是否全
0405 部正确。
400 DBS.20 The parameter 参数值超出范 检查参数值是否超出范围。
0461 value is out of 围。
range.
400 DBS.20 New password 新密码不能与 检查新旧密码是否符合要
0475 should not 旧密码相同。 求。
equal to the old
ones.
400 DBS.20 Invalid database 数据库版本非 检查数据库的版本号是否支
0504 version. 法。 持。
400 DBS.20 Invalid KMS key 密钥非法。 检查密钥是否正确。
0506 ID.
400 DBS.20 The KMS key is 密钥失效或已 检查密钥是否正确。
0507 invalid or has 删除。
been deleted.
400 DBS.20 The job does 任务不存在。 检查任务是否正确。
0543 not exist.
400 DBS.20 The database 数据库不存 检查数据库名称是否合法。
0823 does not exist. 在。
400 DBS.20 The database 数据库帐号不 检查数据库用户名称是否合
0824 account does 存在。 法。
not exist.
400 DBS.20 Modifying 不允许在只读 请确认权限后操作。
0825 permission is 实例上执行修
not allowed on 改权限操作。
read replicas.
400 DBS.20 Agent async 调用agent异步 请检查agent连接是否正常。
0943 requet failed. 请求失败。
400 DBS.20 The backup 备份类型不存 检查备份类型。
1004 type does not 在。
exist.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 246
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 This operation is 实例状态不允 检查实例的状态或实例正在
1014 not allowed by 许做该操作。 进行的操作是否与请求冲
the DB instance 突。
status.
409 DBS.20 Another 该实例正在进 该实例正在进行其它操作，
1015 operation is 行其它操作， 无法执行该操作，请稍后重
being 无法执行该操 试。
performed on 作，请稍后重
the DB instance. 试。
400 DBS.20 The restoration 恢复任务不存 该实例没有相关恢复任务或
1019 task does not 在. 者不需要进行恢复后的数据
exist. 确认。
400 DBS.20 The database 输入的数据库 检查数据库名是否正确。
1035 name must be 名重复或者输
different from 入的数据库名
the original and 与目标库上的
target database 重复。
names.
400 DBS.20 Invalid backup 备份周期非 检查备份周期是否正确，是
1101 cycle. 法。 否符合要求。
400 DBS.20 Invalid backup 备份开始时间 检查备份开始时间是否符合
1103 start time. 非法。 要求，备份开始时间和备份
结束时间的关系是否正确。
400 DBS.20 Invalid retention 保留天数非 检查保留天数是否合法。
1106 days. 法。
400 DBS.20 The backup file 备份文件不存 检查该备份是否存在，备份
1203 does not exist. 在。 是否匹配实例。
400 DBS.20 The DB engine 不支持的数据 检查数据库引擎或版本是否
1207 or version is not 库类型或版 支持。
supported. 本。
400 DBS.20 The operation is 备份状态不允 请明确具体操作约束，按照
1208 not allowed by 许。 约束进行操作。
the backup
status.
400 DBS.20 Invalid backup 备份名非法。 检查备份名称是否合法。
1210 name.
400 DBS.21 Incorrect 参数组配额错 检查参数组配额是否正确。
2002 parameter 误。
group quota.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 247
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.21 Operation not 不支持此操 检查实例的状态或实例正在
2003 allowed. 作。 进行的操作是否与请求冲
突。
400 DBS.21 Parameter 参数组更新错 检查参数是否正确。
2004 group update 误。
error.
400 DBS.21 The node does 节点不属于 检查节点及所属组是否正
2005 not belong to 组。 确。
the group.
400 DBS.21 The DB engine 引擎不存在。 检查数据库引擎是否正确。
2007 does not exist.
400 DBS.21 The DB engine 不支持的引 检查数据库引擎是否支持。
2008 is not 擎。
supported.
400 DBS.21 Task processing 任务处理失 稍后请重试，或联系技术支
2009 failed. 败。 持。
400 DBS.21 The parameter 绑定正在执 稍后请重试。
2010 group is being 行。
applied.
400 DBS.21 Application 绑定失败。 重新绑定或联系技术支持。
2011 failed.
400 DBS.21 The parameter 参数不存在。 检查参数是否正确。
2012 does not exist.
400 DBS.21 The node does 节点没有默认 检查默认参数组。
2014 not have a 参数组。
default
parameter
group.
400 DBS.21 Partial success. 部分成功。 检查任务部分失败原因或联
2015 系技术支持。
400 DBS.21 Parameter 参数更新失 检查参数是否正确。
2016 update failed. 败。
400 DBS.21 Invalid 参数非法。 检查参数是否正确。
2017 parameter.
400 DBS.21 Update failed. 更新失败。 检查更新失败原因或联系技
2025 术支持。
400 DBS.21 The parameter 参数组名已存 检查参数是否正确。
2030 template name 在。
already exists.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 248
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.21 The parameter 参数模板已被 检查参数模板是否正确。
2032 template has 应用。
been applied.
400 DBS.21 Parameters are 参数设置不正 检查参数设置是否正确。
2037 incorrectly set. 确。
400 DBS.21 Insufficient 内部资源配额 检查内部资源配额。
6028 internal 不足。
resource quota.
400 DBS.21 The queried 操作节点不属 检查操作节点信息是否正
6030 node does not 于该实例。 确。
belong to the
current
instance.
400 DBS.28 Parameter error. 参数错误。 检查参数是否正确。
0001
500 DBS.28 Server failure. 服务器错误。 请联系客服管理员或者稍后
0005 重试。
400 DBS.28 The request is 请求为空，请 检查请求参数是否正确。
0006 null. Enter a 输入请求参
request 数。
parameter.
400 DBS.28 Invalid backup 备份文件id非 检查备份文件id是否合法
0124 file id 法
400 DBS.28 Invalid backup 备份描述不合 检查备份描述是否合法。
0127 description. 法。
400 DBS.28 The database 请检查数据库 检查数据库名称是否正确。
0128 information of 名，确认所填
the DB instance 数据库名信
is not found. 息，找不到该
Check the 实例的数据库
database name 信息。
to see whether
the instance
database
information
exists.
400 DBS.28 This is a weak 这是一个弱密 请参考对应的密码参数说
0203 password. 码，请输入一 明，输入符合密码复杂度要
Please enter a 个强度大一些 求，且强度更高的密码。
strong 的密码.
password.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 249
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 Invalid 输入参数不合 检查参数是否正确。
0204 parameter. 法。
400 DBS.28 Invalid retention 保留天数非 检查保留天数是否合法。
0214 days. 法。
400 DBS.28 Invalid backup 备份周期非 检查备份周期是否合法。
0215 cycle. 法。
400 DBS.28 Invalid backup 备份开始时间 检查备份开始时间是否合
0216 start time. 非法。 法。
400 DBS.28 Invalid DB 实例名非法。 检查实例名称是否合法。
0234 instance name.
400 DBS.28 Invalid database 数据库类型非 检查数据库类型是否正确。
0235 type. 法
400 DBS.28 Invalid database 数据库版本非 检查数据库版本是否正确。
0236 version. 法。
400 DBS.28 Datastore not Datastore为 检查Datastore是否合法。
0237 specified. 空。
400 DBS.28 The DB engine 不支持的数据 检查数据库引擎或版本是否
0238 or version is not 库类型或版 支持。
supported. 本。
400 DBS.28 Invalid 所选规格非 检查所选规格是否正确。
0239 specifications. 法。
400 DBS.28 Invalid storage 卷类型非法。 检查磁盘的类型是否正确，
0241 type. 是否符合要求。
400 DBS.28 Storage space is 卷大小超出允 检查磁盘大小的值是否正
0242 out of range. 许范围。 确。
400 DBS.28 The region or Region或可用 请输入正确的 Region ID或可
0244 AZ does not 区不存在 用区。
exist.
400 DBS.28 Invalid database 数据库root密 检查数据库root密码是否符合
0246 root password 码非法。 要求。
400 DBS.28 Invalid backup 备份保留天数 检查保留天数是否合法。
0250 retention days. 非法。
400 DBS.28 Invalid backup 备份周期不合 检查备份周期是否符合要
0251 cycle. 法。 求。
400 DBS.28 Invalid backup 备份开始时间 检查备份开始时间是否符合
0253 start time. 非法。 要求，备份开始时间和备份
结束时间的关系是否正确。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 250
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 The parameter 参数不存在。 检查参数是否正确。
0270 does not exist.
400 DBS.28 The parameter 参数值超出范 检查参数是否正确。
0271 value is out of 围。
range.
400 DBS.28 The tag key 新增标签存在 请检查请求参数中的标签键
0272 must be unique. 重复的键值。 值。
400 DBS.28 Invalid object 对象名称非 检查对象名称是否合法。
0277 name. 法。
400 DBS.28 Invalid AZ. 可用区取值非 检查可用区的参数是正确，
0285 法。 可用区是否存在。
400 DBS.28 Invalid 规格非法。 检查规格是否合法。
0288 FlavorRef.
400 DBS.28 Invalid storage 存储空间大小 检查存储空间大小是否合
0311 space size. 非法。 法。
400 DBS.28 Invalid storage 硬盘信息不合 检查硬盘信息是否合法。
0325 information. 法。
400 DBS.28 Invalid cluster 集群模式非 检查集群模式是否合法。
0342 mode. 法。
400 DBS.28 Invalid database 数据库端口号 检查数据库端口号是否合
0364 port. 无效。 法。
400 DBS.28 Invalid billing 付款模式无 检查传入的付款模式是否正
0365 mode. 效。 确。
400 DBS.28 Invalid HA Ha模式非法。 检查HA模式是否合法。
0402 mode.
400 DBS.28 Invalid DB 实例ID或者节 检查实例ID是否合法。
0404 instance ID or 点ID非法。
node ID format.
400 DBS.28 Invalid node ID. 节点ID非法。 检查节点ID是否合法。
0407
400 DBS.28 Invalid backup 备份结束时间 检查备份结束时间是否合
0416 end time. 非法。 法。
400 DBS.28 Invalid backup 备份时间非 检查备份回见是否合法。
0417 time. 法。
400 DBS.28 Invalid 不合法的企业 检查企业项目ID是否符合要
0433 enterprise 项目ID。 求。
project ID.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 251
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 Invalid 所选规格码非 检查规格码是否合法。
0434 specification 法。
code.
400 DBS.28 Invalid records. 无效的查询记 检查查询记录数是否合法。
0439 The number of 录数，请输入
records must be 小于等于100的
an integer less 正整数。
than or equal to
100.
400 DBS.28 Invalid offset, 无效的偏移 检查偏移量是否合法。
0440 please enter a 量，请输入非
non negative 负整数
integer.
400 DBS.28 Invalid time 不合法的time 检查时区参数是否填写正
0447 zone. zone。 确。
400 DBS.28 This operation 不能对冻结的 解冻该实例，再重试。
0449 cannot be 对象执行该操
performed 作。
because the
object is frozen.
400 DBS.28 Invalid time 无效的查询时 请输入正确的查询时间。
0472 range. 间。
400 DBS.28 Invalid 协调节点数量 检查协调节点数量是否合
0600 coordinator 非法。 法。
node quantity.
400 DBS.28 Invalid shard 分片数量非 检查分片数量是否合法。
0601 quantity. 法。
400 DBS.28 Invalid number 扩容分片数非 检查扩容分片数量是否合
0604 of added shards 法。 法。
for cluster
capacity
expansion.
400 DBS.28 Differential 差异备份周期 检查差异备份周期是否合
0618 backup cycle 无效。 法。
invalid.
400 DBS.28 Invalid replica 副本数非法。 检查副本数量是否合法。
0628 count.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 252
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 The database 数据库版本不 检查副本数量是否合法，或
0629 version does not 支持2副本实 者修改为支持的数据库版
support two- 例。 本，再重试。
replica
instances.
400 DBS.28 Two-replica 2副本实例只支 检查2副本实例可用区是否合
0630 instances can 持单可用区。 法。
only be
deployed within
a single AZ.
400 DBS.28 Invalid database 数据库名非 检查数据库名称是否合法。
0631 name. 法。
400 DBS.28 Invalid schema. 数据库模式非 检查数据库模式是否合法
0632 法。
400 DBS.28 Invalid source 源Node Group 检查源Node Group是否合
0633 node group. 非法。 法。
400 DBS.28 Invalid target 目标Node 检查目标Node Group是否合
0634 node group. Group非法。 法。
400 DBS.28 Invalid Solution Solution非法。 检查solution参数是否填写正
0635 确。
400 DBS.29 Parameter error. 参数错误。 检查传入的参数或URL是否全
0000 部正确，是否符合要求。
400 DBS.29 Parameter error. 参数错误。 检查参数是否填写正确。
0001
403 DBS.20 The DB instance 实例ID和用户 检查实例ID或用户ID是否正
0010 ID or user ID ID可能为空， 确，或者检查访问权限。
may be null, or 或者操作越
the operation is 权。
not authorized.
403 DBS.20 Resource not 访问资源不存 修改资源ID或者检查访问权
0044 found or 在，或者无访 限。
permission 问权限。
denied.
403 DBS.20 No permission 没有设置切换 检查是否有设置切换策略参
0174 to enable force 策略参数的权 数的权限。
switch. 限。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 253
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
403 DBS.20 The DB instance 实例ID和用户 检查实例ID或用户ID是否正
0604 ID or user ID ID可能为空， 确，获取检查访问权限。
may be null, or 或者操作越
the operation is 权。
not authorized.
403 DBS.20 You are not 不能在只读实 检查只读实例操作限制。
0810 allowed to 例创建数据
create 库。
databases on
read replicas.
403 DBS.20 You are not 不能在只读实 检查只读实例操作限制。
0819 allowed to 例执行删除数
delete database 据库用户。
users on read
replicas.
403 DBS.28 The account is 账户受限。 检查帐号是否权限不足。
0020 restricted.
400 DBS.28 This operation is 集群状态受 检查集群状态是否正常。
0800 not allowed by 限，操作不允
the cluster 许执行。
status.
400 DBS.28 This operation is 1.X内核版本不 检查操作实例内核版本，如
0804 not allowed for 支持对主备版 要必要需要升级内核版本。
primary/standby 实例进行操
instances with 作。
kernel version
1.x
400 DBS.28 The component 组件ID必须是 检查组件ID状态，不允许传
0828 ID must be the 备DN。 入主DN组件ID。
standby DN ID.
403 DBS.20 Resource not 访问资源不存 修改资源ID或者检查访问权
1003 found or 在，或者无访 限
permission 问权限。
denied.
403 DBS.28 Resource not 访问资源不存 修改资源ID或者检查访问权
0015 found or 在，或者无访 限
permission 问权限。
denied.
403 DBS.28 Invalid token. Token非法。 请检查token是否正确，或者
0056 重新获取token后再试
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 254
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
404 DBS.20 The DB instance 实例不存在。 检查租户是否拥有该实例，
0002 does not exist. 实例名或实例ID是否正确，
实例是否存在。
404 DBS.20 The ECS 请检查数据 检查实例虚拟机是否正常。
0008 information of 库，确认实例
the DB instance 的虚拟机信
cannot be 息，找不到该
found. 实例的虚拟机
信息。
404 DBS.20 The original DB 源实例不存 检查源实例是否存在。
0013 instance does 在。
not exist.
404 DBS.20 The DB instance 实例不存在。 查租户是否拥有该实例，实
0045 does not exist. 例名或实例ID是否正确，实
例是否存在。
404 DBS.20 The security 安全组不存 检查安全组是否正确。
0050 group does not 在，或不属于
exist or does 该VPC。
not belong to
the VPC.
404 DBS.20 The DB instance 实例异常，无 检查实例或节点状态。
0408 abnormal, no 正常节点。
normal nodes.
404 DBS.20 The region or Region或可用 请输入正确的 Region ID或可
0470 AZ does not 区不存在。 用区。
exist.
404 DBS.20 The subnet does 子网不存在， 检查子网是否正确。
0501 not exist or 或不属于该
does not belong VPC。
to the VPC.
404 DBS.20 The VPC does VPC不存在， 检查VPC是否正确。
0503 not exist or 或不属于该用
does not belong 户。
to the user.
404 DBS.20 The DB instance 该实例不存 查租户是否拥有该实例，实
0602 does not exist. 在。 例名或实例ID是否正确，实
例是否存在。
404 DBS.20 The backup file 备份文件不存 检查该备份是否存在，备份
1010 does not exist. 在。 是否匹配实例。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 255
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
404 DBS.20 The DB instance 实例不存在或 查租户是否拥有该实例，实
1028 does not exist. 已删除。 例名或实例ID是否正确，实
例是否存在。
404 DBS.21 The parameter 参数组不存 检查参数组是否存在。
2001 group does not 在。
exist.
404 DBS.21 The object does 对象不存在。 请确定操作的对象存在。
2013 not exist.
404 DBS.29 The selected 所选规格不存 检查所选规格是否正确。
0002 specifications 在。
do not exist.
404 DBS.29 The DB instance 该实例不存 检查租户是否拥有该实例，
0005 does not exist. 在。 实例名或实例ID是否正确，
实例是否存在。
404 DBS.29 The DB instance 实例不存在。 检查租户是否拥有该实例，
0011 does not exist. 实例名或实例ID是否正确，
实例是否存在。
404 DBS.29 Resource not 未找到资源。 检查入参是否正确，实例是
0013 found. 否存在。
409 DBS.20 Another 该实例正在进 检查实例的状态或实例正在
0011 operation is 行其它操作或 进行的操作是否与请求冲
being 该实例故障， 突。
performed on 无法执行该操
the DB instance 作，请稍后重
or the DB 试。
instance is
faulty.
409 DBS.20 This operation 该操作与当前正在 检查实例的状态或实例正在
conflicts with the 运行的任务是冲突
0019 currently running 的，请自行排查。 进行的操作是否与请求冲
task, please 突。
troubleshoot by
yourself.
409 DBS.20 The DB instance 实例名称已存 请输入一个与已存在的实例
0022 name already 在。 不相同的实例名。
exists.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 256
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
409 DBS.20 Another 该实例正在进 检查实例的状态或实例正在
0047 operation is 行其它操作或 进行的操作是否与请求冲
being 该实例故障， 突。
performed on 无法执行该操
the DB instance 作，请稍后重
or the DB 试。
instance is
faulty.
409 DBS.20 This operation 当前实例状态 检查实例存储空间是否已
0316 cannot be 为存储空间 满。
performed 满，不能进行
because the DB 该操作。
instance status
is Storage full.
409 DBS.20 Invalid 操作不合法。 检查请求是否合法。
0402 operation.
409 DBS.20 The database 数据库名称已 检查数据库名称是否合法。
0826 name already 存在。
exists.
409 DBS.20 The database 帐号名称已存 检查数据库用户是否合法。
0827 user already 在。
exists.
409 DBS.20 Built-in 数据库内置帐 检查用户操作权限。
0828 database 号，用户不可
accounts cannot 操作。
be edited.
409 DBS.20 The backup 备份名称已存 请确定操作的对象是否存
1201 name already 在。 在。
exists.
409 DBS.20 Another 该实例正在进 检查实例的状态或实例正在
1202 operation is 行其它操作或 进行的操作是否与请求冲
being 该实例故障， 突。
performed on 无法执行该操
the DB instance 作，请稍后重
or the DB 试。
instance is
faulty.
409 DBS.20 Backup is in 正在备份中， 等待备份完成后，再重试。
1205 progress, please 请稍等。
wait.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 257
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
409 DBS.21 Another 该实例正在进 检查实例的状态或实例正在
2006 operation is 行其它操作或 进行的操作是否与请求冲
being 该实例故障， 突。
performed on 无法执行该操
the DB instance 作，请稍后重
or the DB 试。
instance is
faulty.
409 DBS.21 Failed to 无法更改数据 检查实例的状态或实例正在
2033 change 库实例的参数 进行的操作是否与请求冲
parameter 组值，因为当 突。
template values 前正在操作数
because the DB 据库实例。
instance is
currently being
operated.
409 DBS.28 This operation 实例当前状态 检查实例的状态是否正常或
0011 cannot be 异常或已删 者该实例是否已经被删除
performed 除，不允许做 了。
because the DB 该操作。
instance is
abnormal or
has been
deleted.
409 DBS.28 Operation not 实例类型或状 检查实例的状态或实例正在
0406 allowed by the 态受限，操作 进行的操作是否与请求冲
DB instance 不允许。 突。
type or status.
413 DBS.20 The number of 实例数量达到 检查配额。
0046 DB instances 配额。
has reached the
quota.
413 DBS.29 The number of 实例数量达到 检查配额。
0003 DB instances 配额。
has reached the
quota.
422 DBS.21 The parameter 参数错误。 检查参数是否正确。
2019 cannot be
processed.
500 DBS.10 Server failure. 服务器错误。 请联系客服管理员或者稍后
8000 重试。
500 DBS.10 Server failure. 服务器错误。 请联系客服管理员或者稍后
8002 重试。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 258
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
500 DBS.10 Server failure. 服务器错误。 请联系客服管理员或者稍后
8005 重试。
500 DBS.20 Server failure. 服务器错误。 请联系客服管理员或者稍后
0005 重试。
500 DBS.20 Server failure. 服务器错误。 请联系客服管理员或者稍后
0208 重试。
500 DBS.20 Failed to create 创建数据库失 检查失败原因或联系技术支
0811 the database. 败。 持。
500 DBS.20 Failed to modify 修改数据库用 检查用户权限。
0821 database user 户权限失败。
permissions.
500 DBS.21 Failed to 请求处理失 请联系客服管理员或者稍后
3002 process the 败。 重试。
request.
500 DBS.21 Failed to 请求处理失 请联系客服管理员或者稍后
3004 process the 败。 重试。
request.
500 DBS.28 The DB instance 实例状态异 请联系客户服务，或者稍后
0106 status is 常。 再试。
abnormal.
Please contact
customer
service or try
again later.
500 DBS.29 Failed to 请求处理失 请联系客服管理员或者稍后
0006 process the 败。 重试。
request.
500 DBS.29 Failed to 请求处理失 请联系客服管理员或者稍后
0015 process the 败。 重试。
request.
400 DBS.28 Storage space 卷大小不是10 检查磁盘大小是否是10的倍
0266 must be a 的整数倍。 数。
multiple of 10.
400 DBS.28 Storage space 所选磁盘容量 检查磁盘大小是否符合要
0611 must be a 大小必须为 求。
common 40GB和分片数
multiple of 的公倍数。
40GB and the
number of
shards.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 259
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 Storage space 所选磁盘容量 检查磁盘大小是否符合要
0612 excess max limit 大于当前分片 求。
for current 数支持的最大
shard number. 值。
400 DBS.28 Invalid region. Region非法。 请输入正确的 Region ID。
0243
400 DBS.20 The subnet does 子网不存在， 请输入正确的子网后重试。
0505 not exist or 或不属于该
does not belong vpc。
to the VPC.
404 DBS.20 The security 安全组不存 请输入正确的安全组后重
0502 group does not 在，或不属于 试。
exist or does 该VPC。
not belong to
the VPC.
400 DBS.20 Invalid retention 保留天数非 检查保留天数是否合法。
0065 days. 法。
400 DBS.28 Invalid HA Ha一致性非 检查Ha一致性是否合法。
0602 consistency. 法。
400 DBS.28 Invalid Ha同步模式非 检查Ha模式是否合法。
0262 synchronize 法。
model.
400 DBS.20 Invalid 实例参数组的 请输入正确的实例参数组ID
0057 parameter ID取值非法。 后重试。
template ID.
404 DBS.20 The parameter 参数组不存 检查参数组是否存在。
0058 template does 在。
not exist.
400 DBS.20 Invalid database 数据库端口号 检查数据库端口号是否合
0059 port. 无效。 法。
400 DBS.28 The Ha instance 主备版实例不 主备版实例不支持设置并行
0654 is not supported 支持取消并行 恢复，请按照API文档在请求
to cancel 恢复。 体中取消设置并行恢复。
parallel restore.
400 DBS.28 Please use 请使用数据节 检查数据节点规格是否正
0613 specifications of 点的规格。 确。
data nodes.
404 DBS.20 Resource not 未找到资源。 检查资源后重试。
0355 found.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 260
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 Invalid billing 付款模式无 检查付款模式是否合法。
0061 mode. 效。
400 DBS.20 The backup file 不是手动备份 选择手动备份文件进行操
1218 is not manual. 文件。 作。
404 DBS.28 The DB instance 实例不存在或 查租户是否拥有该实例，实
0022 does not exist. 已删除。 例名或实例ID是否正确，实
例是否存在。
400 DBS.28 Invalid project project id 非 检查project id是否合法。
0408 id. 法。
400 DBS.28 Exceeding the 超过单次数据 检查单次数据节点扩容数量
0607 upper limit of 节点扩容数量 是否达到上限。
data nodes 的上限。
number in a
single expand
request.
400 DBS.20 The available IP 所选子网可用 请输入正确可用的子网后重
0082 addresses in the IP不足。 试。
selected subnet
are insufficient.
400 DBS.28 Expanding 暂不支持同时 检查扩容约束后重试。
0606 coordinator 扩容协调节点
nodes and data 和数据节点。
nodes at the
same time is
not supported
currently.
400 DBS.28 Exceeding the 超过单次协调 检查单次协调节点扩容数量
0608 upper limit of 节点扩容数量 是否达到上限。
coordinator 的上限。
nodes number
in a single
expand request.
400 DBS.28 Expand cluster 扩容集群请求 检查扩容规范后重试。
0609 request must 至少要包含一
contains at least 种要扩容的节
one node type 点。
to expand.
400 DBS.30 The backup file 备份文件状态 检查该备份文件的状态。
1024 is not normal. 异常。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 261
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
500 DBS.30 Failed to submit 提交订单失 检查订单提交状态。
1028 the order. 败。联系管理
Contact the 员。
administrator.
400 DBS.28 Failed to create 创建数据库 检查输入schema参数然后重
0651 all DB schemas. SCHEMA全部 试。
失败。
400 DBS.28 Failed to create 创建数据库 检查输入schema参数然后重
0652 some DB SCHEMA部分 试。
schemas. 失败。
400 DBS.20 Incorrect 用户名或密码 检查输入输入用户名与密码
0029 username or 参数错误。 然后重试。
password
parameter.
400 DBS.28 Database name 未输入数据库 请输入数据库名称。
0132 not entered. 名称。
400 DBS.28 Illegal instance 非法的实例规 请根据当前实例检查传入的
0661 specification, 格，该规格不 规格参数。
which does not 存在或与实例
exist or does 不匹配。
not match the
instance
400 DBS.28 DR relationship 容灾主集群和 请检查容主备实例是否已经
0626 established 灾备集群已存 存在灾关系。
between 在容灾关系。
primary and DR
instances.
400 DBS.28 The DR 容灾关系记录 请检查容灾关系是否存在。
0638 relationship 不存在。
does not exist.
400 DBS.28 Submit an 白名单不支持 请检查跨region调用组件是否
0803 application to 容灾跨region 部署，并且特性白名单
call the API for 接口。 gaussdb_feature_supportDis
cross-region DR. asterApiGlobal处于开启状
态。
400 DBS.28 Cross-region DR 跨region操作 请检查目前region的project
0806 operation failed. 失败。 id是否合法。
400 DBS.28 Invalid shard 分片组件id非 请检查组件ID是否合法。
0667 component ID. 法。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 262
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 Component IDs 存在同组DN分 请检查批量DN主备倒换时，
0668 are from the 片异常。 多个组件ID是否来自不同组
same shard. 分片。
400 DBS.28 The component 组件id不属于 请检查DN主备倒换时，组件
0676 ID does not 当前节点id。 ID是否属于对应的节点ID。
belong to the
current node ID.
400 DBS.20 Failed to 修改密码失 请检查传入的密码是否正
0478 change the 败。 确。
password.
400 DBS.20 Invalid database 数据库用户名 请输入正确的数据库用户
0062 username. 非法。 名。
400 DBS.28 Invalid database 数据库模板非 请输入正确的模板名称。
0653 template. Use 法，建议使用
the template0. template0数据
库模板。
400 DBS.28 Invalid cluster 无效集群一致 请检查集群一致性协议。
0640 consensus 性协议，请检
protocol, please 查数据库版本
check database 与一致性协
version and 议。
consistency
protocol.
400 DBS.20 The database 数据库版本不 请检查实例数据库版本是否
0856 version is not 支持。 支持该操作。
supported.
400 DBS.28 Remain 资源校验未通 请检查源是否充足。
0822 resource 过。
verification
failed.
400 DBS.20 Invalid retention 保留天数非 请输入正确的保留天数。
0064 days. 法。
400 DBS.30 An AZ that does 存在不支持 请确认所选择的az是否全部
1009 not support IPv6的可用 支持IPv6。
IPv6 exists. 区。
400 DBS.30 Selected 所选规格不支 请确认当前规格是否支持
1010 specifications 持IPv6。 IPv6。
do not support
IPv6.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 263
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.30 XBSA 缺失XBSA配置 请配置XBSA配置信息。
0111 configuration 信息。
information is
missing.
400 DBS.30 ca_cert_pem is a “ca_cert_pem 请输入正确的ca_cert_pem。
0112 required field. ”字段不能为
空。
400 DBS.30 client_key is a “client_key 请输入正确的client_key。
0113 required field. ”字段不能为
空。
400 DBS.30 client_crt is a “client_crt ” 请输入正确的client_crt。
0114 required field. 字段不能为
空。
400 DBS.30 rand_pass is a “rand_pass 请输入正确的rand_pass。
0115 required field. ”字段不能为
空。
400 DBS.30 Nodes has 所有节点或者 请确定实例或者节点的状态
1132 shutdown. 实例已经处于 正常。
停止状态。
400 DBS.20 The node 备份时实例的 请选择与当前节点拓扑一致
0480 topology of the 节点拓扑结构 的备份。
selected DB 与当前实例不
instance must 一致。
be the same as
that of the
original DB
instance.
400 DBS.06 Instance status 实例状态无 请检查当前的实例状态。
010001 is invalid. 效。
400 DBS.06 The IPv6 status 所选vpc的ipv6 对于多VPC场景，需要选择的
013041 of the selected 开启状态不一 VPC子网IPv6开启状态保持一
VPCs is 致。 致。
inconsistent.
400 DBS.06 An operation 与当前操作冲 请检查当前实例是否正在进
020003 that conflicts 突的操作正在 行其他操作。
with the current 进行中。
operation is in
progress.
400 DBS.06 The instance is 实例状态不满 检查实例状态。
020104 abnormal. 足。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 264
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 The instance is 容灾状态不满 检查当前实例的容灾状态。
020105 abnormal. 足。
400 DBS.06 Agent agent 调用异 请联系客服管理员或者稍后
020108 invocation 常 重试。
exception.
400 DBS.06 Peer-region 跨region 请联系客服管理员或者稍后
020109 verification preCheck校验 重试。
failed. 不通过。
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020110 synchronization 量同步中，请
in progress for 在无容灾状态
the primary 时执行该操
instance. Select 作。
an instance
without a DR
relationship as
primary
instance.
400 DBS.06 Incremental 主实例处于增 检查当前实例的容灾状态。
020111 synchronization 量同步中，请
in progress for 在无容灾状态
the primary 时执行该操
instance. Select 作。
an instance
without a DR
relationship as
primary
instance.
400 DBS.06 Incremental 主实例处于全 检查当前实例的容灾状态。
020112 synchronization 量同步失败，
in progress for 请在无容灾状
the primary 态时执行该操
instance. Select 作。
an instance
without a DR
relationship as
primary
instance.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 265
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 主实例处于增 检查当前实例的容灾状态。
020113 synchronization 量同步失败，
failed for the 请在无容灾状
primary 态时执行该操
instance. Select 作。
an instance
without a DR
relationship as
primary
instance.
400 DBS.06 Switchover in 主备切换中， 检查当前实例的容灾状态。
020114 progress for the 请在无容灾状
primary or DR 态时执行该操
instance. Select 作。
an instance
without a DR
relationship.
400 DBS.06 Switchover 主备切换失 检查当前实例的容灾状态。
020115 failed for the 败，请在无容
primary or DR 灾状态时执行
instance. Select 该操作。
an instance
without a DR
relationship.
400 DBS.06 Incremental 灾备实例处于 检查当前实例的容灾状态。
020116 restoration in 全量恢复中，
progress for the 请在无容灾状
DR instance. 态时执行该操
Select an 作。
instance
without a DR
relationship as
DR instance.
400 DBS.06 Incremental 灾备实例处于 检查当前实例的容灾状态。
020117 restoration 全量恢复失
failed for the 败，请在无容
DR instance. 灾状态时执行
Select an 该操作。
instance
without a DR
relationship as
DR instance.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 266
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 灾备实例处于 检查当前实例的容灾状态。
020118 restoration in 增量恢复中，
progress for the 请在无容灾状
DR instance. 态时执行该操
Select an 作。
instance
without a DR
relationship as
DR instance.
400 DBS.06 Incremental 灾备实例处于 检查当前实例的容灾状态。
020119 restoration 增量恢复失
failed for the 败，请在无容
DR instance. 灾状态时执行
Select an 该操作。
instance
without a DR
relationship as
DR instance.
400 DBS.06 Promotion to 灾备实例处于 检查当前实例的容灾状态。
020120 primary in 升主中，请在
progress for the 无容灾状态时
DR instance. 执行该操作。
Select an
instance
without a DR
relationship as
DR instance.
400 DBS.06 Promotion to 灾备实例处于 检查当前实例的容灾状态。
020121 primary failed 升主失败，请
for the DR 在无容灾状态
instance. Select 时执行该操
an instance 作。
without a DR
relationship as
DR instance.
400 DBS.06 No DR 灾备实例处于 检查当前实例的容灾状态。
020122 relationship 无容灾状态，
established for 请在增量恢复
the DR instance. 中或增量恢复
Perform this 失败时执行该
operation when 操作。
incremental
restoration is in
progress or
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 267
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Switchover in 灾备实例处于 检查当前实例的容灾状态。
020123 progress for the 主备切换中，
DR instance. 请在增量恢复
Perform this 中或增量恢复
operation when 失败时执行该
incremental 操作。
restoration is in
progress or
failed.
400 DBS.06 Switchover 灾备实例处于 检查当前实例的容灾状态。
020124 failed for the 主备切换失
DR instance. 败，请在增量
Perform this 恢复中或增量
operation when 恢复失败时执
incremental 行该操作。
restoration is in
progress or
failed.
400 DBS.06 Full restoration 灾备实例处于 检查当前实例的容灾状
020125 in progress for 全量恢复中， 态。。
the DR instance. 请在增量恢复
Perform this 中或增量恢复
operation when 失败时执行该
incremental 操作。
restoration is in
progress or
failed.
400 DBS.06 Full restoration 灾备实例处于 检查当前实例的容灾状态。
020126 failed for the 全量恢复失
DR instance. 败，请在增量
Perform this 恢复中或增量
operation when 恢复失败时执
incremental 行该操作。
restoration is in
progress or
failed.
400 DBS.06 Promotion to 灾备实例处于 检查当前实例的容灾状态。
020127 primary in 升主中，请在
progress for the 增量恢复中或
DR instance. 增量恢复失败
Perform this 时执行该操
operation when 作。
incremental
restoration is in
progress or
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 268
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Promotion to 灾备实例处于 检查当前实例的容灾状态。
020128 primary failed 升主失败，请
for the DR 在增量恢复中
instance. 或恢复同步失
Perform this 败时执行该操
operation when 作。
incremental
restoration is in
progress or
failed.
400 DBS.06 No DR 无容灾该状态 检查当前实例的容灾状态。
020129 relationship 中，请在增量
established for 同步中执行该
the instance. 操作。
Perform this
operation when
incremental
synchronization
is in progress.
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020130 synchronization 量同步中，请
in progress for 在增量同步中
the primary 执行该操作。
instance.
Perform this
operation when
incremental
synchronization
is in progress.
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020131 synchronization 量复制失败，
failed for the 请在增量同步
primary 中执行该操
instance. 作。
Perform this
operation when
incremental
synchronization
is in progress.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 269
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 主实例增量同 检查当前实例的容灾状态。
020132 synchronization 步失败，请在
failed for the 增量同步中执
primary 行该操作。
instance.
Perform this
operation when
incremental
synchronization
is in progress.
400 DBS.06 Switchover is in 主备切换中， 检查当前实例的容灾状态。
020133 progress. 请在增量同步
Perform this 中执行该操
operation when 作。
incremental
synchronization
is in progress.
400 DBS.06 Switchover 主备切换失 检查当前实例的容灾状态。
020134 failed. Perform 败，请在增量
this operation 同步中执行该
when 操作。
incremental
synchronization
is in progress.
400 DBS.06 Full restoration 灾备实例全量 检查当前实例的容灾状态。
020135 in progress for 恢复中，请在
the DR instance. 增量恢复中执
Perform this 行该操作。
operation when
incremental
restoration is in
progress.
400 DBS.06 Full restoration 灾备实例全量 检查当前实例的容灾状态。
020136 failed for the 恢复失败，请
DR instance. 在增量恢复中
Perform this 执行该操作。
operation when
incremental
restoration is in
progress.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 270
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 灾备实例增量 检查当前实例的容灾状态。
020137 synchronization 同步失败，请
failed for the 在增量恢复中
DR instance. 执行该操作。
Perform this
operation when
incremental
restoration is in
progress.
400 DBS.06 Promotion to 灾备实例升主 检查当前实例的容灾状态。
020138 primary in 中，请在增量
progress for the 恢复中执行该
DR instance. 操作。
Perform this
operation when
incremental
restoration is in
progress.
400 DBS.06 Promotion to 灾备实例升主 检查当前实例的容灾状态。
020139 primary failed 失败，请在增
for the DR 量恢复中执行
instance. 该操作。
Perform this
operation when
incremental
restoration is in
progress.
400 DBS.06 No DR 主实例处于无 检查当前实例的容灾状态。
020140 relationship 容灾状态，请
established for 在增量同步中
the primary 或增量同步失
instance. 败时执行该操
Perform this 作。
operation when
incremental
synchronization
is in progress or
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 271
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020141 synchronization 量同步中，请
in progress for 在增量同步中
the primary 或增量同步失
instance. 败时执行该操
Perform this 作。
operation when
incremental
synchronization
is in progress or
failed.
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020143 synchronization 量同步失败，
failed for the 请在增量同步
primary 中或增量同步
instance. 失败时执行该
Perform this 操作。
operation when
incremental
synchronization
is in progress or
failed.
400 DBS.06 Switchover in 主实例处于主 检查当前实例的容灾状态。
020144 progress for the 备切换中，请
primary 在增量同步中
instance. 或增量同步失
Perform this 败时执行该操
operation when 作。
incremental
synchronization
is in progress or
failed.
400 DBS.06 Switchover 主实例处于主 检查当前实例的容灾状态。
020145 failed for the 备切换失败，
primary 请在增量同步
instance. 中或增量同步
Perform this 失败时执行该
operation when 操作。
incremental
synchronization
is in progress or
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 272
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020146 synchronization 量同步中，请
in progress for 在无容灾状态
the primary 或主实例全量
instance. 复制失败时执
Perform this 行该操作。
operation when
there is no DR
relationship or
full
synchronization
failed.
400 DBS.06 Incremental 主实例处于增 检查当前实例的容灾状态。
020147 synchronization 量同步中，请
in progress for 在无容灾状态
the primary 或主实例全量
instance. 复制失败时执
Perform this 行该操作。
operation when
there is no DR
relationship or
full
synchronization
failed.
400 DBS.06 Incremental 主实例增量同 检查当前实例的容灾状态。
020148 synchronization 步失败，请在
failed for the 无容灾状态或
primary 实例全量复制
instance. 失败执行该操
Perform this 作。
operation when
there is no DR
relationship or
full
synchronization
failed.
400 DBS.06 Switchover in 主备切换中， 检查当前实例的容灾状态。
020149 progress. 请在无容灾状
Perform this 态或实例全量
operation when 复制失败执行
there is no DR 该操作。
relationship or
full
synchronization
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 273
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Switchover 主备切换失 检查当前实例的容灾状态。
020150 failed. Perform 败，请在无容
this operation 灾状态或主实
when there is 例全量复制失
no DR 败时执行该操
relationship or 作。
full
synchronization
failed.
400 DBS.06 Full restoration 灾备实例处于 检查当前实例的容灾状态。
020151 in progress for 全量恢复中，
the DR instance. 请在无容灾状
Select an 态时执行该操
instance 作。
without a DR
relationship as
DR instance.
400 DBS.06 Incremental 灾备实例增量 检查当前实例的容灾状态。
020152 restoration in 恢复中，请在
progress for the 无容灾状态时
primary 执行该操作。
instance.
Perform this
operation when
there is no DR
relationship.
400 DBS.06 Incremental 灾备实例增量 检查当前实例的容灾状态。
020153 restoration 恢复失败，请
failed for the 在无容灾状态
DR instance. 时执行该操
Perform this 作。
operation when
there is no DR
relationship.
400 DBS.06 Promotion to 灾备实例升主 检查当前实例的容灾状态。
020154 primary in 中，请在无容
progress for the 灾状态时执行
DR instance. 该操作。
Perform this
operation when
there is no DR
relationship.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 274
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Promotion to 灾备实例升主 检查当前实例的容灾状态。
020155 primary failed 失败，请在无
for the DR 容灾状态时执
instance. 行该操作。
Perform this
operation when
there is no DR
relationship.
400 DBS.06 This operation 主备切换中， 检查当前实例的容灾状态。
020156 cannot be 不支持当前操
performed 作。
because there is
a switchover in
progress for the
primary
instance.
400 DBS.06 This operation 主备切换失 检查当前实例的容灾状态。
020157 cannot be 败，不支持当
performed 前操作。
because a
switchover
failed.
400 DBS.06 This operation 灾备实例全量 检查当前实例的容灾状态。
020158 cannot be 恢复中，不支
performed 持当前操作。
because there is
a full
restoration for
the DR instance.
400 DBS.06 This operation 灾备实例升主 检查当前实例的容灾状态。
020159 cannot be 中，不支持当
performed 前操作。
because the DR
instance is
being promoted
to primary.
400 DBS.06 This operation 灾备实例升主 检查当前实例的容灾状态。
020160 cannot be 中，不支持当
performed 前操作。
because the DR
instance failed
to be promoted
to primary.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 275
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 主实例处于增 主实例处于增量同步失败，
020175 synchronization 量同步失败， 请在增量同步中执行该操
failed for the 请在增量同步 作。
primary 中执行该操
instance. 作。
Perform this
operation when
incremental
synchronization
is in progress.
400 DBS.06 Switchover 灾备实例处于 灾备实例处于主备切换失
020177 failed for the 主备切换失 败，请在增量恢复中执行该
DR instance. 败，请在增量 操作。
Perform this 恢复中执行该
operation when 操作。
incremental
restoration is in
progress.
400 DBS.06 Incremental 灾备实例处于 灾备实例处于增量恢复失
020180 restoration 增量恢复失 败，请在增量恢复中执行该
failed for the 败，请在增量 操作。
DR instance. 恢复中执行该
Perform this 操作。
operation when
incremental
restoration is in
progress.
400 DBS.06 The xlog_keep_radi xlog_keep_radio字段非法
020161 xlog_keep_radio o字段非法
field is invalid.
400 DBS.06 This operation is 不支持此容灾 不支持此容灾操作。
020162 not supported. 操作。
400 DBS.06 This feature is 此功能特性未 此功能特性未启用，请在运
280105 not enabled. 启用。 维管理平台开启相关特性白
名单。
400 DBS.06 This operation is dorado一致性 dorado一致性组id不支持当
010012 not allowed in 组状态不允许 前的操作，请检查一致性态
the current 当前操作。 状态。
status of the
Dorado
consistency
group.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 276
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 The database 单副本实例当 请升级实例至数据库最新版
0662 version of 前版本不支持 本。
Single-replica 该操作
instances does
not support this
operation.
400 DBS.06 One or more 创建SCHEMA 请检查SCHEMA是否重复 或
280102 schemas failed 部分失败或者 者 不合规
to be created. 多个全部失败
400 DBS.06 The new 新密码不能与 请输入符合要求的新密码
280006 password must 旧密码相同或
be different 相反
from the old
password or the
old password in
reverse order.
400 DBS.06 One or more 授权数据库账 请检查授权账户及权限是否
280103 database 户失败或者多 正确
accounts failed 个全部失败
to be
authorized.
400 DBS.06 Invalid encoding 创建数据库时 请指定有效的编码格式
280051 format. 指定的编码格
式无效
400 DBS.06 The LC_CTYPE 创建数据库时 请指定有效的LC_CTYPE 或
280052 and 指定的 LC_COLLATE 参数值
LC_COLLATE LC_CTYPE和
values are LC_COLLATE值
invalid. 无效
400 DBS.06 The schema SCHEMA已存 请输入新SCHEMA
280008 already exists. 在
400 DBS.06 Parameter error: 调用接口时填 请重新填写为正确的参数。
010013 $ 写的参数错
{parameterNam 误。
e}/$
{parameterValu
e}
400 DBS.20 Invalid node 实例节点角色 请检查节点角色 或者 节点状
0075 role. 无效。 态是否正常。
400 DBS.06 The schema SCHEMA不存 请输入有效的SCHEMA
280007 does not exist. 在
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 277
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.21 Permission 没有权限。 检查账号是否权限不足。
6003 denied.
400 DBS.06 Table not found. 表不存在。 检查表是否不存在。
280009
400 DBS.06 Table already 表已存在。 检查表是否已存在。
280010 exists.
400 DBS.06 Maximum 库表数量超过 检查库表的数量是否超过最
280013 number of 最大限制。 大限制。
databases or
tables exceeded.
400 DBS.06 Inconsistent 库表信息不一 检查每个库表数据，参数是
280016 database or 致。 否一致。
table
information in
the parameter.
400 DBS.06 Invalid backup 备份类别非 检查备份类别是否正确。
280017 type. 法。
400 DBS.06 The new 新库名非法。 检查新库名是否不合规。
280018 database name
is invalid.
400 DBS.06 The new 新SCHEMA非 检查新SCHEMA是否不合
280019 schema name is 法。 规。
invalid.
400 DBS.06 The new table 新表名非法。 检查新表名是否不合规。
280020 name is invalid.
400 DBS.06 The backup file 备份文件和备 检查备份文件和备份类别是
280023 does not match 份类别不匹 否匹配。
the backup 配。
type.
400 DBS.06 New OS does 备份恢复到新 检查原实例操作系统是否匹
280032 not match 实例，操作系 配。
original 统不匹配。
instance.
400 DBS.06 The selected 资源类型：$ 检查当前资源类型是否支持
280033 deployment {resourceType} 创建该形态的实例。
model of the $ ，暂不支持创
{resourceType} 建该部署形态
type cannot be 的实例。
created.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 278
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 This method is 当前单节点实 检查单节点实例升级约束。
280034 not available for 例版本不支持
single-node 该升级操作。
instances
version..
400 DBS.06 The current 当前引擎版本 检查创建实例选择的数据库
013044 engine version 不支持创建 版本是否支持IPv6。
does not IPv6实例。
support IPv6
instance
creation.
400 DBS.06 kms type not 不支持当前 检查当前使用的KMS主密钥
280031 support. KMS密钥加密 是否为SM4/AES。
类型
400 DBS.20 Instance not 当前实例不支 检查当前实例状态。
0960 support kms- 持下发透明加
tde. 密。
400 DBS.21 Invalid engine 当前引擎不支 检查当前实例的引擎版本。
6045 version. 持下发该操
作。
400 DBS.20 The storage 新实例卷大小 请检查原实例和目前实例磁
0073 space of the 不得小于旧实 盘大小 。
new DB 例卷大小。
instance cannot
be less than
that of the
original DB
instance.
400 DBS.06 No nodes 实例不存在正 请检查原实例节点状态。
010015 available for 常的节点。
this instance.
400 DBS.06 Kernel status 内核状态已经 请检查实例状态和任务流状
010016 changed not 变更，不支持 态。
support 清理资源。
resource
cleaning.
400 DBS.06 Failed to obtain 获取实例磁盘 检查获取磁盘信息的远程接
010018 the instance 信息失败。 口是否调用成功或者磁盘信
volume 息处理是否出现异常。
information.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 279
云数据库 GaussDB
API 参考 6 附录
6.4 获取项目 ID/名称
操作场景
在调用接口的时候，部分URL中需要填入项目编号，所以需要获取到项目编号。获取
方式如下：
步骤1 使用浏览器，以VDC管理员或VDC业务员帐号登录ManageOne。
非B2B场景登录地址：https://ManageOne运营面的访问地址。例如，https://
console.demo.com。
B2B场景登录地址：https://ManageOne租户面的访问地址。例如，https://
tenant.demo.com。
步骤2 在页面右上角单击用户图标，在下拉列表中选择“个人设置”。
步骤3 在资源空间列表中获取对应区域的ID，即项目ID（project_id）。
同时可获取资源空间名称，即项目名称。
----结束
6.5 获取终端节点
获取 GaussDB 服务的终端节点
GaussDB服务的Endpoint信息由服务名、Region ID、外部域名三部分组成，格式为：
{service_name}.{region0_id}.{external_global_domain_name}
其中{service_name}、{region0_id}和{external_global_domain_name}的获取方式
具体如下：
● {service_name}：服务名缩写，不区分大小写，例如gaussdb。
● {region0_id}：请在安装时导出的汇总文件《xxx__export_all_CN.xlsm》的“1.2
基本参数”页签中查找region0_id。
● {external_global_domain_name}：请在安装时导出的汇总文件
《xxx__export_all_CN.xlsm》的“1.2基本参数”页签中查找
external_global_domain_name。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 280
云数据库 GaussDB
API 参考 6 附录
说明
调用GaussDB API前，首先需要在本地计算机上进行如下的hosts配置：
{apigw_float_ip} {service_name}.{region0_id}.{external_global_domain_name}
● {apigw_float_ip} ： 在底座安装安装工程导出汇总文件《xxx__export_all_CN.xlsm》的
“2.1 工具生成的ip参数”页签中查找参数名为AGW-LB-Float-IP对应的IP地址。
● {service_name}：服务名缩写，不区分大小写，例如gaussdb。
● {region0_id}：请在安装时导出的汇总文件《xxx__export_all_CN.xlsm》的“1.2基本参数”
页签中查找region0_id。
● {external_global_domain_name}：请在安装时导出的汇总文件
《xxx__export_all_CN.xlsm》的“1.2基本参数”页签中查找
external_global_domain_name。
示例：
172.202.2.10 gaussdb.sa-fb-1.songshanghu-x86-1.com
获取 IAM 服务的终端节点
IAM服务的终端节点在DBS运维管理平台的“配置管理 > 系统参数管理”页签搜索
“iamEndpoint”获取，截取“https://”后的值。例如：
iam-cache-proxy.sa-fb-1.songshanghu-x86-1.com:26335
说明
调用接口获取Token前，首先需要在本地计算机上进行如下的hosts配置：
{mo_float_ip} {iam_url}
● {mo_float_ip}: 在底座安装安装工程导出汇总文件《xxx__export_all_CN.xlsm》的“2.1 工具
生成的ip参数”页签中查找参数名为ManageOne-Tenant-Float-IP对应的IP地址。在多个
region场景下，请查找当前提供Global服务的主region的底座安装工程。
● {iam_url}: 截取“iamEndpoint”参数值中“https://”与“:26335”之间的值。
样例值：
172.202.0.119 iam-cache-proxy.sa-fb-1.songshanghu-x86-1.com
6.6 ReplicationMode 列表
ReplicationMode列表
同步模式 描述 备注
sync 同步模式 -
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 281
云数据库 GaussDB
API 参考 6 附录
6.7 数据库实例规格
本章介绍GaussDB提供的实例性能规格。
表 6-4 实例性能规格
规格 规格编码 vCPU(个) 内存(GB)
鲲鹏通用 gaussdb.opengauss.ee.ld.2xlarg 8 64
型 e.arm8.ha
gaussdb.opengauss.ee.ld.4xlarg 16 128
e.arm8.ha
gaussdb.opengauss.ee.ld.8xlarg 32 256
e.arm8.ha
gaussdb.opengauss.ee.ld.15xlar 60 480
ge.arm8.ha
gaussdb.opengauss.ee.ld.20xlar 80 640
ge.arm8.ha
gaussdb.opengauss.ee.ld.2xlarg 8 64
e.arm8.co
gaussdb.opengauss.ee.ld.4xlarg 16 128
e.arm8.co
gaussdb.opengauss.ee.ld.8xlarg 32 256
e.arm8.co
gaussdb.opengauss.ee.ld.15xlar 60 480
ge.arm8.co
gaussdb.opengauss.ee.ld.20xlar 80 640
ge.arm8.co
裸金属服 gaussdb.opengauss.ee.bms.4xla 16 64
务器 rge.x864.ha
gaussdb.opengauss.ee.bms.8xla 32 128
rge.x864.ha
gaussdb.opengauss.ee.bms.16xl 64 256
arge.x864.ha
gaussdb.opengauss.ee.bms.24xl 96 256
arge.x863.ha
gaussdb.opengauss.ee.bms.24xl 96 512
arge.x865.ha
gaussdb.opengauss.ee.bms.24xl 96 768
arge.x868.ha
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 282
云数据库 GaussDB
API 参考 6 附录
规格 规格编码 vCPU(个) 内存(GB)
gaussdb.opengauss.ee.bms.24xl 96 1024
arge.x868.ha
gaussdb.opengauss.ee.bms.26xl 104 1024
arge.x868.ha
gaussdb.opengauss.ee.bms.32xl 128 512
arge.x864.ha
gaussdb.opengauss.ee.bms.32xl 128 768
arge.x866.ha
gaussdb.opengauss.ee.bms.64xl 256 1024
arge.x864.ha
gaussdb.opengauss.ee.bms.4xla 16 64
rge.x864.co
gaussdb.opengauss.ee.bms.8xla 32 128
rge.x864.co
gaussdb.opengauss.ee.bms.16xl 64 256
arge.x864.co
裸金属服 gaussdb.opengauss.ee.enh.bms 96 1024
务器（增 .24xlarge.x868.ha
强型网
关） gaussdb.opengauss.ee.enh.bms 104 1024
.26xlarge.x868.ha
通用增强 gaussdb.opengauss.ee.dn.m6.2 8 64
II型 xlarge.8.ha
说明
该规格不能用于生产环境。
gaussdb.opengauss.ee.c3.2xlarg 8 32
e.x864.ha
gaussdb.opengauss.ee.c3.4xlarg 16 64
e.x864.ha
gaussdb.opengauss.ee.dn.m6.4 16 128
xlarge.8.ha
gaussdb.opengauss.ee.c3.8xlarg 32 128
e.x864.ha
gaussdb.opengauss.ee.dn.m6.8 32 256
xlarge.8.ha
gaussdb.opengauss.ee.c3.16xlar 64 256
ge.x864.ha
gaussdb.opengauss.ee.dn.m6.1 64 512
6xlarge.8.ha
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 283
云数据库 GaussDB
API 参考 7 修订记录
7 修订记录
发布日期 更新特性
2023-03-30 第一次正式发布。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 284
2.23.07.210
API 参考
文档版本 01
发布日期 2023-10-30
华为云计算技术有限公司
版权所有 © 华为云计算技术有限公司 2023。 保留一切权利。
非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传
播。
商标声明
和其他华为商标均为华为技术有限公司的商标。
本文档提及的其他所有商标或注册商标，由各自的所有人拥有。
注意
您购买的产品、服务或特性等应受华为云计算技术有限公司商业合同和条款的约束，本文档中描述的全部或部
分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为云计算技术有限公司对本文
档内容不做任何明示或暗示的声明或保证。
由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文
档中的所有陈述、信息和建议不构成任何明示或暗示的担保。
华为云计算技术有限公司
地址： 贵州省贵安新区黔中大道交兴功路华为云数据中心 邮编：550029
网址： https://www.huaweicloud.com/
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 i
云数据库 GaussDB
API 参考 目 录
目 录
1 使用前必读.................................................................................................................................. 1
1.1 概述.............................................................................................................................................................................................. 1
1.2 调用说明......................................................................................................................................................................................1
1.3 终端节点......................................................................................................................................................................................1
1.4 约束限制......................................................................................................................................................................................1
1.5 基本概念......................................................................................................................................................................................1
2 API 概览...................................................................................................................................... 3
3 如何调用 API...............................................................................................................................4
3.1 构造请求......................................................................................................................................................................................4
3.2 认证鉴权......................................................................................................................................................................................7
3.3 返回结果......................................................................................................................................................................................8
4 API（推荐）............................................................................................................................. 10
4.1 实例管理................................................................................................................................................................................... 10
4.1.1 创建数据库实例................................................................................................................................................................... 10
4.1.2 删除数据库实例................................................................................................................................................................... 21
4.1.3 查询数据库实例列表.......................................................................................................................................................... 22
4.1.4 同城切换 AZ......................................................................................................................................................................... 35
4.1.5 分片节点主备切换.............................................................................................................................................................. 36
4.1.6 查询实例的组件列表.......................................................................................................................................................... 39
4.1.7 实例主备状态重置.............................................................................................................................................................. 44
4.1.8 查询实例主备平衡状态......................................................................................................................................................46
4.1.9 查询实例扩展信息.............................................................................................................................................................. 47
4.1.10 设置实例扩展信息............................................................................................................................................................ 49
4.1.11 启动实例/节点................................................................................................................................................................... 50
4.1.12 停止实例/节点................................................................................................................................................................... 52
4.1.13 切换透明加密.....................................................................................................................................................................54
4.1.14 结束空闲会话.....................................................................................................................................................................56
4.1.15 结束会话............................................................................................................................................................................. 58
4.1.16 获取实时会话.....................................................................................................................................................................60
4.2 参数配置................................................................................................................................................................................... 62
4.2.1 获取参数模板列表.............................................................................................................................................................. 62
4.2.2 获取指定实例的参数.......................................................................................................................................................... 65
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 ii
云数据库 GaussDB
API 参考 目 录
4.2.3 修改指定实例的参数.......................................................................................................................................................... 67
4.2.4 创建参数模板....................................................................................................................................................................... 69
4.2.5 删除参数模板....................................................................................................................................................................... 72
4.2.6 查询参数模板详情.............................................................................................................................................................. 73
4.2.7 复制参数模板....................................................................................................................................................................... 76
4.2.8 重置参数组........................................................................................................................................................................... 78
4.2.9 比较两个参数组模板之间的差异.................................................................................................................................... 79
4.2.10 查询可应用实例列表........................................................................................................................................................81
4.2.11 校验参数组名称是否存在............................................................................................................................................... 83
4.2.12 应用参数模板.....................................................................................................................................................................84
4.2.13 查询参数模板的应用记录............................................................................................................................................... 86
4.2.14 查询参数模板的修改历史............................................................................................................................................... 88
4.3 备份管理................................................................................................................................................................................... 90
4.3.1 查询备份列表....................................................................................................................................................................... 90
4.3.2 创建手动备份....................................................................................................................................................................... 94
4.3.3 删除手动备份....................................................................................................................................................................... 98
4.3.4 查询可恢复时间段.............................................................................................................................................................. 99
4.3.5 恢复到新实例.....................................................................................................................................................................101
4.3.6 恢复到当前实例................................................................................................................................................................ 113
4.3.7 备份恢复后执行数据确认............................................................................................................................................... 118
4.3.8 查询差量备份列表............................................................................................................................................................ 119
4.3.9 安装三方备份 SSL 证书................................................................................................................................................... 122
4.4 引擎版本和规格.................................................................................................................................................................... 124
4.4.1 查询引擎列表.....................................................................................................................................................................124
4.5 管理数据库和用户............................................................................................................................................................... 125
4.5.1 创建数据库......................................................................................................................................................................... 126
4.5.2 创建数据库用户................................................................................................................................................................ 128
4.5.3 创建数据库 SCHEMA...................................................................................................................................................... 130
4.5.4 授权数据库帐号................................................................................................................................................................ 132
4.5.5 重置数据库帐号密码........................................................................................................................................................135
4.5.6 查询数据库列表................................................................................................................................................................ 137
4.5.7 查询数据库用户列表........................................................................................................................................................139
4.5.8 查询数据库 SCHEMA 列表.............................................................................................................................................141
4.6 容灾管理................................................................................................................................................................................. 143
4.6.1 查询容灾集群监控状态................................................................................................................................................... 144
4.6.2 查询容灾关系列表............................................................................................................................................................ 145
4.6.3 搭建容灾关系.....................................................................................................................................................................149
4.6.4 备实例容灾升主................................................................................................................................................................ 151
4.6.5 解除容灾关系.....................................................................................................................................................................152
4.6.6 灾备实例主从切换............................................................................................................................................................ 154
4.6.7 重建容灾关系.....................................................................................................................................................................156
4.6.8 开启容灾演练.....................................................................................................................................................................157
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 iii
云数据库 GaussDB
API 参考 目 录
4.6.9 结束容灾演练.....................................................................................................................................................................159
4.6.10 开启日志保持.................................................................................................................................................................. 161
4.6.11 结束日志保持.................................................................................................................................................................. 163
4.6.12 重置容灾配置.................................................................................................................................................................. 164
4.7 任务管理................................................................................................................................................................................. 166
4.7.1 获取任务信息.....................................................................................................................................................................166
5 历史 API.................................................................................................................................. 169
5.1 实例管理................................................................................................................................................................................. 169
5.1.1 创建数据库实例................................................................................................................................................................ 169
5.1.2 删除数据库实例................................................................................................................................................................ 178
5.1.3 查询数据库实例列表........................................................................................................................................................180
5.1.4 同城切换 AZ....................................................................................................................................................................... 193
5.1.5 实例主备状态重置............................................................................................................................................................ 195
5.1.6 查询实例主备平衡状态................................................................................................................................................... 196
5.2 备份管理................................................................................................................................................................................. 198
5.2.1 查询备份列表.....................................................................................................................................................................198
5.2.2 创建手动备份.....................................................................................................................................................................202
5.2.3 删除手动备份.....................................................................................................................................................................204
5.2.4 恢复到新实例.....................................................................................................................................................................205
5.3 容灾管理（V3.1）............................................................................................................................................................... 215
5.3.1 查询可搭建容灾实例列表............................................................................................................................................... 215
5.3.2 容灾操作校验.....................................................................................................................................................................217
5.3.3 查询容灾集群监控状态................................................................................................................................................... 219
5.3.4 查询容灾关系列表............................................................................................................................................................ 222
5.3.5 搭建容灾关系.....................................................................................................................................................................225
5.3.6 备实例容灾升主................................................................................................................................................................ 227
5.3.7 解除容灾关系.....................................................................................................................................................................229
5.3.8 灾备实例主从切换............................................................................................................................................................ 231
5.3.9 重建容灾关系.....................................................................................................................................................................232
5.3.10 开启容灾演练.................................................................................................................................................................. 233
5.3.11 结束容灾演练.................................................................................................................................................................. 235
5.3.12 开启日志保持.................................................................................................................................................................. 236
5.3.13 结束日志保持.................................................................................................................................................................. 238
6 附录......................................................................................................................................... 240
6.1 异常请求结果........................................................................................................................................................................ 240
6.2 状态码..................................................................................................................................................................................... 240
6.3 错误码..................................................................................................................................................................................... 243
6.4 获取项目 ID/名称................................................................................................................................................................. 280
6.5 获取终端节点........................................................................................................................................................................ 280
6.6 ReplicationMode 列表....................................................................................................................................................... 281
6.7 数据库实例规格.................................................................................................................................................................... 282
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 iv
云数据库 GaussDB
API 参考 目 录
7 修订记录................................................................................................................................. 284
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 v
云数据库 GaussDB
API 参考 1 使用前必读
1 使用前必读
1.1 概述
GaussDB是华为自主创新研发的分布式关系型数据库。该产品支持分布式事务，同城
跨AZ部署，数据0丢失，支持1000+的扩展能力，PB级海量存储。同时拥有云上高可
用，高可靠，高安全，弹性伸缩，一键部署，快速备份恢复，监控告警等关键能力，
能为企业提供功能全面，稳定可靠，扩展性强，性能优越的企业级数据库服务。
您可以使用本文档提供API对数据库实例进行相关操作，如创建、删除等。支持的全部
操作请参见API概览。
1.2 调用说明
GaussDB提供了REST（Representational State Transfer）风格API，支持您通过
HTTPS请求调用，调用方法请参见API概览。
1.3 终端节点
终端节点（Endpoint）即调用API的请求地址，不同服务不同区域的终端节点不同，您
需要提前联系企业管理员，获取终端节点。
1.4 约束限制
详细的限制请参见具体API的说明。
1.5 基本概念
● 帐号
用户注册时的帐号，帐号对其所拥有的资源及云服务具有完全的访问权限，可以
重置用户密码、分配用户权限等。为了确保帐号安全，建议您不要直接使用帐号
进行日常管理工作。
● 用户
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 1
云数据库 GaussDB
API 参考 1 使用前必读
用户是云服务的使用人员，具有身份凭证（密码和访问密钥）。
您需要用到帐号、用户和密码等信息。
● 区域
指云资源所在的物理位置，同一区域内可用区间内网互通，不同区域间内网不互
通。通过在不同地区创建云资源，可以将应用程序设计的更接近特定客户的要
求，或满足不同地区的法律或其他要求。
● 可用区
一个可用区是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上
再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高
速光纤相连，以满足用户跨AZ构建高可用性系统的需求。
● 资源集
用户只有和资源集关联，在界面中即用户只有和资源集关联了同一个用户组，才
可以申请或管理资源，其中用户申请的资源就属于该资源集，从而实现资源分
组。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 2
云数据库 GaussDB
API 参考 2 API 概览
2 API 概览
通过使用GaussDB接口，您可以使用GaussDB的创建实例、删除实例等功能。
类型 子类型 说明
GaussDB 接口 实例管理 包括创建实例、删除实例、查询实例列表接口。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 3
云数据库 GaussDB
API 参考 3 如何调用 API
3 如何调用 API
3.1 构造请求
本节介绍REST API请求的组成，并以调用IAM服务获取用户Token说明如何调用API。
该API获取用户的Token，Token可以用于调用其他API时鉴权。
请求 URI
请求URI由如下部分组成：
{URI-scheme}://{Endpoint}/{resource-path}?{query-string}
尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传
递它，所以在此单独强调。
表 3-1 URI 中的参数说明
参数 描述
URI-scheme 表示用于传输请求的协议，当前所有API均采用HTTPS协议。
Endpoint 指定承载REST服务端点的服务器域名或IP，不同服务不同区域的
Endpoint不同，您可以从获取IAM服务的终端节点获取。
resource-path 资源路径，即API访问路径。从具体API的URI模块获取，例如“获
取用户Token”API的resource-path为“/v3/auth/tokens”。
query-string 查询参数，是可选部分，并不是每个API都有查询参数。查询参数
前面需要带一个“？”，形式为“参数名=参数取值”，例如
“limit=10”，表示查询不超过10条数据。
说明
为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。
这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分
省略。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 4
云数据库 GaussDB
API 参考 3 如何调用 API
请求方法
HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。
表 3-2 HTTP 方法
方法 说明
GET 请求服务器返回指定资源。
PUT 请求服务器更新指定资源。
POST 请求服务器新增资源或执行特殊操作。
DELETE 请求服务器删除指定资源，如删除对象等。
在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为：
POST https://{{Endpoint}}/v3/auth/tokens
请求消息头
附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请
求头“Content-Type”，请求鉴权信息等。
详细的公共请求消息头字段请参见表3-3。
表 3-3 公共请求消息头
名称 描述 是否必选 示例
Host 请求的服务器信 否 code.test.com
息，从服务API的 or
URL中获取。值为
hostname[:port]。 code.test.com:443
端口缺省时使用默
认的端口，https的
默认端口为443。
Content-Type 发送的实体的MIME 是 application/json
类型。推荐用户默
认使用application/
json，如果API是对
象、镜像上传等接
口，媒体类型可按
照流类型的不同进
行确定。
Content- 请求body长度，单 否 3495
Length 位为Byte。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 5
云数据库 GaussDB
API 参考 3 如何调用 API
名称 描述 是否必选 示例
X-Project-Id project id，项目编 否 e9993fc787d94b6c886cb
号。请参考获取项 aa340f9c0f4
目ID/名称章节获取
项目编号。
X-Auth-Token 用户Token。 否 注：以下仅为Token示例片
用户Token也就是调 使用Token认 段
用获取用户Token接 证时该字段必 MIIPAgYJKoZIhvcNAQcCo
口的响应值，该接 选。 ...ggg1BBIINPXsidG9rZ
口是唯一不需要认
证的接口。
请求响应成功后在
响应消息头中包含
的“X-Subject-
Token”的值即为
Token值。
对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加
消息头后的请求如下所示。
POST https://{{Endpoint}}/v3/auth/tokens
Content-Type: application/json
请求消息体（可选）
该部分可选。请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中
Content-Type对应，传递除请求消息头之外的内容。若请求消息体中的参数支持中
文，则中文字符必须为UTF-8编码。
每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消
息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根
据具体接口而定。
对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。
将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中
username为用户名，domainname为用户所属的帐号名称，********为用户登录密
码，xxxxxxxxxxxxxxxxxx为project的名称，您可以从管理员处获取。
说明
scope参数定义了Token的作用域，上面示例中获取的Token仅能访问project下的资源。您还可
以设置Token的作用域为某个帐号下所有资源或帐号的某个project下的资源，详细定义请参见获
取用户Token。
POST https://{{Endpoint}}/v3/auth/tokens
Content-Type: application/json
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 6
云数据库 GaussDB
API 参考 3 如何调用 API
"name": "username",
"password": "********",
"domain": {
"name": "domainname"
}
}
}
},
"scope": {
"project": {
"name": "xxxxxxxxxxxxxxxxxx"
}
}
}
}
到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编
写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x-
subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认
证调用其他API。
3.2 认证鉴权
调用接口需进行Token认证鉴权。
Token认证：通过Token认证调用请求。
Token 认证
说明
Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。
Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。
Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得
操作API的权限。
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"name": "username",
"password": "********",
"domain": {
"name": "domainname"
}
}
}
},
"scope": {
"project": {
"name": "xxxxxxxx"
}
}
}
}
在构造请求中以调用获取用户Token接口为例说明了如何调用API。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 7
云数据库 GaussDB
API 参考 3 如何调用 API
获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，
其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token:
ABCDEFJ....”加到请求消息头即可，如下所示。
POST https://{{Endpoint}}/v3/auth/projects
Content-Type: application/json
X-Auth-Token: ABCDEFJ....
3.3 返回结果
状态码
请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。
状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码
列表请参见状态码。
对于获取用户Token接口，如果调用后返回状态码为“201”，则表示请求成功。
响应消息头
对应请求消息头，响应同样也有消息头，如“Content-type”。
对于获取用户Token接口，返回如图3-1所示的消息头，其中“x-subject-token”就是
需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。
图 3-1 获取用户 Token 响应消息头
响应消息体（可选）
该部分可选。响应消息体通常以结构化格式（如JSON或XML）返回，与响应消息头中
Content-Type对应，传递除响应消息头之外的内容。
对于获取用户Token接口，返回如下消息体，为篇幅起见，这里只展示部分内容。
{
"token": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 8
云数据库 GaussDB
API 参考 3 如何调用 API
"expires_at": "2019-02-13T06:52:13.855000Z",
"methods": [
"password"
],
"catalog": [
{
"endpoints": [
{
"region_id": "az-01",
......
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 9
云数据库 GaussDB
API 参考 4 API（推荐）
4 API（推荐）
4.1 实例管理
4.1.1 创建数据库实例
功能介绍
创建GaussDB实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/054ea741f700d4a32f1bc00f5c80dd4c/instances
● 参数说明
表 4-1 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项
目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 10
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
表 4-2 参数说明
名称 是否必 参数类型 说明
选
name 是 String 实例名称。
用于表示实例的名称，同一租户下，同类型
的实例名可重名。
取值范围：4~64个字符之间，必须以字母
开头，区分大小写，可以包含字母、数字、
中划线或者下划线，不能包含其他的特殊字
符。
datastore 是 Object 数据库信息。
详情请参见表4-3。
ha 是 Object 实例部署形态。详情请参见表4-4。
configuration_i 否 String 参数模板ID。当不传该参数时，使用系统默
d 认的参数模板，且响应体中不返回该参数
port 否 String GaussDB数据库端口当前只支持设置为
8000，当不传该参数时，默认端口为
8000。
password 是 String 数据库密码。
GaussDB密码取值范围:
非空； 至少包含大写字母（A-Z），小写字
母（a-z），数字（0-9），非字母数字字符
（限定为~!@#$%^&*()-_=+|[{}];:,<>/?）四
类字符中的三类字符；长度8~32个字符。
建议您输入高强度密码，以提高安全性，防
止出现密码被暴力破解等安全风险。
backup_strateg 否 Object 备份策略。
y 详情请参见表4-5。
enterprise_proje 否 String 企业项目ID。创建指定企业项目实例时必
ct_id 选。
flavor_ref 是 String 规格码，取值范围：非空。参考数据库实例
规格中GaussDB的“规格编码”列内容获
取。
volume 是 Object volume信息。
详情请参见表4-6。
region 是 String 区域ID。
取值范围：非空，请向企业管理员获取。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 11
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必 参数类型 说明
选
availability_zon 是 String 可用区ID。
e GaussDB取值范围：非空，可选部署在同一
可用区或三个不同可用区，可用区之间用逗
号隔开。详见请求示例。
● 部署在同一可用区：需要输入三个相同
的可用区。
● 部署在三个不同可用区：需要分别输入
三个不同的可用区。
取值范围：非空，请向企业管理员获取。
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界
面，在虚拟私有云的详情页面查找VPC
ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询VPC列表”的内容。
subnet_id 是 String 子网的网络ID信息，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界
面，单击VPC下的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询子网列表”的内容。
security_group_ 是 String 指定实例所属的安全组。
id ● 方法1：登录虚拟私有云服务的控制台界
面，在安全组的详情页面查找安全组
ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询安全组列表”的内
容。
charge_info 否 Object 计费类型信息。
详情请参见表4-7。
time_zone 否 String UTC时区。
● 不选择时，GaussDB默认为UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且只支持整段
时间，如UTC+08:00，不支持UTC
+08:30。
solution 是 String GaussDB支持的部署模式，ha字段选择为
“ha”时必填，当前可选的有triset。
kms_tde_key_id 否 String GaussDB使用透明加密的KMS主密钥ID，填
写ID启用透明加密功能。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 12
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必 参数类型 说明
选
kms_project_na 否 String kms_tde_key_id不为空时必传。GaussDB使
me 用透明加密的KMS主密钥ID所在资源空间名
称。
获取方法请参见获取项目ID/名称。
表 4-3 datastore 字段数据结构说明
名称 是 参数类型 说明
否
必
选
type 是 String 数据库引擎，取值如下：
GaussDB。不区分大小写。
version 否 String 数据库版本。不填时，默认为当前最新版
本。
GaussDB支持如下版本：
● 1.3
● 1.4
● 2.1
● 2.2
● 2.3
● 2.5
● 2.7
● 2.8
● 3.200
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 13
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-4 ha 字段数据结构说明
名称 是 参数类型 说明
否
必
选
mode 是 String GaussDB当前只支持创建主备模式，取
值：
centralization_standard：主备模式，不区
分大小写。
说明
参数填写为ha，也可以下发主备模式的实例，
但是不建议使用，保留该取值是为了兼容历史取
值。
consistency 是 String 指定事务一致性类型，取值范围：strong
（强一致性） | eventual(最终一致性)，不
分区大小写。
replication_mode 是 String 备机同步参数。
取值：
GaussDB为“sync"
说明
“sync”为同步模式。
consistency_proto 否 String 指定副本一致性协议类型，取值范围：
col ● quorum：quorum模式是主备同步复制
机制，客户端发起事务后，必须要等待
对应的WAL日志复制到多个副本后，主
库才会响应给客户端，少数节点的宕机
不影响全局可用性，保证数据的一致
性。
● paxos：该模式解决了quorum模式下日
志复制过程中日志分叉的问题，提高日
志复制吞吐量，增加DN自仲裁能力。
不区分大小写。不填时，默认为quorum。
说明
开放
“gaussdb_feature_supportSetConsistencyProt
ocol”白名单后，支持创建paxos协议实例，且
仅支持3.200及以上版本的主备版实例。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 14
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-5 backup_strategy 字段数据结构说明
名称 是 参数类型 说明
否
必
选
start_time 是 String 备份时间段。自动备份将在该时间段内触
发。
取值范围：非空且非负，格式必须为
hh:mm-HH:MM且有效，当前时间指UTC
时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值必须
为00。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days 否 Integer 指定备份文件的可保存天数。
取值范围： 1-36500，开放
“gaussdb_feature_supportConsoleBack
upPolicyDay_36500”白名单后，支持备
份文件最长保留天数36500天。该参数缺
省时，默认填写为7天。
表 4-6 volume 字段数据结构说明
名称 是否 参数类型 说明
必选
type 是 String 磁盘类型。
LOCALSSD：主备模式都支持，表示本地
SSD盘。
ULTRAHIGH：仅ECS部署形态支持，表示
云磁盘。
size 是 Integer 磁盘大小。例如：该参数填写为“40”，
表示为创建的实例分配40GB的磁盘空间。
ECS部署方案：取值范围：（分片数
*40GB）~（分片数*16TB），且大小只能
为分片数*40的整数倍。
MCS部署方案：取值范围：（分片数
*40GB）~（分片数*16TB），且大小只能
为分片数*40的整数倍。
BMS部署方案：该参数由所选择的规格自
动计算，不可指定，即使填写，也不会生
效。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 15
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-7 chargeInfo 字段数据结构说明
名称 是否 参数类型 说明
必选
charge_mode 是 String 计费模式。
请求示例
创建主备版实例：
{
"name": "user_v3_ha_01",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"volume": {
"type": "LOCALSSD",
"size": "120"
},
"region": "sa-fb-1",
"availability_zone": "az4.dc0,az4.dc0,az4.dc0",
"vpc_id": "c0a17a45-5e4a-4166-9cd6-cf9846f776a2",
"subnet_id": "ba239f09-7b59-4233-80c9-af2b418803ae",
"security_group_id": "093807ac-4d7a-44c6-b554-b3460dab50cf",
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 7
},
"charge_info": {
"charge_mode": "postPaid"
},
"password": "xxxxxx",
"configuration_id": "26f22545846040d1a02163a068b6b3a3pr14",
"time_zone": "UTC+08:00",
"ha":{
"mode":"ha",
"consistency":"strong",
"replication_mode":"sync" ,
"consistency_protocol":"quorum"
},
"port": "8000",
"solution": "triset"
}
响应消息
● 正常响应要素说明
表 4-8 要素说明
名称 参数类型 说明
instance Object 实例信息。
详情请参见表4-9。
job_id String 实例创建的任务id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 16
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-9 instance 说明
名称 参数类型 说明
id String 实例id。
name String 实例名称。用于表示实例的名称，同一
租户下，同类型的实例名称可相同。
取值范围：4~64个字符之间，必须以
字母开头，不区分大小写，可以包含字
母、数字、中划线或者下划线，不能包
含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
datastore Object 数据库信息。
详情请参见表4-10。
ha Object 数据库部署形态。
详情请参见表4-11。
replica_num Integer 实例副本数。
configuration_id String 参数模板id，仅当您创建实例指定用户
自定义参数组时，该参数才可见。
port String 数据库端口信息，与请求参数相同。
backup_strategy Object 自动备份策略。
详情请参见表4-12。
flavor_ref String 规格码，取值范围：非空。参考数据库
实例规格中GaussDB的“规格编码”列
内容获取。
volume Object volume信息。
详情请参见表4-13。
region String 区域ID。
availability_zone String 可用区ID。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
security_group_id String 实例所属的安全组。
charge_info Object 付费方式信息。
详情请参见表4-14。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 17
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-10 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎，返回值如下：
GaussDB
version String 数据库版本。
表 4-11 ha 字段数据结构说明
名称 参数类型 说明
mode String GaussDB支持取值：ha(solution为triset
时选择)enterprise(企业版) ，不区分大小
写。
replication_ String 备机同步参数。
mode 取值：
GaussDB为“sync”。
说明
“sync”为同步模式。
consistency String GaussDB的预留参数：指定事务一致性类
型，取值范围：strong（强一致性） |
eventual(最终一致性)。
consistency_ String 指定副本一致性协议类型，取值范围：
protocol quorum | paxos。不填时，默认为
quorum。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 18
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-12 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内
触发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值必
须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
如果请求体中不填写
“backup_strategy”字段，则响应体中
“start_time”默认返回
“02:00-03:00”。
keep_days Integer 指定已生成备份文件的可保存天数。
取值范围：1～732。如果请求体中不填
写“backup_strategy”字段，则响应体
中 “keep_days”默认填写为30天。
表 4-13 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
取值如下，区分大小写：
● LOCALSSD，表示本地SSD盘。
● ULTRAHIGH，区分大小写，表示云磁
盘。
size Integer 磁盘大小。
GaussDB分布式实例创建时需指定大
小：要求必须为（分片数 * 40GB）的倍
数，取值范围：（分片数*40GB）~（分
片数*16TB）。
表 4-14 charge_Info 字段数据结构说明
名称 参数类型 说明
charge_mode String 计费模式。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 19
云数据库 GaussDB
API 参考 4 API（推荐）
● 正常响应样例
{
"instance": {
"id": "2afb68bc983742308f7a878581762a49in14",
"name": "user_v3_ha_01",
"status": "BUILD",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"ha": {
"mode": "centralization_standard",
"replication_mode": "sync",
"consistency": "strong",
"consistency_protocol":"quorum"
},
"port": "8000",
"volume": {
"type": "LOCALSSD",
"size": 120
},
"region": "sa-fb-1",
"replica_num": 3,
"configuration_id": "26f22545846040d1a02163a068b6b3a3pr14",
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 7
},
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"availability_zone": "az3.dc0,az3.dc0,az3.dc0",
"vpc_id": "aaefc937-c12e-449a-9907-604827337999",
"subnet_id": "ebeaece0-c16c-42aa-a546-0d42d0c68956",
"security_group_id": "290af3b6-289b-4014-a336-b98da9c4fa8e",
"charge_info": {
"charge_mode": "postPaid"
}
},
"job_id": "d7b73e60-4237-43d0-9007-097b7678495d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 20
云数据库 GaussDB
API 参考 4 API（推荐）
4.1.2 删除数据库实例
功能介绍
删除数据库实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14
● 参数说明
表 4-15 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项
目ID/名称。
instance_id 是 实例ID。
请求消息
无
响应消息
● 正常响应要素说明
表 4-16 要素说明
名称 参数类型 说明
job_id String 实例删除的任务id
● 正常响应样例：
{
"job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 21
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.3 查询数据库实例列表
功能介绍
根据指定条件查询实例列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/instances?
id={id}&name={name}&type={type}&datastore_type={datastore_type}&vpc_id
={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit}
● URI样例
– 查询所有实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/97b026aa9cc4417888c14c84a1ad9860/instances
– 根据指定条件查询实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/97b026aa9cc4417888c14c84a1ad9860/instances?
id=ed7cc6166ec24360a5ed5c5c9c2ed726in14&name=hy&type=Centralizat
ion_standard&datastore_type=GaussDB&vpc_id=19e5d45d-70fd-4a91-87e
9-
b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offs
et=0&limit=10
● 参数说明
表 4-17 参数说明
名称 参数类 是否 说明
型 必选
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 22
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类 是否 说明
型 必选
id String 否 实例ID。
“*”为系统保留字符，如果id是以“*”起
始，表示按照*后面的值模糊匹配，否则，按
照id精确匹配查询。不能只传入“*”。
name String 否 实例名称。
“*”为系统保留字符，如果name是以“*”
起始，表示按照*后面的值模糊匹配，否则，
按照name精确匹配查询。不能只传入“*”。
type String 否 按照实例类型查询。目前支持取值如下：
● Enterprise（区分大小写），对应分布式实
例（独立部署）（已废弃）。
● Centralization_standard（区分大小
写），对应主备版实例。
● Combined（区分大小写），对应分布式实
例（混合部署）。
datastore_ String 否 数据库类型，不区分大小写。
type GaussDB
vpc_id String 否 虚拟私有云ID，获取方法如下：。
● 方法1：登录虚拟私有云服务的控制台界
面，在虚拟私有云的详情页面查找VPC
ID。
● 方法2：获取方法请参见《虚拟私有云API
参考》中“查询VPC列表”的内容。
subnet_id String 否 子网的网络ID信息。
● 方法1：登录虚拟私有云服务的控制台界
面，单击VPC下的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚拟私有云
(VPC) 使用指南 》的API参考中“查询子
网列表”的内容。
offset Integer 否 索引位置，偏移量。从第一条数据偏移offset
条数据后开始查询，默认为0（偏移0条数
据，表示从第一条数据开始查询），必须为数
字，不能为负数。
limit Integer 否 查询记录数。默认为100，不能为负数，最小
值为1，最大值为100。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 23
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类 是否 说明
型 必选
charge_mo String 否 计费模式。
de 取值范围：
postPaid：后付费，即按需付费。
prePaid：预付费，即 包年/包月。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-18 参数说明
名称 参数类型 说明
instances Array of objects 实例信息。
详情请参见表4-19。
total_count Integer 总记录数。
表 4-19 instances 字段数据结构说明
名称 参数类型 说明
id String 实例ID。
name String 创建的实例名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 24
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
status String 实例状态。
取值：
值为“BUILD”，表示实例正在创建。
值为“ACTIVE”，表示实例正常。
值为“FAILED”，表示实例异常。
值为“MODIFYING”，表示实例正在
扩容磁盘或者变更规格。
值为“EXPANDING”，表示实例正在
扩容。
值为“REBOOTING”，表示实例正在
重启。
值为“UPGRADING”，表示实例正在
升级。
值为“RESTORING”，表示实例正在恢
复。
值为“SWITCHOVER”，表示实例正在
主备切换。
值为“MIGRATING”，表示实例正在
迁移。
值为“BACKING UP”，表示实例正在
进行备份。
值为“REBALANCING”，表示实例正
在进行主备分布均衡。
值为“UPGRADE TO BE
OBSERVED”，表示实例正在进行升级
待观察。
值为“STORAGE FULL”，表示实例磁
盘空间满。
值为”REPAIRING”，表示实例正在修
复。
private_ips List<String> 实例内网IP地址列表。分布式CN所在的
弹性云服务器创建成功后该值存在，主
备版DN所在的弹性云服务器创建成功
后该值存在，其他情况下为空字符串。
port Integer 数据库端口号。GaussDB数据库端口当
前只允许为8000。
type String 实例类型，取值为
"centralization_standard"，对应于主
备版实例。区分大小写。
ha Object 实例的高可用参数。
详情请参见表4-20。
replica_num Integer 实例副本数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 25
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
region String 实例所在区域。
datastore Object 数据库信息。
详情请参见表4-21。
created String 创建时间，格式为“yyyy-mm-dd
hh:mm:ss timezone”。
其中timezone是指时区。
说明：创建时该值为实例下发创建的时
间，创建完成后，该值为创建完成时
间。
updated String 更新时间，格式与“created”字段对应
格式完全相同。
说明：创建时返回值为空，数据库实例
创建成功后该值不为空。
db_user_name String 默认用户名。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
security_group_ String 安全组ID。
id
flavor_ref String 规格码。参考数据库实例规格中
GaussDB的“规格编码”列内容获取。
flavor_info Object 规格信息。
详情请参见表4-22
volume Object Volume信息。
详情请参见表4-23。
backup_strateg Object 备份策略。
y 详情请参见表4-24。
maintenance_w String 可维护时间窗，为UTC时间。
indow
nodes Array of objects 实例节点信息。
详情请参见表4-25。
enterprise_proje String 企业项目标签ID。0代表非企业项目。
ct_id
instance_mode String enterprise代表数据库版本为企业版。
time_zone String 时区。
charge_info Object 计费类型信息，支持按需。
详情请参见表4-26。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 26
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
kms_tde_key_id String kms秘钥ID。
kms_project_na String kms秘钥在某一region下的资源空间名
me 称。
表 4-20 ha 字段数据结构说明
名称 参数类型 说明
consistency String 事务一致性类型。取值为“strong”、
“eventual”，分别表示强一致性、最终
一致性。
replication_mo String 备机同步参数。
de 取值：非空。
GaussDB为 “sync”
说明
“sync”为同步模式。
consistency_pro String 副本一致性协议类型，取值范围：
tocol ● quorum：quorum模式是主备同步复
制机制，客户端发起事务后，必须要等
待对应的WAL日志复制到多个副本后，
主库才会响应给客户端，少数节点的宕
机不影响全局可用性，保证数据的一致
性。
● paxos：该模式解决了quorum模式下
日志复制过程中日志分叉的问题，提高
日志复制吞吐量，增加DN自仲裁能
力。
表 4-21 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎。
version String 数据库大版本，两位数。
complete_versi String 数据库小版本，三位数。
on
hotfix_versions String 数据库已升级的热补丁版本，当数据库热
补丁升级成功后，该值不为空。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 27
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-22 flavor_info 字段数据结构说明
名称 参数类型 说明
vcpu Integer cpu核数。
mem Integer 内存大小，单位GB。
表 4-23 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
size Integer 磁盘大小。
表 4-24 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内触
发。
当前时间指UTC时间。
keep_days Integer 已生成的备份文件可以保存的天数。
取值范围：1～732。
表 4-25 nodes 字段数据结构说明
名称 参数类型 说明
id String 节点ID。
name String 节点名称。
role String 节点类型，取值为“master”、
“slave”，分别对应于主节点、备节点。
status String 节点状态。
availability_zon String 可用区。
e
data_ip String 数据IP。
management_i String 管理IP。
p
bms_hs_ip String 高速网卡IP，bms实例特有的IP字段，用
于数据同步。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 28
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-26 charge_info 字段数据结构说明
名称 参数类型 说明
charge_mode String 计费模式。
postPaid：后付费，即按需付费。
● 正常响应样例
实例列表：
{
"instances": [
{
"id": "b331ed66cc3249f78bc20737308c01f4in14",
"status": "ACTIVE",
"name": "gauss-9e88",
"port": 8000,
"type": "Enterprise",
"ha": {
"consistency": "strong",
"replication_mode": "sync",
"consistency_protocol":"quorum"
},
"region": "eu-de",
"datastore": {
"type": "GaussDB",
"version": "2.7",
"complete_version": "2.7.2",
"hotfix_versions": "2.7.2.1,2.7.2.2"
},
"created": "2021-01-15 01:46:40 UTC",
"updated": "2021-01-15 02:05:03 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 120
},
"nodes": [
{
"id": "02ebf757aaf94074855f49cc6e0e4712no14",
"name": "gauss-9e88_gaussdbv5cn_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz",
"private_ip": "192.168.16.253"
},
{
"id": "0a87b8ecbfeb46aba1409cfc0f0d5c34no14",
"name": "gauss-9e88_gaussdbv5cn_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz",
"private_ip": "192.168.28.81"
},
{
"id": "2d9fec1ab3834936b074d63acf48b1f2no14",
"name": "gauss-9e88_gaussdbv5dn3_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 29
云数据库 GaussDB
API 参考 4 API（推荐）
{
"id": "48bb08a2d635435891ac0caa1c0bf2e3no14",
"name": "gauss-9e88_gaussdbv5dn1_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "5df830f652204827ada32f8bc28b107eno14",
"name": "gauss-9e88_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "8a97a246cee841b38c5b47290d4c9c38no14",
"name": "gauss-9e88_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz",
"private_ip": "192.168.27.52"
},
{
"id": "8c1a3f8eecca4d9e9974a868bb6dd942no14",
"name": "gauss-9e88_gaussdbv5dn2_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "9bd0c80b8a684cc9bd7d99dd5adffb07no14",
"name": "gauss-9e88_gaussdbv5dn3_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "9e2a3cd541e249d4af5aa57c5d3a7f39no14",
"name": "gauss-9e88_gaussdbv5dn1_2",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b046d28989ec4ae5a1a9ab20fe65f248no14",
"name": "gauss-9e88_gaussdbv5dn2_2",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b614cc12fd3742dbb230245f88a7bf00no14",
"name": "gauss-9e88_gaussdbv5dn3_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "caba8e88c3c84ae58202f1f589490611no14",
"name": "gauss-9e88_gaussdbv5dn2_1",
"role": "slave",
"status": "ACTIVE",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 30
云数据库 GaussDB
API 参考 4 API（推荐）
"availability_zone": "az2xahz"
}
],
"private_ips": [
"192.168.16.253 / 192.168.28.81 / 192.168.27.52"
],
"replica_num": 3,
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "prePaid"
},
"backup_strategy": {
"start_time": "19:00-20:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab",
"enterprise_project_id": "6e76681b-a2f5-4c5f-97c5-ba4fd3c0dfb2",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
},
{
"id": "226b4afcfcc84c86bf1b9cb345d3b00fin14",
"status": "ACTIVE",
"name": "UTS-gauss-ad53-2C3D",
"port": 8000,
"type": "Enterprise",
"ha": {
"consistency": "strong",
"replication_mode": "sync",
"consistency_protocol":"paxos"
},
"region": "cn-xianhz-1",
"datastore": {
"type": "GaussDB",
"version": "2.7",
"complete_version": "2.7.2",
"hotfix_versions": "2.7.2.1,2.7.2.2"
},
"created": "2021-01-08 09:18:27 UTC",
"updated": "2021-01-14 13:25:03 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 120
},
"nodes": [
{
"id": "07538a1def584cee99e2a5685eeab36ano14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 31
云数据库 GaussDB
API 参考 4 API（推荐）
},
{
"id": "21f41baba1e2454f82331b7cb5aeabe5no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "2909771a3b3e4e3998f9388e77d22391no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "2bd9a90a5da242a6b0743a7f597f6106no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "77092f1dadb74d3ea13d28269cdd3590no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "a46bfaa6d5a24355a60fce7432b964cano14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "aa5277736f3844e2a7adeb9de529e2b1no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b1d798e4ea7344dfa95032984bc6cfd7no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz",
"private_ip": "192.168.29.231"
},
{
"id": "b9a46540186f4c0781eabaa2a79594cbno14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "d283813030364060ab64371d50294977no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_0",
"role": "slave",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 32
云数据库 GaussDB
API 参考 4 API（推荐）
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "eb7bce29b2284cd290405eaddc1b1a1eno14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_0",
"role": "master",
"status": "FAILED",
"availability_zone": "az2xahz",
"private_ip": "192.168.30.44",
"public_ip": "10.154.217.248"
}
],
"private_ips": [
"192.168.29.231 / 192.168.30.44"
],
"public_ips": [
"10.154.217.248"
],
"replica_num": 3,
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "prePaid"
},
"backup_strategy": {
"start_time": "18:00-19:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
}
],
"total_count": 2
}
● 实例详情：
{
"instances": [
{
"id": "034fbefcf4bf4bd99d72cc396b8a32bein14",
"status": "ACTIVE",
"name": "gauss-ba01-llz",
"port": 8000,
"type": "centralization_standard",
"ha": {
"consistency": "strong",
"replication_mode": "sync",
"consistency_protocol":"quorum"
},
"region": "sa-fb-2",
"datastore": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 33
云数据库 GaussDB
API 参考 4 API（推荐）
"type": "GaussDB",
"version": "2.6"
},
"created": "2022-12-23 09:48:34 UTC",
"updated": "2022-12-25 14:10:31 UTC",
"volume": {
"type": "LOCALSSD",
"size": 160
},
"nodes": [
{
"id": "89e15cd8da28410590cd0257cc1012ffno14",
"name": "gauss-ba01-llz_root_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "mcsAZ3.dc2"
},
{
"id": "ed9a727be38545c5a2d1471f6d11ee77no14",
"name": "gauss-ba01-llz_root_2",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "mcsAZ3.dc2"
},
{
"id": "fc1f2540f0484b10adedd7ce6ae3eac4no14",
"name": "gauss-ba01-llz_root_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "mcsAZ3.dc2"
}
],
"private_ips": [
"172.168.1.163 / 172.168.1.10 / 172.168.1.22"
],
"replica_num": 3,
"db_user_name": "root",
"vpc_id": "4aed8010-b0bb-4e48-96c2-fbbbcaec9fa8",
"subnet_id": "44da393a-9813-4838-9bd8-c9e77443aa22",
"security_group_id": "0727106a-9cad-420d-9b1b-85953785bf4f",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"flavor_info": {
"vcpu": 8,
"mem": 64
},
"charge_info": {
"charge_mode": "postPaid"
},
"backup_strategy": {
"start_time": "19:00-20:00",
"keep_days": 30
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode": "enterprise"
}
],
"total_count": 1
}
● 异常响应
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 34
云数据库 GaussDB
API 参考 4 API（推荐）
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.4 同城切换 AZ
功能介绍
切换主DN组至对应AZ。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
注意事项
切换完成后，可能会导致集群主备分布不均衡，如果需要将集群重新切回均衡状态，
可以参考实例主备状态重置，将集群主备状态切回。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
switch-az
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/switch-az
● 参数说明
表 4-27 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 35
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-28 参数说明
名称 是否必选 参数类型 说明
availability_zone 是 String 需要将主DN切换到的AZ。
● 请求样例
{
"availability_zone": "az3.dc0"
}
响应消息
● 正常响应要素说明
表 4-29 要素说明
名称 参数类型 说明
job_id String 同城切换AZ的任务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.5 分片节点主备切换
功能介绍
支持用户对单个或多个DN分片做主备切换，同一分组内只能指定一个新的备节点进行
升主操作。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 36
云数据库 GaussDB
API 参考 4 API（推荐）
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
switch-shard
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/switch-shard
● 参数说明
表 4-30 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-31 参数说明
名称 是否必选 参数类型 说明
shards 是 Array 节点列表，支持对单个或者
多个DN分片做主备切换。
节点信息为将要升主的备
DN分片对应的节点
id(node_id)和组件
id(component_id)。具体请
参考表4-32。
表 4-32 shards 参数说明
名称 是否必选 参数类型 说明
node_id 是 String 将要升主的备DN的节点
Id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 37
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
component_id 是 String 将要升主的备DN的组件
Id。最大长度7个字符，不
能为null或者空字符串，不
能为空格，校验和使用之前
会自动过滤掉前后空格。至
少包含大写字母（A-Z），
小写字母（a-z），数字
（0-9），非字母数字字符
（限定为_）四类字符中的
三类字符。组件id通过查询
实例的组件列表获取。
请求示例
切换多个DN分片的主备。
{
"shards": [
{
"node_id": "0bc478b4d132494a8f7b804da521b4b2no14",
"component_id": "dn_6001"
},
{
"node_id": "53dee94c50574d36a0060db0a6b644f6no14",
"component_id": "dn_6004"
}
]
}
响应消息
● 正常响应要素说明
表 4-33 要素说明
名称 参数类型 说明
job_id String 分片节点主备切换的任
务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 38
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.6 查询实例的组件列表
功能介绍
查询实例的所有组件信息。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
components
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dd93e98e103b4fc4b5a978a6bd6f03a9in14/components
● 参数说明
表 4-34 参数说明
名称 参 是否必选 说明
数
类
型
project_id stri 是 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
instance_id stri 是 实例ID。
ng
limit int 否 查询记录数。默认为100，不能为负
ege 数，最小值为1，最大值为100。例如该
r 参数设定为10，则查询结果最多只显示
10条记录。
offset int 否 索引位置，偏移量。从第一条数据偏移
ege offset条数据后开始查询，默认为0（偏
r 移0条数据，表示从第一条数据开始查
询），必须为数字，不能为负数。例
如：该参数指定为0，limit指定为10，
则只展示第1-10条数据。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 39
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参 是否必选 说明
数
类
型
component_ty stri 否 组件类型，过滤拿到需要的组件类型的
pe ng 组件信息，默认为ALL。传参数会查询
对应组件信息， "ALL": 查询所有组件类
型。 "CM": 查询CMS组件类型。枚举
值：
● ALL
● CN
● DN
● CM
● GTM
● ETCD
availability_zo stri 否 主组件所在可用区编号，筛选符合条件
ne_id ng 的组件，默认为ALL，查询实例所有可
用区上的节点的组件信息。 当调用接口
传入可用区编号时： 相对于DN组件，
会查询出的DN分片中的主组件在该可用
区上的这个分片的所有副本的组件信
息。 相对于CN组件，CN组件没有主备
关系，会查询出该可用区上的CN组件信
息。 相对于其他组件，会查询该可用区
上有没有某个组件类型的主组件，有则
会返回该组件类型的所有组件信息，没
有则不返回该组件类型的信息。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-35 要素说明
名称 参数类型 说明
nodes Array of objects 组件详情。
详情请参见表4-36。
total_count integer 总记录数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 40
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-36 nodes 说明
名称 参数类型 说明
id string 节点id。
components Array of 该实例节点下的组件信息列表，详情请
objects 参见查询实例的组件列表。
name string 节点名字。
availability_zone_i string 节点所在可用区编码。
d
description string 可用区描述信息。
status string 节点状态。
表 4-37 components 说明
名称 参数类型 说明
id string 组件id。
GTM：Global Transaction Manager，
全局事务管理器。用于管理事务状态的
部件。
CMS：Cluster Management Server，
集群管理组件。是用于管理集群状态的
部件。
DN：Data Node，和CN对应的概念。
负责实际执行表数据的存储、查询操
作。
CN：Coordinator Node，负责数据库
系统元数据存储、查询任务的分解和部
分执行，以及将DN中查询结果汇聚在
一起。
ETCD：Editable Text Configuration
Daemon，分布式键值存储系统，用于
共享配置和服务发现（服务注册和查
找）。
role string 节点角色。
master：组件所在节点为主节点。
slave：组件所在节点为备节点。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 41
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
status string 组件状态。
Primary：该组件为主。
Normal：该组件状态正常。
Down：该组件处于宕机状态。
Standby：该组件为备。
StateFollower：该ETCD为备。
StateLeader：该ETCD为主。
StateCandidate：该ETCD为仲裁。
distributed_id string 分组ID，只有DN组件有分组DN，用于
区分是否是同一个分片下的组件。其他
组件为空字符串。
type string 节点类型，包括：DN, CN, GTM, CM,
ETCD。
detail string 详情。
● 正常响应样例
{
"nodes": [
{
"components": [
{
"id": "cm_1",
"role": "master",
"status": "Primary",
"distributed_id": ""，
"type" : "CM",
"detail" : ""
},
{
"id": "etcd_7001",
"role": "master",
"status": "StateLeader",
"distributed_id": ""，
"type" : "ETCD",
"detail" : ""
},
{
"id": "dn_6001",
"role": "master",
"status": "Primary",
"distributed_id": "60011"，
"type" : "DN",
"detail" : "Normal"
}
],
"id": "7d19f72f8f514564bd92962a6fbddb7dno14",
"name": "gauss-9e1a_root_0",
"availability_zone_id": "cn-southwest-244a",
"description": "az1",
"status": "normal"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 42
云数据库 GaussDB
API 参考 4 API（推荐）
{
"components": [
{
"id": "cm_3",
"role": "slave",
"status": "Standby",
"distributed_id": ""，
"type" : "CM",
"detail" : ""
},
{
"id": "etcd_7003",
"role": "slave",
"status": "StateFollower",
"distributed_id": ""，
"type" : "ETCD",
"detail" : ""
},
{
"id": "dn_6003",
"role": "slave",
"status": "Standby",
"distributed_id": "60011"，
"type" : "DN",
"detail" : "Normal"
}
],
"id": "aafc2e14234d4c9eadb481fb0a09a865no14",
"name": "gauss-9e1a_root_2",
"availability_zone_id": "cn-southwest-244a",
"description": "az1",
"status": "normal"
},
{
"components": [
{
"id": "cm_2",
"role": "slave",
"status": "Standby",
"distributed_id": ""，
"type" : "CM",
"detail" : ""
},
{
"id": "etcd_7002",
"role": "slave",
"status": "StateFollower",
"distributed_id": ""，
"type" : "ETCD",
"detail" : ""
},
{
"id": "dn_6002",
"role": "slave",
"status": "Standby",
"distributed_id": "60011"，
"type" : "DN",
"detail" : "Normal"
}
],
"id": "d6c6c6e6b48c41d79d99d7240751d744no14",
"name": "gauss-9e1a_root_1",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 43
云数据库 GaussDB
API 参考 4 API（推荐）
"availability_zone_id": "cn-southwest-244a",
"description": "az1",
"status": "normal"
}
],
"total_count": 3
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.7 实例主备状态重置
功能介绍
将数据库实例恢复为初始配置的主备状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 实例在创建、变更规格、异常等状态下不能执行该操作。
● 该功能不支持1.x版本的主备版实例。
URI
● URI格式
PUT https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
rebalance
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/rebalance
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 44
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-38 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
请求消息
无。
响应消息
● 正常响应要素说明
响应参数
表 4-39 要素说明
参数 参数类型 描述
job_id String 任务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 45
云数据库 GaussDB
API 参考 4 API（推荐）
4.1.8 查询实例主备平衡状态
功能介绍
查询实例是否发生过主备切换而导致主机负载不均衡。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
balance
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/balance
● 参数说明
表 4-40 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-41 要素说明
名称 参数类型 说明
balanced boolean 平衡状态。显示是否有
集群实例发生过主备切
换而导致主机负载不均
衡。
● 返回"true"，均衡。
● 返回"false"，不均
衡。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 46
云数据库 GaussDB
API 参考 4 API（推荐）
● 正常响应样例
{
"balanced": true
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.9 查询实例扩展信息
功能介绍
查询实例扩展信息。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
extend-info?key={key}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/extend-info?key=BackupSet
● 参数说明
表 4-42 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 47
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 说明
key 是 实例扩展信息key。
枚举值：
● BackupSet：备份集信息。
● XbsaRoute：Xbsa协议下对应的路由
信息。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-43 要素说明
名称 参数类型 说明
key String 实例扩展key，枚举值：
● “BackupSet”，备
份集信息。
● “XbsaRoute”，
Xbsa协议下对应的路
由信息。
value String 实例扩展信息value。
● 正常响应样例
{
"key" : "BackupSet",
"value" : "BackupSetExamples"
}
{
"key" : "XbsaRoute",
"value" : "{\"ip\":\"192.168.1.1\",\"port\":\"8009\"}"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 48
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.1.10 设置实例扩展信息
功能介绍
设置实例扩展信息。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
PUT https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
extend-info
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/extend-info
● 参数说明
表 4-44 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-45 参数说明
名称 是否必选 参数类型 说明
key 是 String 实例扩展key，枚举值：
● “BackupSet”，备份集
信息。
● “XbsaRoute”，Xbsa
协议下对应的路由信
息。
value 是 String 实例扩展信息。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 49
云数据库 GaussDB
API 参考 4 API（推荐）
● 请求示例
{
"key" : "BackupSet",
"value" : "BackupSetExamples"
}
{
"key" : "XbsaRoute",
"value" : "{\"ip\":\"192.168.1.1\",\"port\":\"8009\"}"
}
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.11 启动实例/节点
功能介绍
启动实例/节点。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{endpoint}/v3/{project_id}/instances/{instance_id}/db-startup
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3/
cc94568cb5a54e4a8ab5dff95e64a5e0br14/instances/
d8e6ca5a624745bcb546a227aa3ae1cfin14/db-startup
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 50
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-46 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-47 参数说明
名称 是否必选 参数类型 说明
X-Auth-Token 是 String 用户Token
X-Language 否 String 语言。
缺省值：en-us
枚举值：
● zh-cn
● en-us
表 4-48 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_ids 是 Array of 需要启动的节点的ID，取值
strings 不能为null，如果为空列
表，则启动整个实例
● 请求示例
{
"node_ids":
["187ff420e15c467eaaef226154eb1578no14","4ed9cbb0d61144e0802a82c0ab0e1de5no14"]
}
响应消息
● 正常响应要素说明
表 4-49 参数说明
参数 参数类型 描述
job_id String 启动实例或节点的异步任务ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 51
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-50 参数说明
参数 参数类型 描述
error_code String 错误码。
error_msg String 错误消息。
● 响应示例
{
"job_id" : "bf26cf3c-d046-4080-bb45-f114be7afa5f"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.12 停止实例/节点
功能介绍
停止数据库,同时支持节点级别的停止操作。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-stop
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054e292c9880d4992f02c0196d3ea468/instances/
d8e6ca5a624745bcb546a227aa3ae1cfin14/db-stop
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 52
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-51 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 需要停止的实例的ID。
请求消息
● 参数说明
表 4-52 参数说明
名称 是否必选 参数类型 说明
X-Auth-Token 是 String 用户Token
X-Language 否 String 语言。
缺省值：en-us
枚举值：
● zh-cn
● en-us
表 4-53 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_ids 是 Array of 需要停止的节点的ID，取值
strings 不能为null，如果为空列
表，则停止整个实例。
● 请求示例
{
"node_ids":
["187ff420e15c467eaaef226154eb1578no14","4ed9cbb0d61144e0802a82c0ab0e1de5no14"]
}
响应消息
● 正常响应要素说明
表 4-54 参数说明
参数 参数类型 描述
job_id String 停止实例或节点的异步任务ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 53
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-55 参数说明
参数 参数类型 描述
error_code String 错误码。
error_msg String 错误消息。
● 响应示例
{
"job_id" : "bf26cf3c-d046-4080-bb45-f114be7afa5f"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.13 切换透明加密
功能介绍
切换实例透明加密状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
PUT https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/kms-tde/
switch
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054e292c9880d4992f02c0196d3ea468/instances/
d8e6ca5a624745bcb546a227aa3ae1cfin14/kms-tde/switch
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 54
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-56 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例的ID。
请求消息
● 参数说明
表 4-57 请求 Body 参数说明
名称 是否必选 参数类型 说明
kms_tde_key_id 是 String KMS主密钥ID。
kms_tde_status 是 String 需要切换的状态。
枚举值：
● on：开启
kms_project_na 是 String GaussDB使用透明加密的
me KMS主密钥ID所在所在资源
空间名称。
获取方法请参见获取项目
ID/名称
● 请求示例
{
"kms_tde_key_id":"ca0da073-20a4-451d-812d-67f35d4d91f1",
"kms_tde_status":"on",
"kms_project_name":"kms_project_name"
}
响应消息
● 正常响应要素说明
表 4-58 参数说明
参数 参数类型 描述
job_id String 异步任务ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 55
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-59 参数说明
参数 参数类型 描述
error_code String 错误码。
error_msg String 错误消息。
● 响应示例
{
"job_id" : "bf26cf3c-d046-4080-bb45-f114be7afa5f"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.14 结束空闲会话
功能介绍
查杀空闲会话。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 仅支持包含有CN或DN（主、备）组件的节点。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/kill-free-
session
● URI样例
https://{Endpoint}/gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/
instances/cc6fd964d93f4003851dfc29d57d30a5in14/kill-free-session
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 56
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-60 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例的ID。
请求消息
● 参数说明
表 4-61 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_id 是 String 节点ID，仅支持包含有CN
或DN（主、备）组件的节
点。
component_id 是 String 组件ID，仅支持包含有CN
或DN（主、备）组件ID，
且需要是node_id参数上的
组件。
● 请求示例
{
"node_id": "52c25e148a4a48c293b66ca95565719cno14",
"component_id": "cn_5001"
}
响应消息
● 正常响应要素说明
表 4-62 参数说明
参数 参数类型 描述
success Boolean 是否成功。
● 响应示例
{
"success" : true
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 57
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.1.15 结束会话
功能介绍
查杀指定会话列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 仅支持包含有CN或DN（主、备）组件的节点。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/kill-
session
● URI样例
https://{Endpoint}/gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/
instances/cc6fd964d93f4003851dfc29d57d30a5in14/kill-session
● 参数说明
表 4-63 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例的ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 58
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-64 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_id 是 String 节点ID，仅支持包含有CN
或DN（主、备）组件的节
点。
component_id 是 String 组件ID，仅支持包含有CN
或DN（主、备）组件ID，
且需要是node_id参数上的
组件。
session_ids 是 Array of 查杀指定会话ID列表
strings
● 请求示例
{
"node_id": "52c25e148a4a48c293b66ca95565719cno14",
"component_id": "cn_5001",
"session_ids": ["10180"]
}
响应消息
● 正常响应要素说明
表 4-65 参数说明
参数 参数类型 描述
session_ids Array of 成功查杀指定会话ID列表。
strings
success Boolean 是否成功。
● 响应示例
{
"session_ids" : [ 10180 ],
"success" : true
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 59
云数据库 GaussDB
API 参考 4 API（推荐）
4.1.16 获取实时会话
功能介绍
查询数据库实例节点的实时会话列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 仅支持包含有CN或DN（主、备）组件的节点。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/real-time-
session
● URI样例
https://{Endpoint}/gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/
instances/cc6fd964d93f4003851dfc29d57d30a5in14/real-time-session
● 参数说明
表 4-66 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例的ID。
请求消息
● 参数说明
表 4-67 请求 Body 参数说明
名称 是否必选 参数类型 说明
node_id 是 String 节点ID，仅支持包含有CN
或DN（主、备）组件的节
点。
component_id 是 String 组件ID，仅支持包含有CN
或DN（主、备）组件ID，
且需要是node_id参数上的
组件。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 60
云数据库 GaussDB
API 参考 4 API（推荐）
● 请求示例
{
"node_id": "52c25e148a4a48c293b66ca95565719cno14",
"component_id": "cn_5001"
}
响应消息
● 正常响应要素说明
表 4-68 响应 Body 参数
参数 参数类型 描述
sessions 表4-69 数据库实例的实时会话列表。
表 4-69 RealTimeSession 参数说明
参数 参数类型 描述
session_id String 会话ID。
pid String 线程ID。
unique_sql_id String SQL ID。
database_name String 数据库。
client_ip String 客户端IP。
user_name String 用户名。
wait String 是否等待。
block_session String 阻塞会话。
wait_event String 等待事件。
state String 状态。
query_runtime String 语句执行时长。
query String SQL文本。
back_end_start Long 会话开始时间。
transaction_start Long 事务开始时间。
query_start Long 语句开始时间。
application_name String 应用名称。
● 响应示例
{
"sessions" : {
"session_id" : "725",
"pid" : "140623987341056",
"unique_sql_id" : "3545025713",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 61
云数据库 GaussDB
API 参考 4 API（推荐）
"database_name" : "postgres",
"client_ip" : "23.100.74.131",
"user_name" : "root",
"wait" : "f",
"block_session" : "",
"wait_event" : "none",
"state" : "active",
"query_runtime" : "00:00:22.641774",
"query" : "select pg_sleep(100);",
"back_end_start" : 1690448618645,
"transaction_start" : 1690448618689,
"query_start" : 1690448618689,
"application_name" : "gsql"
}
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2 参数配置
4.2.1 获取参数模板列表
功能介绍
获取参数模板列表，包括所有数据库的默认参数模板和用户创建的参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/configurations?
offset={offset}&limit={limit}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/054ea741f700d4a32f1bc00f5c80dd4c/configurations?offset=1&limit=3
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 62
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-70 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。例如：该参数指定为0，
limit指定为10，则只展示第
1-10条数据。
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。例如该参数设定为
10，则查询结果最多只显示10
条记录。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-71 参数说明
参数 参数类型 描述
configuration Array of 参数模板信息，具体参数请参考表4-72。
s objects
count Integer 总记录数。
表 4-72 configurations 字段数据结构说明
参数 参数类型 描述
id String 参数组ID。
name String 参数组名称。
description String 参数组描述。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 63
云数据库 GaussDB
API 参考 4 API（推荐）
参数 参数类型 描述
datastore_ve String 引擎版本。
rsion
datastore_na String 引擎名称。
me
ha_mode String 实例类型。
created String 创建时间，格式为"yyyy-MM-dd
HH:mm:ss"。
updated String 更新时间，格式为"yyyy-MM-dd
HH:mm:ss"。
user_defined Boolean 是否是用户自定义参数模板：
● false，表示为系统默认参数模板。
● true，表示为用户自定义参数模板。
● 正常响应样例
{
"count": 3,
"configurations": [
{
"id": "b000d7c91f1749da87315700793a11d4pr14",
"name": "Default-GaussDB-EE-1.0-Dist-Combined (4 replicas)",
"description": "Default parameter template for GaussDB-Enterprise Edition-1.0-
Distributed-combined (4 replicas)",
"created": "2022-03-23 07:20:11",
"updated": "2022-03-23 07:20:11",
"datastore_version": "1.0",
"datastore_name": "GaussDB",
"ha_mode": "combined",
"user_defined": false
},
{
"id": "8d99f260ea1b4493a1b349e7abce5c09pr14",
"name": "Default-Finance-Edition-GaussDB-1.3-Combined",
"description": "Default parameter template for Finance Edition GaussDB 1.3-
Combined",
"created": "2022-03-23 07:20:11",
"updated": "2022-03-23 07:20:11",
"datastore_version": "1.1",
"datastore_name": "GaussDB",
"ha_mode": "combined",
"user_defined": false
},
{
"id": "0f44b65521a8414d8b8811df810d94ccpr14",
"name": "Default-Finance-Disaster-GaussDB-1.3-Combined",
"description": "Default parameter template for Finance Disaster GaussDB 1.3-
Combined",
"created": "2022-03-23 07:20:11",
"updated": "2022-03-23 07:20:11",
"datastore_version": "1.2",
"datastore_name": "GaussDB",
"ha_mode": "combined",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 64
云数据库 GaussDB
API 参考 4 API（推荐）
"user_defined": false
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.2 获取指定实例的参数
功能介绍
获取指定实例的参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
configurations
● URI样例
https://gaussdb-api.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/054ea741f700d4a32f1bc00f5c80dd4c/instances/dsfae23fsfdsae3435in14/
configurations
● 参数说明
表 4-73 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 65
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
无。
响应消息
● 正常响应要素说明
表 4-74 参数说明
参数 参数类型 描述
datastore_ve String 引擎版本。
rsion
datastore_na String 引擎名称。
me
created String 创建时间，格式为"yyyy-MM-dd
HH:mm:ss"。
updated String 更新时间，格式为"yyyy-MM-ddHH:mm:ss"。
configuration Array of 参数对象，用户基于默认参数模板自定义的参
_parameters objects 数配置，具体请参考表4-75。
表 4-75 configuration_parameters 字段数据结构说明
参数 参数类型 描述
name String 参数名称。
value String 参数值。
restart_requir Boolean 修改该参数是否需要重启实例。
ed
value_range String 参数取值范围。
type String 参数类型，取值为“string”、“integer”、
“boolean”、“list”或“float”之一。
枚举值：
● string
● integer
● boolean
● list
● float
description String 参数描述。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 66
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息示例
● 正常响应要素说明
{
"created": "2022-04-11 10:46:59",
"updated": "2022-04-11 10:46:59",
"datastore_version": "2.0",
"datastore_name": "GaussDB",
"configuration_parameters": [
{
"name": "audit_system_object",
"value": "12295",
"type": "integer",
"description": "Determines whether to audit the CREATE, DROP, and ALTER
operations on GaussDB Kernel database objects. GaussDB Kernel database objects include
databases, users, schemas, and tables. You can change the parameter value to audit only
the operations on required database objects. During a forcible primary/standby failover,
set audit_system_object to the maximum value and audit all DDL objects. If the parameter
value is incorrectly changed, DDL audit logs will be lost. Contact customer service
personnel to change it.",
"restart_required": false,
"value_range": "0-2097151"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.3 修改指定实例的参数
功能介绍
修改指定实例的参数模板参数。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
修改的参数必须在指定数据库版本的默认参数范围内。
URI
● URI格式
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 67
云数据库 GaussDB
API 参考 4 API（推荐）
PUT https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
configurations
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/configurations
● 参数说明
表 4-76 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-77 参数说明
名称 是否必选 参数类型 说明
values 是 Map<String,St 参数值对象，用户基于默认
ring> 参数模板自定义的参数值。
填写示例：对于
"failed_login_attempts":"4
"，其中
"failed_login_attempts"就
是需要修改的参数名，"4"
就是需要将参数修改的值。
请求示例
● 修改实例的参数failed_login_attempts的值为4。不需要重启。
{
"values": {
"failed_login_attempts": "4"
}
}
● 修改实例的参数track_activity_query_size的值为2048，修改参数
max_replication_slots的值为25。需要重启。
{
"values": {
"track_activity_query_size": "2048",
"max_replication_slots": "30"
}
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 68
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-78 要素说明
名称 参数类型 说明
restart_required Boolean 实例是否需要重启。
● “true”需要重启。
● “false”不需要重
启。
● 正常响应样例
– 不需要重启
{
"restart_required": false
}
– 需要重启
{
"restart_required": true
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.4 创建参数模板
功能介绍
创建参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/configurations
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/configurations
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 69
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-79 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
请求消息
● 参数说明
表 4-80 参数说明
名称 是否必选 参数类型 说明
name 是 String 参数模板名称。 取值范
围：长度1到64位之间，区
分大小写字母，可包含字
母、数字、中划线、下划线
或句点，不能包含其他特殊
字符。
description 否 String 参数模板描述，默认为空。
取值范围：长度超过256自
动截取，不能包含回车>!
<"&'=等特殊字符。
parameter_value 否 Map<String,St 参数名和参数值映射关系。
s ring> 用户可以基于默认参数模板
的参数，自定义参数值。
datastore 是 object 数据库引擎信息。可通过
【查询引擎列表】接口查
询。详情请参见表4-81。
表 4-81 datastore 参数说明
名称 是否必选 参数类型 说明
engine_version 是 String 数据库版本。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 70
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
instance_mode 是 String 部署形态。
枚举值：
● ha：主备版
● combined：分布式版
金融版（标准型）
● combined_hcs2：分布
式版 企业版
● combined_hcs3：分布
式版 金融版(标准型)
● combined_hcs4：分布
式版 金融版（数据计算
型，容灾主）
● combined_hcs5：分布
式版 金融版（数据计算
型，容灾备）
请求示例
● 创建一个2.3版本，主备版部署形态的参数模板。
{
"name": "paramTemplate",
"description": "",
"parameter_values": {
"audit_system_object": "12294"
},
"datastore": {
"engine_version": "2.3",
"instance_mode": "ha"
}
}
响应消息
● 正常响应要素说明
表 4-82 参数说明
参数 参数类型 描述
id String 参数模板ID。
name String 参数模板名称。
created_at String 创建时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。 其中，T指某个时间的开
始；Z指时区偏移量，例如北京时间偏移显示
为+0800。
● 正常响应样例
{
"id" : "137eeaf0cc884ca4adffa9ebd101c115pr14",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 71
云数据库 GaussDB
API 参考 4 API（推荐）
"name" : "paramTemplate-del",
"created_at" : "2022-08-09T03:06:52+0800"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.5 删除参数模板
功能介绍
删除参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14
● 参数说明
表 4-83 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
请求消息
无。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 72
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.6 查询参数模板详情
功能介绍
查询参数模板详情，根据参数模板ID获取指定参数模板详情。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14
● 参数说明
表 4-84 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 73
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
无。
响应消息
● 正常响应要素说明
表 4-85 参数说明
参数 参数类型 描述
id String 参数模板ID。
name String 参数模板名称。
description String 参数模板描述。
engine_versi String 引擎版本。
on
instance_mo String 部署形态。
de 枚举值：
● ha：主备版
● combined：分布式版 金融版（标准型）
● combined_hcs2：分布式版 企业版
● combined_hcs3：分布式版 金融版(标准
型)
● combined_hcs4：分布式版 金融版（数据
计算型，容灾主）
● combined_hcs5：分布式版 金融版（数据
计算型，容灾备）
created_at String 创建时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量，
例如北京时间偏移显示为+0800。
updated_at String 修改时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量，
例如北京时间偏移显示为+0800。
configuration Array of 参数详情，具体请参考 表
_parameters objects configuration_parameters字段数据结构说
明。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 74
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-86 configuration_parameters 字段数据结构说明
参数 参数类型 描述
name String 特定参数名称。
value String 特定参数值。
need_restart Boolean 参数是否需要重启。
- 取值为"true"，需要重启。
- 取值为"false"，不需要重启。
readonly Boolean 该参数是否只读。
true：只读
false：可编辑
value_range String 参数取值范围。
data_type String 参数类型，取值为“string”、“integer”、
“boolean”、“list”或“float”之一。
description String 参数描述。
● 正常响应样例
{
"id": "3ca44134a16d4bbab8eb701e025b19f7pr14",
"name": "GaussDB_2b87a799-515",
"description": "ParamGroup for instance.",
"engine_version": "2.3",
"instance_mode": "ha",
"created_at": "2022-08-05T08:15:07+0800",
"updated_at": "2022-08-09T03:06:52+0800",
"configuration_parameters": [
{
"name": "audit_system_object",
"value": "12294",
"need_restart": false,
"readonly": false,
"value_range": "1-65536",
"data_type": "integer",
"description": "该参数决定是否对GaussDB Kernel数据库对象的CREATE、
DROP、ALTER操作进行审计。GaussDB Kernel数据库对象包括DATABASE、USER、schema、
TABLE等。通过修改该配置参数的值，可以只审计需要的数据库对象的操作，在主备强制选主
场景建议audit_system_object取最大值，所有DDL对象全部审计，不当修改该参数会导致丢失
DDL审计日志，请在客服人员指导下进行修改。"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 75
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.7 复制参数模板
功能介绍
复制参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
copy
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/copy
● 参数说明
表 4-87 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 被复制的参数模板ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 76
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-88 参数说明
名称 是否必选 参数类型 说明
name 是 String 复制后的参数模板名称。取
值范围：长度1到64位之
间，区分大小写字母，可包
含字母、数字、中划线、下
划线或句点，不能包含其他
特殊字符。
description 否 String 参数模板描述，默认为空。
取值范围：长度不能超过
256，不能包含回车>!<"&'=
等特殊字符。
请求示例
复制一个参数模板
{
"name" : "paramTemplate-1233",
"description" : "描述"
}
响应消息
● 正常响应要素说明
表 4-89 参数说明
参数 参数类型 描述
config_id String 复制后的参数模板ID。
● 正常响应样例
{
"config_id" : "3ca44134a16d4bbab8eb701e025b19f7pr14"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 77
云数据库 GaussDB
API 参考 4 API（推荐）
4.2.8 重置参数组
功能介绍
重置参数组。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
仅自定义模版才可以重置。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
reset
● URI样例
https://gaussdb.sa-
fb-2.hcsglobal.com/v3/599628f2665841b2a66fa2780fadc025/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/reset
● 参数说明
表 4-90 参数说明
名称 参数类 是否 说明
型 必选
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
config_id String 是 参数模板ID。
请求消息
无。
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 78
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.9 比较两个参数组模板之间的差异
功能介绍
获取两个参数配置模板的差异列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/configurations/comparison
● URI样例
https://gaussdb.sa-
fb-2.hcsglobal.com/v3/0483b6b16e954cb88930a360d2c4e663/configurations/
comparison
● 参数说明
表 4-91 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
请求消息
● 参数说明
表 4-92 参数说明
名称 是否必选 参数类型 说明
source_id 是 String 需要进行比较的参数组模板
ID。
target_id 是 String 需要进行比较的参数组模板
ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 79
云数据库 GaussDB
API 参考 4 API（推荐）
请求示例
查询两个参数组模板的差异列表。
{
"source_id" : "3e9f722f27c9477089bdf576b33f9d8epr14",
"target_id" : "a51fcdde022a4ea8a016a3c4671644f4pr14"
}
响应消息
● 正常响应要素说明
表 4-93 参数说明
参数 参数类型 描述
differences Array of 参数组之间的差异集合。
objects 详情请参见表 differences字段数据结构说明
表 4-94 differences 字段数据结构说明
参数 参数类型 描述
name String 参数名称。
source_value String 比较参数组的参数值。
target_value String 目标参数组的参数值。
● 正常响应样例
{
"differences" : [ {
"name" : "audit_system_object",
"source_value" : "12289",
"target_value" : "12295"
} ]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 80
云数据库 GaussDB
API 参考 4 API（推荐）
4.2.10 查询可应用实例列表
功能介绍
查询可应用当前参数组模板的实例列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
applicable-instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/applicable-instances
● 参数说明
表 4-95 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。例如：该参数指定为0，
limit指定为10，则只展示第
1-10条数据。
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。例如该参数设定为
10，则查询结果最多只显示10
条记录。
请求消息
无。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 81
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-96 参数说明
参数 参数类型 描述
instances Array of 参数模板信息，具体参数请参考表4-97。
objects
total_count Integer 总记录数。
表 4-97 instances 字段数据结构说明
参数 参数类型 描述
instance_id String 实例ID。
instance_na String 实例名称。
me
● 正常响应样例
{
"total_count": 2,
"instances": [
{
"instance_id": "1995a67680474481b3e42ac1474e32e0in14",
"instance_name": "gauss-a283"
},
{
"instance_id": "8303819fd8744ef69f34595e9710a33din14",
"instance_name": "gauss-2423-lt-master"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 82
云数据库 GaussDB
API 参考 4 API（推荐）
4.2.11 校验参数组名称是否存在
功能介绍
校验参数组名称是否存在。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/name-
validation?name={name}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/configurations/name-
validation?name=paramTemplate-a9f3
● 参数说明
表 4-98 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
name 是 String 参数模板名称。 取值范围：
长度1到64位之间，区分大小
写字母，可包含字母、数字、
中划线、下划线或句点，不能
包含其他特殊字符。
请求消息
● 参数说明
无。
响应消息
● 正常响应要素说明
表 4-99 参数说明
参数 参数类型 描述
exist Boolean 校验结果。true为已存在，false为不存在。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 83
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息示例
● 正常响应要素说明
{
"exist" : false
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.12 应用参数模板
功能介绍
应用参数模板。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
PUT https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
apply
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/apply
● 参数说明
表 4-100 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 84
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
● 参数说明
表 4-101 参数说明
参数 是否必选 参数类型 描述
instance_ids 是 Array of 实例ID列表。
strings
请求示例
应用参数模板
{
"instance_ids" : [ "5362449138da4e408dbae5152ca26640in14",
"ea926816f0154066830d12ebebc8562din14" ]
}
响应消息
● 正常响应要素说明
表 4-102 参数说明
参数 参数类型 描述
job_id String 应用参数模板的异步任务ID。
响应消息示例
● 正常响应要素说明
{
"job_id" : "bf26cf3c-d046-4080-bb45-f114be7afa5f"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 85
云数据库 GaussDB
API 参考 4 API（推荐）
4.2.13 查询参数模板的应用记录
功能介绍
查询参数模板的应用记录。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
applied-histories
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/applied-histories
● 参数说明
表 4-103 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。例如：该参数指定为0，
limit指定为10，则只展示第
1-10条数据。
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。例如该参数设定为
10，则查询结果最多只显示10
条记录。
请求消息
无。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 86
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-104 参数说明
参数 参数类型 描述
histories Array of 应用记录列表，具体参数请参考表4-105。
objects
total_count Integer 总记录数。
表 4-105 histories 字段数据结构说明
参数 参数类型 描述
instance_id String 实例ID。
instance_na String 实例名称。
me
apply_result String 应用状态 (SUCCESS | FAILED | APPLYING)。
applied_at String 应用时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。 其中，T指某个时间的开
始；Z指时区偏移量，例如北京时间偏移显示
为+0800。
error_code String 失败原因错误码，如DBS.280005。
● 正常响应样例
{
"total_count": 2,
"histories": [
{
"instance_id": "1995a67680474481b3e42ac1474e32e0in14",
"instance_name": "gauss-a283",
"apply_result" : "SUCCESS",
"applied_at" : "2022-08-09T03:06:52+0800",
"error_code" : null
},
{
"instance_id": "8303819fd8744ef69f34595e9710a33din14",
"instance_name": "gauss-2423-lt-master",
"apply_result" : "FAILED",
"applied_at" : "2022-08-09T03:06:52+0800",
"error_code" : "DBS.280005"
}
]
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 87
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.2.14 查询参数模板的修改历史
功能介绍
查询参数模板的修改历史记录。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/configurations/{config_id}/
histories
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/619d3e78f61b4be68bc5aa0b59edcf7b/configurations/
3ca44134a16d4bbab8eb701e025b19f7pr14/histories
● 参数说明
表 4-106 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
config_id 是 String 参数模板ID。
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。例如：该参数指定为0，
limit指定为10，则只展示第
1-10条数据。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 88
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。例如该参数设定为
10，则查询结果最多只显示10
条记录。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-107 参数说明
参数 参数类型 描述
histories Array of 参数模板信息，具体参数请参考表4-108。
objects
total_count Integer 总记录数。
表 4-108 histories 字段数据结构说明
参数 参数类型 描述
parameter_n String 参数名称。
ame
old_value String 修改前参数值。
new_value String 修改后参数值。
update_resul String 修改状态 (SUCCESS | FAILED)。
t
updated_at String 修改时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量，
例如北京时间偏移显示为+0800。
● 正常响应样例
{
"histories" : [ {
"parameter_name" : "audit_system_object",
"old_value" : "12295",
"new_value" : "12298",
"update_result" : "SUCCESS",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 89
云数据库 GaussDB
API 参考 4 API（推荐）
"updated_at" : "2022-08-09T03:06:52+0800"
} ],
"total_count" : 1
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3 备份管理
4.3.1 查询备份列表
功能介绍
获取备份列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
该接口仅支持查询GaussDB的手动全量备份及自动全量备份(包括XBSA手动全量备份
类型、手动增量备份类型)。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/backups?
instance_id={instance_id}&backup_id={backup_id}&backup_type={backup_typ
e}&offset={offset}&limit={limit}&begin_time={begin_time}&end_time={end_ti
me}
● URI样例
– 查询所有备份列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/054ea741f700d4a32f1bc00f5c80dd4c/backups
– 根据指定条件查询实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/backups?
instance_id=88be33e4c5a64ceba42b42da89310111in14&backup_id=88be1234
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 90
云数据库 GaussDB
API 参考 4 API（推荐）
c5a64ceba42b42da89310111br14&backup_type=auto&begin_time=2022-05-0
9T16:15:50+0800&end_time=2022-05-09T16:20:45+0800&limit=1&offset=1
● 参数说明
表 4-109 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 否 String 实例ID，严格匹配UUID规
则。增备列表查询时实例IDid
必选。
backup_id 否 String 备份ID，严格匹配UUID规
则。
backup_type 否 String 备份类型，取值范围：
● auto：实例级自动全量备
份
● manual：实例级手动全量
备份
● Snapshot_Xbsa：xbsa手
动全量备份
● Log_Xbsa xbsa：增量备
份(该类型仅支持3.301及以
上版本实例)
● auto_database_table：
表级自动备份
● manual_database_table
：表级手动备份
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。
最小值：0
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。
最小值：1
最大值：100
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 91
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
begin_time 否 String 查询开始时间，格式为
“yyyy-mm-
ddThh:mm:ssZ”。其中，T指
某个时间的开始；Z指时区偏
移量。与end_time必须同时使
用。
end_time 否 String 查询结束时间，格式为
“yyyy-mm-
ddThh:mm:ssZ”，且大于查
询开始时间。其中，T指某个
时间的开始；Z指时区偏移
量。与begin_time必须同时使
用。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-110 参数说明
参数 参数类型 描述
backups Array of 备份信息。
objects 详情请参见表4-111。
total_count Long 备份文件的总数。
表 4-111 backups 字段数据结构说明
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
description String 备份文件描述信息。
begin_time String 备份开始时间，格式为"yyyy-mm-
ddThh:mm:ssZ"。 其中，T指某个时间的开
始；Z指时区偏移量。
end_time String 备份结束时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。 其中，T指某个时间的开
始；Z指时区偏移量。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 92
云数据库 GaussDB
API 参考 4 API（推荐）
参数 参数类型 描述
detail_messa String 备份详情信息，备份成功为 ‘success’或者
ge 为空；备份失败的时候会返回GaussDB生成失
败的错误信息。
status String 备份状态
枚举值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
size Double 备份大小(单位：MB)。
type String 备份类型
取值：
● auto：实例级自动全量备份。
● manual：实例级手动全量备份。
● auto_database_table：表级自动备份
● manual_database_table：表级手动备份
● Log_Xbsa：Xbsa增量备份
datastore Object 数据库信息。
详情请参见表4-112
instance_id String 实例ID。
表 4-112 datastore 字段数据结构说明
参数 参数类型 描述
type String 数据库引擎，不区分大小写，取值如下：
GaussDB。
version String 数据库版本。不填时，默认为当前最新版本。
● 正常响应样例
{
"backups": [
{
"id": "a696cd25e4fc453aa503650225cece8bbr14",
"name": "GaussDB-hly-ha-20220509080110906",
"description": null,
"status": "FAILED",
"size": 0.0,
"type": "auto",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 93
云数据库 GaussDB
API 参考 4 API（推荐）
"begin_time": "2022-05-09T16:01:10+0800",
"end_time": "2022-05-09T16:04:31+0800",
"detail_message": "success",
"instance_id": "164abc6d35114095bb849d007b19db3bin14"
},
{
"id": "5651c62a7f12461c98020dd3abfe24ccbr14",
"name": "GaussDB-hly-master-20220509022658257",
"description": null,
"status": "FAILED",
"size": 0.0,
"type": "auto",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"begin_time": "2022-05-09T10:26:58+0800",
"end_time": "2022-05-09T10:30:17+0800",
"instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
}
],
"total_count": 167
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.2 创建手动备份
功能介绍
创建手动备份。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/backups
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 94
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-113 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
请求消息
● 参数说明
表 4-114 参数说明
参数 是否必选 参数类型 描述
instance_id 是 String 实例ID。
name 是 String 备份名称，4~64个字符，必须
以英文字母开头，区分大小
写，可以包含英文字母、数
字、中划线或者下划线，不能
包含其他特殊字符。
最小长度：4
最大长度：64
description 否 String 备份描述，不能包含>!<"&'=
特殊字符，不大于256个字
符。
最大长度：256
backup_type 否 String 创建备份的类型，缺省值为
"completed" 。
取值：
● completed: 全备。
● differential: 差备，仅支持
xbsa实例。
● log: 增备，仅支持xbsa实
例(该类型仅支持3.301及以
上版本实例)。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 95
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
depend_back 否 Array of 增备时依赖的全备、差备的备
upIds String 份id列表，仅支持xbsa实例。
注意
由于PITR恢复时间由第三方维
护，因此字段由第三方自行计算
得出，计算为当前PITR最大可恢
复时间之前最近一次备份所对应
的BACKUPID的ENDTIME之后所
有备份对应的BACKUPID。
table_list 否 Array 表级备份信息。填写该参数会
创建表级备份，不填写则不会
创建实例级备份。详情参见表
4-115。
说明
● 仅支持3.200以上实例。
● 最多支持100个库或100个表
同时创建备份，超出建议使
用实例级备份。
表 4-115 table_list 字段数据结构说明
名称 是否必选 参数类型 说明
db_name 是 String 库名。
schema_name 是 String schema名。
table_name 是 String 表名。
请求示例
创建GaussDB手动全量备份。
{
"instance_id" : "7e01ac5ac5274957ba506f3851d11d51in14",
"name" : "backupwqwq3",
"description" : "manual backup",
"table_list": [
{
"db_name": "table_backup_db",
"schema_name": "myschema1",
"table_name": "test"
}
]
}
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 96
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-116 响应 Body 参数
参数 参数类型 描述
backup Object 备份信息。
详情请参见表4-117
job_id String 任务ID。
表 4-117 backup 字段数据结构说明
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
description String 备份描述。
begin_time String 备份开始时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量。
status String 备份状态，取值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
type String 备份类型，“manual”表示手动全量备份
instance_id String 实例ID。
● 正常响应样例
{
"backup": {
"id": "e76112bfb2074871bf54cb8df5af7f64br14",
"name": "backupwqwq32",
"description": "mannual backup",
"status": "BUILDING",
"type": "manual",
"begin_time": "2022-05-09T18:02:31+0800",
"instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
},
"job_id": "e4733090-b2c8-4ea7-a33a-f55f65723fb3"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 97
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.3 删除手动备份
功能介绍
删除手动备份。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/gaussdb/v3/{project_id}/backups/{backup_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups/
e28d08754b1a490fb2b3540ed013a7fbbr14
● 参数说明
表 4-118 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
backup_id 是 String 备份ID。
请求消息
无。
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 98
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.4 查询可恢复时间段
功能介绍
查询可恢复时间段。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
restore-time?date={date}
● URI样例
https://gaussdb-opengauss-api.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
d2113b7c60154636b94bea1320b6a874in14/restore-time?date=2022-04-17
● 参数说明
表 4-119 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
date 是 String 所需查询的日期，为yyyy-
mm-dd字符串格式，时区为
UTC。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 99
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
schema_type 否 String 备份类别取值, 默认值：
INSTANCE。
枚举值：
● INSTANCE：实例级备份。
● DATABASE_TABLE：表级
备份。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-120 参数说明
参数 参数类型 描述
restore_time Array of 可恢复时间段列表。
objects 详情请参见表4-121
表 4-121 restore_time 字段数据结构说明
参数 参数类型 描述
start_time Long 可恢复时间段的起始时间点，UNIX时间戳格
式，单位是毫秒，时区是UTC+8。
end_time Long 可恢复时间段的结束时间点，UNIX时间戳格
式，单位是毫秒，时区是UTC+8。
● 正常响应样例
{
"restore_time": [
{
"start_time": 1652084311000,
"end_time": 1652092839000
},
{
"start_time": 1652092847000,
"end_time": 1652094792000
}
]
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 100
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.5 恢复到新实例
功能介绍
根据备份恢复新实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 目标实例与源实例的数据库版本和实例类型必须一致。
● 目标实例规格必须大于等于源实例规格。
● 支持金融版（标准型）、1主3备、1主2备和BMS的金融版计算型形态的实例。
● 支持实例在资源类型BMS、ECS、MCS之间恢复到新实例，当前仅支持恢复到相
同的部署形态。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances
● 参数说明
表 4-122 参数说明
参数 是否必选 描述
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 101
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
表 4-123 参数说明
参数 是否必选 参数类型 描述
name 是 String 实例名称。
用于表示实例的名称，同一租户
下，同类型的实例名可重名。
取值范围：4~64个字符之间，
必须以字母开头，区分大小写，
可以包含字母、数字、中划线或
者下划线，不能包含其他的特殊
字符。
availability_zo 是 String 可用区ID。
ne GaussDB取值范围：非空，可选
部署在同一可用区或三个不同可
用区，可用区之间用逗号隔开。
详见示例。
● 部署在同一可用区：需要输
入三个相同的可用区。
● 部署在三个不同可用区：需
要分别输入三个不同的可用
区。
取值范围：非空，请向企业管理
员获取。
flavor_ref 是 String 规格码，取值范围：非空。参考
数据库实例规格中GaussDB的
“规格编码”列内容获取。
volume 是 Object volume信息。
详情请参见表4-124
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务
的控制台界面，在虚拟私有
云的详情页面查找VPC ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
VPC列表”的内容。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 102
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
subnet_id 是 String 子网的网络ID信息，获取方法如
下：
● 方法1：登录虚拟私有云服务
的控制台界面，单击VPC下
的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
子网列表”的内容。
security_grou 是 String 指定实例所属的安全组。
p_id ● 方法1：登录虚拟私有云服务
的控制台界面，在安全组的
详情页面查找安全组ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
安全组列表”的内容。
password 是 String 数据库密码。
GaussDB密码取值范围:
非空； 至少包含大写字母（A-
Z），小写字母（a-z），数字
（0-9），非字母数字字符（限
定为~!@#%^*-_=+?,）四类字符
中的三类字符；长度8~32个字
符。
建议您输入高强度密码，以提高
安全性，防止出现密码被暴力破
解等安全风险。
charge_info 否 Object 付费方式信息，支持按需。
详情请参见表4-125。
backup_strate 否 Object 自动备份策略。
gy 详情请参见表4-128。
restore_point 是 Object 恢复数据源对象。
详情请参见表4-126。
configuration_ 否 String 参数组ID。当不传该参数时，使
id 用系统默认的参数模板。
port 否 String GaussDB数据库端口当前只支持
设置为8000，当不传该参数
时，默认端口为8000。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 103
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
time_zone 否 String UTC时区。
● 不选择时，GaussDB默认为
UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且
只支持整段时间，如UTC
+08:00，不支持UTC
+08:30。
master_az 否 String 主可用区ID。取值为
availability_zone三个可用区ID
其一。当原实例存在单独的仲裁
可用区时必传，金融版（数据计
算型）和其他情况不需要填写。
arbitration_az 否 String 仲裁可用区ID。取值为
availability_zone三个可用区ID
其一。当原实例存在单独的仲裁
可用区时必传，其他情况不需要
填写。
xbsa_ssl_certs 否 Object xbsa SSL证书信息。
详情请参见表4-129。
kms_tde_key_i 否 String GaussDB使用透明加密的KMS主
d 密钥ID，填写ID启用透明加密功
能。需要填写为原实例KMS主密
钥ID。
kms_project_n 否 String kms_tde_key_id不为空时必传。
ame GaussDB使用透明加密的KMS主
密钥ID所在资源空间名称。
需要填写为原实例KMS主密钥ID
所在资源空间名称。
获取方法请参见获取项目ID/名
称。
表 4-124 volume 字段数据结构说明
参数 是否必选 参数类型 描述
type 是 String 磁盘类型。
仅支持LOCALSSD，
ULTRAHIGH。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 104
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
size 是 Integer 磁盘大小,需要大于等于原实
例。例如：该参数填写为
“40”，表示为恢复的实例分
配40GB的磁盘空间。
ECS部署方案取值范围：（分片
数*40GB）~（分片数*16TB），
且大小只能为分片数*40的整数
倍。
MCS部署方案：取值范围：（分
片数*40GB）~（分片数
*16TB），且大小只能为分片数
*40的整数倍。
BMS部署方案：该参数由所选择
的规格自动计算，不可指定，即
使填写，也不会生效。
表 4-125 charge_info 字段数据结构说明
参数 是否必选 参数类型 描述
charge_mode 是 String 计费模式。支持postPaid，后付
费，即按需付费。
表 4-126 restore_point 字段数据结构说明
参数 是否必选 参数类型 描述
instance_id 是 String 源实例ID。
backup_id 否 String 用于恢复的备份ID。
restore_time 否 String PITR用于恢复的时间戳，obs恢
复可通过 【查询可恢复时间
段】接口查询。详情请参见查询
可恢复时间段。xbsa恢复可通过
第三方文件解析查询。
type 是 String 表示恢复方式，缺省值为
backup，枚举值：
“backup”，表示使用备份文
件恢复，按照此方式恢复时，
“backup_id”必选。
“timestamp”，表示按时间
点恢复，按照此方式恢复时，
“restore_time”必选。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 105
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
table_list 否 Array 表级备份信息。仅恢复到库或恢
复到表需要填写。详情参见表
4-127。
说明
● 仅支持3.200以上实例。
● 最多支持100个库或100个表同
时恢复，超出建议使用实例级
恢复。
schema_type 否 String 源备份类别，默认值：
INSTANCE
枚举值：
● INSTANCE：实例级备份
● DATABASE_TABLE：表级备
份
表 4-127 table_list 字段数据结构说明
名称 是否必选 参数类型 说明
db_name 是 String 源备份库名
说明
不支持恢复模板库以及系统用
户。
模板库包括postgres、
template0 、template1。
系统用户包括rdsAdmin、
rdsMetric、rdsBackup、
rdsRepl。
schema_name 否 String 源备份schema
恢复到表时，该参数必传，
恢复到库时，该参数无效。
说明
不支持恢复系统级的如
dbe_application_info、rdsRepl
等schema。
table_name 否 String 源备份表名
恢复到表时，该参数必传，
恢复到库时，该参数无效。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 106
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
new_db_name 否 String 恢复到的新库名
不填时与源备份库名一致。
说明
● 数据库名称长度可在1～63
个字符之间，由字母、数
字、或下划线组成，不能包
含其他特殊字符，不能以
“pg”和数字开头，且不能
和模板库重名。 模板库包括
postgres、 template0 、
template1。也不能以系统
用户rdsAdmin、
rdsMetric、rdsBackup、
rdsRepl命名。
● 不使用保留或非保留关键字
命名数据库对象，具体请参
考《开发指南》中的"开发设
计建议 - 数据库对象命名"
章节。
new_schema_nam 否 String 恢复到的新schema
e 恢复到库时，该参数无效，
恢复到表不填时与源备份
schema一致。
说明
● schema名称在1到63个字符
之间，由字母、数字、或下
划线组成，不能包含其他特
殊字符，不能以“pg”和数
字开头，且不能和模板库、
已存在的schema重名，模板
库包括postgres、
template0 、template1，
已存在的schema包括
public、
information_schema，另外
不支持恢复系统级的如
dbe_application_info、
rdsRepl等schema。
● 不使用保留或非保留关键字
命名数据库对象，具体请参
考《开发指南》中的"开发设
计建议 - 数据库对象命名"
章节。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 107
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
new_table_name 否 String 恢复到的新表名
恢复到库时，该参数无效，
恢复到表不填时与备份的表
名一致。
说明
● 表名在1到63个字符之间，
由字母、数字、或下划线组
成，不能包含其他特殊字
符，不能以“pg”和数字开
头，具体请参考《开发指
南》中的"开发设计建议 -
数据库对象命名"章节。
表 4-128 backup_strategy 字段数据结构说明
参数 是否必选 参数类型 描述
start_time 是 String 备份时间段。自动备份将在该时
间段内触发。
取值范围：非空，格式必须为
hh:mm-HH:MM且有效，当前
时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且
取值必须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days 否 Integer 指定备份文件的可保存天数。
取值范围：0～732，开放
“gaussdb_feature_supportCo
nsoleBackupPolicyDay_36500
”白名单后，支持备份文件最长
保留天数36500天。该参数缺省
或为0时，默认填写为30天。
表 4-129 xbsa_ssl_certs 字段数据结构说明
参数 是否必选 参数类型 描述
ca_cert_pem 是 String 根证书文件内容。base64编
码。
client_crt 是 String 用户证书内容。base64编码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 108
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
client_key 是 String 用户私钥内容。base64编码。
rand_pass 是 String 私钥文件的密码。
● 请求示例
恢复实例：
{
"name": "targetInst",
"availability_zone": "aaa,bbb,ccc",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.x868.co",
"volume": {
"type": "LOCALSSD",
"size": 160
},
"vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
"subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
"security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
"password": "******",
"restore_point": {
"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin14",
"backup_id": "2f4ddb93b9014b0893d81d2e472f30febr14",
"table_list": [
{
"db_name": "table_backup_db",
"schema_name": "myschema1",
"table_name": "test"
}
],
"schema_type": "DATABASE_TABLE"
},
"configuration_id": "52e86e87445847a79bf807ceda213165pr01",
"port": 8000,
"time_zone": "UTC+04:00",
"master_az": "aaa",
"arbitration_az": "bbb"
}
响应消息
● 正常响应要素说明
表 4-130 要素说明
参数 参数类型 描述
instance Object 实例信息。
详情请参见表4-131。
job_id String 恢复新实例的任务id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 109
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-131 instance 说明
参数 参数类型 描述
id String 实例id。
name String 实例名称。 用于表示实例的名称，同一租户
下，同类型的实例名可重名。
取值范围：4~64个字符之间，必须以字母开
头，区分大小写，可以包含字母、数字、中划
线或者下划线，不能包含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
datastore Object 数据库信息。
详情请参见表4-132
ha Object 实例部署形态。
详情请参见表4-133
port String 数据库端口信息。 当不传该参数时，默认端口
8000。
volume Object volume信息。
详情请参见表4-134
backup_strat Object 自动备份策略。
egy 详情请参见表4-135
replica_num Integer 实例副本数。
region String 区域ID。
flavor_ref String 规格码。
availability_z String 可用区ID。可选部署在同一可用区或三个不同
one 可用区，可用区之间用逗号隔开。
取值范围：非空，请向企业管理员获取。
vpc_id String 虚拟私有云ID。
subnet_id String 子网ID。
security_grou String 安全组ID。
p_id
charge_info Object 付费方式信息，支持按需。
详情请参见表4-136。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 110
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-132 datastore 字段数据结构说明
参数 参数类型 描述
type String 数据库引擎，返回值如下： GaussDB
枚举值：
● GaussDB
version String 数据库版本。
表 4-133 ha 字段数据结构说明
参数 参数类型 描述
mode String GaussDB 分布式模式，返回值为：enterprise
（企业版）；主备版，返回值为：
centralization_standard(主备版)。
replication_ String 备机同步参数。
mode 取值：
GaussDB为“sync”。
说明
“sync”为同步模式。
枚举值：
● sync
consistency String GaussDB的预留参数：指定实例一致性类型，
取值范围：strong（强一致性） | eventual(最
终一致性)。
枚举值：
● strong
● eventual
表 4-134 volume 字段数据结构说明
参数 参数类型 描述
type String 磁盘类型。
取值如下，区分大小写：
● ULTRAHIGH，表示SSD。
● LOCALSSD
枚举值：
● ULTRAHIGH
● LOCALSSD
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 111
云数据库 GaussDB
API 参考 4 API（推荐）
参数 参数类型 描述
size Integer 磁盘大小。
GaussDB分布式实例恢复时需指定大小：要求
必须为（分片数 * 40GB）的倍数，取值范围：
（分片数40GB）~（分片数16TB）。
表 4-135 backup_strategy 字段数据结构说明
参数 参数类型 描述
start_time String 备份时间段。自动备份将在该时间段
内触发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时
间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值
必须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days Integer 指定备份文件的可保存天数。
取值范围：0～732，开放
“gaussdb_feature_supportConsoleB
ackupPolicyDay_36500”白名单后，
支持备份文件最长保留天数36500天。
该参数缺省时，默认填写为30天。
表 4-136 charge_info 字段数据结构说明
参数 参数类型 描述
charge_mode String 计费模式。支持postPaid，后付费，即按需付
费。
● 正常响应样例
{
"instance": {
"id": "2gfdsh844a4023a776fc5c5fb71fb4in14",
"name": "gaussdb-instance-rep2",
"status": "BUILD",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"ha": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 112
云数据库 GaussDB
API 参考 4 API（推荐）
"mode": "enterprise",
"consistency": "strong",
"replication_mode": "sync"
},
"volume": {
"type": "LOCALSSD",
"size": 160
},
"port": "8000",
"replica_num": 3,
"region": "regionA",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.x868.co",
"availability_zone": "aaa,bbb,ccc",
"vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
"subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
"security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
"charge_info": {
"charge_mode": "postPaid"
},
},
"job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.6 恢复到当前实例
功能介绍
将数据库恢复到当前实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{endpoint}/gaussdb/v3/{project_id}/instances/recovery
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/recovery
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 113
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-137 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
请求消息
● 参数说明
表 4-138 参数说明
参数 是否必选 参数类型 描述
source 是 Objects 恢复数据源对象。详情见表
4-139
target 是 Objects 恢复目标对象。详情见表
4-140
表 4-139 source 字段数据结构说明
参数 是否必选 参数类型 描述
instance_id 是 String 实例ID。
type 是 String 表示恢复方式，缺省值为
backup，枚举值：
“backup”，表示使用备份
文件恢复，按照此方式恢复
时，“backup_id”必选。
“timestamp”，表示按时间
点恢复，按照此方式恢复时，
“restore_time”必选。
backup_id 否 String 用于恢复的备份ID。当使用备
份文件恢复时需要指定该参
数。
xbsa可支持差量备份ID 恢复
restore_time 否 String Pitr用于恢复的时间戳，obs恢
复可通过 【查询可恢复时间
段】接口查询。详情请参见查
询可恢复时间段。xbsa恢复可
通过第三方文件解析查询。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 114
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
table_list 否 Array 表级备份信息。仅恢复到库或
恢复到表需要填写。详情参见
表4-141
说明
● 仅支持3.200以上实例。
● 最多支持100个库或100个表
同时恢复，超出建议使用实
例级恢复。
schema_type 否 String 源备份类别，默认值：
INSTANCE
枚举值：
● INSTANCE：实例级备份
● DATABASE_TABLE：表级
备份
表 4-140 target 字段数据结构说明
参数 是否必选 参数类型 描述
instance_id 是 String 恢复目标实例ID。
表 4-141 table_list 字段数据结构说明
名称 是否必选 参数类型 说明
db_name 是 String 源备份库名
说明
不支持恢复模板库以及系统用
户。
模板库包括postgres、
template0 、template1。
系统用户包括rdsAdmin、
rdsMetric、rdsBackup、
rdsRepl。
schema_name 否 String 源备份schema
恢复到表时，该参数必传，
恢复到库时，该参数无效。
说明
不支持恢复系统级的如
dbe_application_info、
rdsRepl等schema。
table_name 否 String 源备份表名
恢复到表时，该参数必传，
恢复到库时，该参数无效。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 115
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
new_db_name 否 String 恢复到的新库名
不填时与源备份库名一致。
说明
● 不能与当前实例已有库同
名。
● 数据库名称长度可在1～
63个字符之间，由字母、
数字、或下划线组成，不
能包含其他特殊字符，不
能以“pg”和数字开头，
且不能和模板库重名。 模
板库包括postgres、
template0 、
template1。也不能以系
统用户rdsAdmin、
rdsMetric、rdsBackup、
rdsRepl命名。
● 不使用保留或非保留关键
字命名数据库对象，具体
请参考《开发指南》中的"
开发设计建议 - 数据库对
象命名"章节。
new_schema_na 否 String 恢复到的新schema
me 恢复到库时，该参数无效，
恢复到表不填时与源备份
schema一致。
说明
● 不能与当前实例已有
schema同名。
● schema名称在1到63个字
符之间，由字母、数字、
或下划线组成，不能包含
其他特殊字符，不能以
“pg”和数字开头，且不
能和模板库、已存在的
schema重名，模板库包括
postgres、 template0 、
template1，已存在的
schema包括public、
information_schema，另
外不支持恢复系统级的如
dbe_application_info、
rdsRepl等schema。
● 不使用保留或非保留关键
字命名数据库对象，具体
请参考《开发指南》中的"
开发设计建议 - 数据库对
象命名"章节。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 116
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
new_table_name 否 String 恢复到的新表名
恢复到库时，该参数无效，
恢复到表不填时与备份的表
名一致。
说明
● 不能与当前实例已有表同
名。
● 表名在1到63个字符之
间，由字母、数字、或下
划线组成，不能包含其他
特殊字符，不能以“pg”
和数字开头，具体请参考
《开发指南》中的"开发设
计建议 - 数据库对象命名"
章节。
● 请求样例
恢复到当前实例
{
"source" : {
"instance_id" : "5362449138da4e408dbae5152ca26640in14",
"type" : "backup",
"backup_id" : "cc94568cb5a54e4a8ab5dff95e64a5e0br14" ,
"table_list": [
{
"db_name": "table_backup_db",
"schema_name": "myschema",
"table_name": "test"
}
],
"schema_type": "DATABASE_TABLE"
},
"target" : {
"instance_id" : "5362449138da4e408dbae5152ca26640in14"
}
}
响应消息
● 正常响应要素说明
表 4-142 响应 Body 参数
参数 参数类型 描述
job_id String 任务ID。
● 正常响应样例
{
"job_id" : "a03b1b8a-b756-467c-8a49-38720c3d23ec"
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 117
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.7 备份恢复后执行数据确认
功能介绍
确认备份恢复后的数据是否正常，仅需要在恢复到当前实例后调用。数据确认后会删
除本次恢复时间点后的归档日志，并重新开启日志归档。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
confirm-restore-data
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/confirm-restore-data
● 参数说明
表 4-143 参数说明
名称 类型 是否必 描述
选
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id String 是 实例ID。
请求消息
无
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 118
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-144 响应 Body 参数
名称 类型 描述
job_id String 任务ID
● 正常响应样例
{
"job_id" : "a03b1b8a-b756-467c-8a49-38720c3d23ec"
}
– 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.8 查询差量备份列表
功能介绍
查询差量备份列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
differential-backups
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
2e642f2861004f659bc567858936160ein14/differential-backups
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 119
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-145 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
limit 否 String 查询记录数。默认为10，不能
为负数，最小值为1，最大值
为100。
最小值：1
最大值：100
offset 否 String 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。
最小值：0
begin_time 否 String 查询开始时间，默认为当前时
刻格式为“yyyy-mm-
ddThh:mm:ssZ”。其中，T指
某个时间的开始；Z指时区偏
移量，例如北京时间偏移显示
为+0800。
end_time 否 String 查询结束时间，默认为当前时
间格式为“yyyy-mm-
ddThh:mm:ssZ”，且大于查
询开始时间。其中，T指某个
时间的开始；Z指时区偏移
量，例如北京时间偏移显示为
+0800
请求消息
无。
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 120
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-146 响应 Body 参数
参数 参数类型 描述
differential_b String 差量备份列表，详情见表4-147。
ackups
total_count Integer 查询结果总数。
表 4-147 响应 differential_backups 参数
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
begin_time String 备份开始时间，格式为"yyyy-mm-
ddThh:mm:ssZ"。其中，T指某个时间的开
始；Z指时区偏移量，例如北京时间偏移显示
为+0800。
end_time String 备份结束时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。其中，T指某个时间的开
始；Z指时区偏移量，例如北京时间偏移显示
为+0800。
status String 备份状态
枚举值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
size Double 备份大小(单位：MB)。
● 正常响应样例
{
"differential_backups": [
{
"id": "2fc14f56ef074d9cbc3005626870acddbr14",
"name": "hc_test1230",
"status": "Active",
"size": 0.840538025390625,
"begin_time": "2023-03-06T22:28:06+0800",
"end_time": "2023-03-06T22:30:12+0800"
}
],
"total_count": 1
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 121
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.3.9 安装三方备份 SSL 证书
功能介绍
XBSA备份实例安装SSL证书。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
backups/ssl-certs
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
2e642f2861004f659bc567858936160ein14/backups/ssl-certs
● 参数说明
表 4-148 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 122
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-149 参数说明
参数 是否必选 参数类型 描述
ca_cert_pem 是 String 根证书文件内容，采用base64
编码格式。
client_crt 是 String 用户证书内容，采用base64编
码格式。
client_key 是 String 用户私钥内容，采用base64编
码格式。
rand_pass 是 String 客户端私钥密码字符串。
● 请求示例
安装SSL 证书
{
"ca_cert_pem" : "Q2VydGlmaWNhdGU6CiAgICBEYXRhOgogICAgIC***************************",
"client_crt" : "Q2VydGlmaWNhdGU6CiAgICBEYXRhOgogICAgIC***************************",
"client_key" : "Q2VydGlmaWNhdGU6CiAgICBEYXRhOgogICAgIC***************************",
"rand_pass" : "pass"
}
响应消息
● 正常响应要素说明
表 4-150 响应 Body 参数
参数 参数类型 描述
job_id String Job_id 任务ID。
● 正常响应样例
{
"job_id":"a03b1b8a-b756-467c-8a49-38720c3d23eo"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 123
云数据库 GaussDB
API 参考 4 API（推荐）
4.4 引擎版本和规格
4.4.1 查询引擎列表
功能介绍
查询引擎列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/datastores
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/datastores
● 参数说明
表 4-151 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
请求消息
● 请求示例
无。
响应消息
● 正常响应要素说明
表 4-152 要素说明
名称 参数类型 说明
datastores Array of objects 数据库引擎列表。
详情请参见表4-153。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 124
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-153 dataStores 字段数据结构说明
参数 参数类型 描述
supported_ve Array of 部署形态支持的引擎版本列表。
rsions strings
instance_mo String 部署形态。
de 枚举值：
● ha：主备版
● combined：分布式版 金融版（标准型）
● combined_hcs2：分布式版 企业版
● combined_hcs3：分布式版 金融版(标准
型)
● combined_hcs4：分布式版 金融版（数据
计算型，容灾主）
● combined_hcs5：分布式版 金融版（数据
计算型，容灾备）
● 正常响应样例
{
"datastores": [
{
"instance_mode": "ha",
"supported_versions": [
"2.0",
"2.3",
"2.6",
"2.9"
]
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5 管理数据库和用户
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 125
云数据库 GaussDB
API 参考 4 API（推荐）
4.5.1 创建数据库
功能介绍
在指定实例中创建数据库。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
该接口只支持单个数据库创建，实例在创建、变更规格、冻结、异常等状态下不能执
行该操作。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
database
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/{instance_id}/
database
● 参数说明
表 4-154 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-155 参数说明
名称 是否必选 参数类型 说明
name 是 String 数据库名称。
数据库名称长度可在1～63
个字符之间，由字母、数
字、或下划线组成，不能包
含其他特殊字符，不能以
“pg”和数字开头，且不
能和模板库重名。 模板库
包括postgres，
template0，template1。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 126
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
character_set 否 String 数据库字符集。默认
UTF8。
owner 否 String 数据库所属用户，缺省时默
认是root，不能和系统用户
重名，且必须是已存在的用
户。
系统用户包括
“rdsAdmin”,
“ rdsMetric”,
“rdsBackup”,
“rdsRepl”。
template 否 String 数据库模板名称，仅支持为
template0。
lc_collate 否 String 数据库排序集。默认C。
须知
不同的排序规则下，相同字符
串的比较其结果可能是不同
的。 例如，在en_US.utf8
下， select 'a'>'A';执行结果为
false，但在'C'下，select
'a'>'A';结果为true。如果数据
库从“O”迁移到GaussDB，
数据库排序集需使用'C'才能得
到一致的预期。支持的排序规
则可以查询系统表
pg_collation。
lc_ctype 否 String 数据库分类集。默认C。
请求示例
创建一个GaussDB数据库，库名为gaussdb_test。
{
"name" : "gaussdb_test",
"owner" : "test",
"template" : "template0",
"character_set" : "UTF8",
"lc_collate" : "en_US.UTF-8",
"lc_ctype" : "en_US.UTF-8"
}
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 127
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.2 创建数据库用户
功能介绍
在指定实例中创建数据库用户。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
● 实例在创建、变更规格、冻结、异常等状态下不能执行该操作。
● 该接口只支持创建单个用户接口。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-
user
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
{instance_id}/db-user
● 参数说明
表 4-156 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 128
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-157 参数说明
名称 是否必选 参数类型 说明
name 是 String 数据库用户名称。
数据库用户名称在1到63个
字符之间，由字母、数字、
或下划线组成，不能包含其
他特殊字符，不能以
“pg”和数字开头，不能
和系统用户名称相同。
系统用户包括
“rdsAdmin”,
“ rdsMetric”,
“rdsBackup”,
“rdsRepl”, “root”。
password 是 String 数据库用户密码。
取值范围：非空，密码长度
在8到32个字符之间，至少
包含大写字母、小写字母、
数字、特殊字符~!@#%^*-
_=+?,三种字符的组合，不
能和数据库帐号“name”
或“name”的逆序相同。
建议您输入高强度密码，以
提高安全性，防止出现密码
被暴力破解等安全风险。
请求示例
创建一个GaussDB数据库用户，用户名为dbs。
{
"name" : "dbs",
"password" : "******"
}
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 129
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.5.3 创建数据库 SCHEMA
功能介绍
在指定实例的数据库中, 创建数据库schema。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
实例在创建、变更规格、冻结、异常等状态下不能执行该操作。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
schema
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/{instance_id}/
schema
● 参数说明
表 4-158 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 130
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-159 参数说明
名称 是否必选 参数类型 说明
db_name 是 String 数据库名称。
数据库名称在1到63个字符
之间，由字母、数字、或下
划线组成，不能包含其他特
殊字符，不能以“pg”和
数字开头，且不能和模板库
重名。
模板库包括postgres，
template0 ，template1。
schemas 是 Array of 每个元素都是与数据库相关
objects 联的schema信息。单次请
求最多支持20个元素。详情
请参见表4-160
表 4-160 schemas 字段数据结构说明
名称 是否必选 参数类型 说明
name 是 String schema名称。
schema名称在1到63个字
符之间，由字母、数字、或
下划线组成，不能包含其他
特殊字符，不能以“pg”
和数字开头，且不能和模板
库和已存在的schema重
名。模板库包括postgres，
template0 ，template1。
已存在的schema包括
public，
information_schema。
owner 是 String 数据库属主用户。
数据库属主名称在1到63个
字符之间，不能以“pg”
和数字开头，不能和系统用
户名称相同。
系统用户包括
“rdsAdmin”,
“ rdsMetric”,
“rdsBackup”,
“rdsRepl”。
请求示例
在gaussdb_test数据库中创建多个SCHEMA。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 131
云数据库 GaussDB
API 参考 4 API（推荐）
{
"db_name" : "gaussdb_test",
"schemas" : [ {
"name" : "rds",
"owner" : "teste123"
}, {
"name" : "rds001",
"owner" : "teste123"
} ]
}
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.4 授权数据库帐号
功能介绍
在指定实例的数据库中, 设置帐号的权限。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
● 实例在创建、变更规格、冻结、异常等状态下不能执行该操作。
● 创建的只读用户对public模式默认具有create和usage权限。
● 同一schema不能同时授权。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-
privilege
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
{instance_id}/db-privilege
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 132
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-161 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-162 参数说明
名称 是否必选 参数类型 说明
db_name 是 String 数据库名称。
数据库名称在1到63个字符
之间，由字母、数字、或下
划线组成，不能包含其他特
殊字符，不能以“pg”和
数字开头，且不能和模板库
重名。
模板库包括postgres，
template0 ，template1。
users 是 Array of 每个元素都是与数据库相关
objects 联的帐号。单次请求最多支
持50个元素。详情请参见表
4-163。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 133
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-163 users 字段数据结构说明
名称 是否必选 参数类型 说明
name 是 String 数据库帐号名称。
数据库帐号名称在1到63个
字符之间，由字母、数字、
或下划线组成，不能包含其
他特殊字符，不能以
“pg”和数字开头，不能
和系统用户名称相同且帐号
名称必须存在。
系统用户包括
“rdsAdmin”,
“rdsMetric”,
“rdsBackup”,
“rdsRepl”, “root”。
readonly 是 Boolean 数据库帐号权限。
● true：只读。
● false：可读可写。
schema_name 是 String schema名称。
schema名称在1到63个字
符之间，由字母、数字、或
下划线组成，不能包含其他
特殊字符，不能以“pg”
和数字开头，不能和模板库
重名，且schema名称必须
存在。
模板库包括postgres，
template0 ，template1,
public，
information_schema。
请求示例
设置gaussdb_test数据库多个帐号的权限。
{
"db_name" : "gaussdb_test",
"users" : [ {
"name" : "rds",
"readonly" : false,
"schema_name" : "teste123"
}, {
"name" : "rds001",
"readonly" : true,
"schema_name" : "teste134"
}, {
"name" : "rds002",
"readonly" : false,
"schema_name" : "teste135"
} ]
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 134
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.5 重置数据库帐号密码
功能介绍
重置指定数据库帐号的密码。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
● 实例在创建、变更规格、冻结、异常等状态下不能执行该操作。
● 该接口只支持重置单个用户。
URI
● URI格式
PUT https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-
user/password
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
{instance_id}/db-user/password
● 参数说明
表 4-164 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 135
云数据库 GaussDB
API 参考 4 API（推荐）
请求消息
● 参数说明
表 4-165 参数说明
名称 是否必选 参数类型 说明
name 是 String 数据库帐号名称，不能为系
统帐号用户。系统用户包括
“rdsAdmin”,
“rdsMetric”,
“rdsBackup”,
“rdsRepl”。
password 是 String 数据库帐号密码。
取值范围：
非空，至少包含以下字符中
的三种：大写字母、小写字
母、数字和特殊符号~!@#
%^*-_=+?,组成，长度8~32
个字符，不能和数据库帐号
“name”或“name”的
逆序相同。
建议您输入高强度密码，以
提高安全性，防止出现密码
被暴力破解等安全风险。
请求示例
重置数据库root帐号的密码。
{
"name" : "root",
"password" : "*******"
}
响应消息
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 136
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.5.6 查询数据库列表
功能介绍
查询指定实例中的数据库列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
databases
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/instances/{instance_id}/
databases
● 参数说明
表 4-166 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
offset 否 Integer 分页符。从第一条数据偏移
offset页数据后开始查询，默
认为0（偏移0页数据，表示从
第一条数据开始查询），必须
为数字，不能为负数。例如：
该参数指定为1，limit指定为
10，则只展示第11-20条数
据。
limit 否 Integer 每页显示的条目数量,取值范围
[1, 100]，默认10。
请求消息
无。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 137
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
● 正常响应要素说明
表 4-167 参数说明
参数 参数类型 描述
databases Array of 列表中每个元素表示一个数据库。详情参见表
objects 4-168。
total_count Integer 总记录数。
表 4-168 databases 字段数据结构说明
参数 参数类型 描述
name String 数据库名称。
owner String 数据库所属用户。
character_set String 数据库使用的字符集，例如UTF8。
collate_set String 数据库排序集，例如en_US.UTF-8等。
size String 数据库大小。
● 正常响应样例
{
"databases" : [ {
"name" : "rds-test",
"character_set" : "utf8",
"owner" : "root",
"collate_set" : "en_US.UTF-8",
"size" : 10777247
}, {
"name" : "testdb1",
"character_set" : "utf8",
"owner" : "root",
"collate_set" : "en_US.UTF-8",
"size" : 10777247
}, {
"name" : "tt",
"character_set" : "utf8",
"owner" : "root",
"collate_set" : "en_US.UTF-8",
"size" : 10777247
} ],
"total_count" : 3
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 138
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.7 查询数据库用户列表
功能介绍
指定实例中查询数据库用户列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/db-
users
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/instances/{instance_id}/db-
users
● 参数说明
表 4-169 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
offset 否 Integer 分页符。从第一条数据偏移
offset页数据后开始查询，默
认为0（偏移0页数据，表示从
第一条数据开始查询），必须
为数字，不能为负数。例如：
该参数指定为1，limit指定为
10，则只展示第11-20条数
据。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 139
云数据库 GaussDB
API 参考 4 API（推荐）
参数 是否必选 参数类型 描述
limit 否 Integer 每页显示的条目数量,取值范围
[1, 100]，默认10。
请求消息
无。
响应消息
● 正常响应要素说明
表 4-170 参数说明
参数 参数类型 描述
users Array of 列表中每个元素表示一个数据库用户，详情参
objects 见表4-171。
total_count Integer 数据库用户总数。
表 4-171 users 字段数据结构说明
参数 参数类型 描述
name String 数据库名称。
attribute Object 用户的权限属性，详情参见表4-172。
memberof String 用户的默认权限。
表 4-172 attributes 字段数据结构说明
参数 参数类型 描述
rolsuper Boolean 用户是否具有管理员权限，取值为“true”或
“false”。
rolinherit Boolean 用户是否自动继承其所属角色的权限，取值为
“true”或“false”。
rolcreaterole Boolean 用户是否支持创建其他子用户，取值为
“true”或“false”。
rolcreatedb Boolean 用户是否可以创建数据库，取值为“true”或
“false”。
rolcanlogin Boolean 用户是否可以登录数据库，取值为“true”或
“false”。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 140
云数据库 GaussDB
API 参考 4 API（推荐）
参数 参数类型 描述
rolconnlimit Integer 用户连接实例的最大并发连接数。-1表示没有
限制。
rolreplication Boolean 用户是否属于复制角色，取值为“true”或
“false”。
rolbypassrls Boolean 用户是否绕过每个行级安全策略，取值为
“true”或“false”。
● 正常响应样例
{
"users": [
{
"name": "root",
"attribute": {
"rolsuper": false,
"rolinherit": true,
"rolcreaterole": true,
"rolcreatedb": true,
"rolcanlogin": true,
"rolconnlimit": -1,
"rolreplication": false,
"rolbypassrls": false
},
"memberof":
"{gs_role_copy_files,gs_role_signal_backend,gs_role_tablespace,gs_role_replication,gs_role_a
ccount_lock}"
}
],
"total_count": 1
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.5.8 查询数据库 SCHEMA 列表
功能介绍
查询指定实例的数据库SCHEMA列表。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 141
云数据库 GaussDB
API 参考 4 API（推荐）
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
实例在异常或冻结状态下不能执行该操作。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/
schemas?db_name={db_name}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/054ea741f700d4a32f1bc00f5c80dd4c/instances/{instance_id}/
schemas?db_name=dbname
● 参数说明
表 4-173 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。
db_name 是 String 数据库名称。不能和模板库重
名。模板库包括postgres，
template0 ，template1。
offset 否 Integer 分页符。从第一条数据偏移
offset页数据后开始查询，默
认为0（偏移0页数据，表示从
第一条数据开始查询），必须
为数字，不能为负数。例如：
该参数指定为1，limit指定为
10，则只展示第11-20条数
据。
limit 否 Integer 每页显示的条目数量,取值范围
[1, 100]，默认10。
请求消息
无。
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 142
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-174 参数说明
参数 参数类型 描述
database_sch Array of 列表中每个元素表示一个数据库schema，详
emas objects 情参见表4-175。
total_count Integer 数据库schema总数。
表 4-175 database_schemas 字段数据结构说明
参数 参数类型 描述
schema_nam String schema名称。
e
owner String schema所属用户。
● 正常响应样例
{
"database_schemas" : [ {
"schema_name" : "rds-test",
"owner" : "root"
}, {
"schema_name" : "testdb1",
"owner" : "root"
} ],
"total_count" : 2
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.6 容灾管理
仅在特性白名单gaussdb_feature_supportDisasterApiGlobal处于开启状态下，容灾管
理API可用。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 143
云数据库 GaussDB
API 参考 4 API（推荐）
4.6.1 查询容灾集群监控状态
功能介绍
查询实例搭建容灾后实时容灾状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/monitor?disaster_type={disaster_type}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
a7d62bf77aa04fceb52fbd57181c9e3ein14/disaster-recovery/monitor?
disaster_type={disaster_type}
● 参数说明
表 4-176 参数说明
名称 是否必选 参 说明
数
类
型
project_id 是 Stri 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
instance_id 是 Stri 实例ID。
ng
disaster_type 是 Stri 容灾类型：
ng ● stream
● dorado
请求消息
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3.5/4a52a8a8f63d4c6d966dff0e20b69738/
instances/4d653d1caf0e4a49b4753713fac679e3in14/disaster-recovery/monitor?
disaster_type=stream
响应消息
表 4-177 响应 Body 参数列表
名称 参数类型 说明
instance_id String 实例id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 144
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
status String 容灾状态。
rpo String 数据恢复点目标。
rto String 数据恢复时间目标。
rpo_threshold String rpo阈值。
rto_threshold String rto阈值。
switchover_pro String 主从切换进度。该值为一个百分数。例
gress 如：40%
failover_progr String 容灾升主进度。该值为一个百分数。例
ess 如：40%
● 正常响应样例
{
"rpo":"0",
"rto":"0",
"status":"archive",
"instance_id":"b3692282395340c5b5421ecf3d7bd6adin14",
"rto_threshold":"900",
"rpo_threshold":"10",
"failover_progress":"",
"switchover_ progress ":""
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.2 查询容灾关系列表
功能介绍
查询容灾关系列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 145
云数据库 GaussDB
API 参考 4 API（推荐）
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.5/{project_id}/disaster-recovery/relations
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/disaster-recovery/relations
● 参数说明
表 4-178 参数说明
名称 参 是否必选 说明
数
类
型
project_id Stri 是 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
instance_nam Stri 否 实例名称，可查询过滤本端实例。
e ng
instance_id Stri 否 实例id，可查询过滤本端实例id。
ng
limit Int 否 查询记录数。为空时，默认为100。最
ege 小值为1，最大值为100。
r
offset Int 否 索引位置，偏移量。从第一条数据偏移
ege offset条数据后开始查询，默认为0（偏
r 移0条数据，表示从第一条数据开始查
询），必须为数字，不能为负数。
请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/4a52a8a8f63d4c6d966dff0e20b69738/disaster-recovery/relations?
limit=&offset=0&instance_name=test
请求消息
无
响应消息
表 4-179 响应 Body 参数列表
名称 参数类型 说明
total Integer 总记录数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 146
云数据库 GaussDB
API 参考 4 API（推荐）
名称 参数类型 说明
relations Array of Object 容灾关系详情。
表 4-180 relations 字段数据结构说明
名称 参数类型 说明
disaster_type String 容灾类型。
枚举值:
● stream
name String 容灾任务名称。
disaster_role String 容灾角色。
枚举值:
● disaster
● master
created String 创建时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移
量，例如北京时间偏移显示为+0800。
updated String 更新时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移
量，例如北京时间偏移显示为+0800。
slave_region_in Object 备region实例信息。
stance_info
master_region_i Object 主region实例信息。
nstance_info
synchronization String 容灾关系唯一id。
_id
id String 容灾记录id。
instance_id String 当前region实例id。
instance_name String 当前region实例名称。
instance_status String 当前region实例状态。
precheck_failed String 预校验失败原因。
_reason
status String 容灾记录状态。
actions Array of String 实例当前正在执行的action列表。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 147
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-181 region_instance_info 字段数据结构说明
名称 参数类型 说明
instance_id String 实例id。
project_id String 实例项目id。
project_name String 实例项目名称。
region_code String regionCode编码。
ip_address String 数据ip地址列表“,”分割。
● 正常响应样例
{
"total" : 1,
"relations" : [ {
"name" : "DR-task-0962",
"created" : "2022-06-16 09:39:51",
"updated" : "2022-06-16 09:44:55",
"id" : "30b74120-4b50-495d-8174-7eeddf7feac5",
"synchronization_id" : "9446f822-ccd2-43dc-929c-0b78ba7fdf64",
"status" : "normal",
"precheck_failed_reason" : "",
"disaster_type" : "stream",
"disaster_role" : "disaster",
"slave_region_instance_info" : {
"region_code" : "sa-fb-1",
"instance_id" : "d1060faf0d3743dd8830b39e7423bc9ain14",
"project_id" : "4a52a8a8f63d4c6d966dff0e20b69738",
"project_name" : "sa-fb-1_GaussDB",
"ip_address" : "172.166.1.192,172.166.0.6,172.166.1.135"
},
"master_region_instance_info" : {
"region_code" : "sa-fb-1",
"instance_id" : "54d4b9fb131745fcba32cb90a05cabb8in14",
"project_id" : "4a52a8a8f63d4c6d966dff0e20b69738",
"project_name" : "sa-fb-1_GaussDB",
"ip_address" : "172.167.1.86,172.167.0.89,172.167.1.229"
},
"instance_id" : "d1060faf0d3743dd8830b39e7423bc9ain14",
"instance_name" : "hly-0609-02",
"instance_status" : "normal",
"actions" : [ "STREAM_DISASTER_RELATION_MASTER_TAG" ]
} ]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 148
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.6.3 搭建容灾关系
功能介绍
搭建容灾关系。
两地三中心添加流灾备实例也将调用此接口。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
从主实例端下发。
支持数据库版本大于等于3.209。
两地三中心场景下仅支持数据库版本大于等于3.209。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/construct
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
9089bbf7377442daa55bc28d514c08bdin14/disaster-recovery/construct
● 参数说明
表 4-182 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 149
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-183 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream：代表流式容灾
● dorado：代表Dorado
容灾
dr_ip 是 String 对端实例任意数据ip。
dr_user_name 是 String 对端实例账户名称。
dr_user_passwor 是 String 对端实例账户密码。
d
– 请求示例
{
"disaster_type" : "stream",
"dr_ip" : "127.0.0.1",
"dr_user_name" : "root",
"dr_user_password" : "password"
}
响应消息
表 4-184 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 150
云数据库 GaussDB
API 参考 4 API（推荐）
错误码
请参见错误码。
4.6.4 备实例容灾升主
功能介绍
容灾升主（failover），灾备实例端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
在灾备region下发。
支持数据库版本大于等于3.209。
两地三中心场景下仅支持数据库版本大于等于3.209。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/failover
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
c04c789b6baa4b6dbcc139c5226f3a2cin14/disaster-recovery/failover
● 参数说明
表 4-185 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
表 4-186 参数说明
名称 是否必选 参数类型 说明
is_support_restore 否 Boolean 是否支持容灾回切(仅支持数
据库版本大于等于3.200)
● true支持
● false不支持(默认false)
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 151
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
● dorado
● 正常响应样例
{
"is_support_restore": true,
"disaster_type": "stream"
}
响应消息
表 4-187 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.5 解除容灾关系
功能介绍
解除容灾关系，从容灾主实例端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 152
云数据库 GaussDB
API 参考 4 API（推荐）
约束限制
● 仅支持从主Region下发解除容灾关系操作。
● 两地三中心场景下，主实例A和同城备实例B和异地备实例C搭建容灾关系，不能
在异地集群C为主的情况下，下发解除容灾操作，需要在异地集群C降备后才能解
除。
● 主实例A和备实例B搭建容灾关系，在备实例B进行容灾演练场景时，禁止在主实
例A下发容灾解除操作。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/release
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
c04c789b6baa4b6dbcc139c5226f3a2cin14/disaster-recovery/release
● 参数说明
表 4-188 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-189 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
● dorado
– 请求示例
{
"disaster_type" : "stream"
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 153
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
表 4-190 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.6 灾备实例主从切换
功能介绍
灾备实例主从切换（switchover），可在主备任意一端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
支持数据库版本大于等于3.209。
两地三中心场景下仅支持数据库版本大于等于3.209。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/switchover
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/instances/c04c789b6baa4b6dbcc139c5226f3a2cin14/
disaster-recovery/switchover
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 154
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-191 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-192 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
● dorado
– 请求示例
{
"disaster_type" : "stream"
}
响应消息
表 4-193 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 155
云数据库 GaussDB
API 参考 4 API（推荐）
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.7 重建容灾关系
功能介绍
流容灾备升主选择支持容灾回切，实现容灾关系的重建任务。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
支持数据库版本大于等于3.209。
两地三中心场景下仅支持数据库版本大于等于3.209。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/restore
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/restore
● 参数说明
表 4-194 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 156
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-195 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
● dorado
– 请求示例
{
"disaster_type" : "stream"
}
响应消息
表 4-196 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.8 开启容灾演练
功能介绍
灾备实例开始容灾演练。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 157
云数据库 GaussDB
API 参考 4 API（推荐）
演练开启后，主实例会对增量数据进行暂存，此处可以指定保留增量数据大小的上限
值，演练结束后，备实例可以根据暂存的增量数据进行增量回放。如果增量数据超过
此处设定值，演练结束后备实例会进行全量数据回放。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
仅支持数据库版本大于等于3.209的实例。
两地三中心场景下不支持此接口。
URI
● URI格式
POST
https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/disaster-
recovery/simulation-start
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/simulation-start
● 参数说明
表 4-197 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-198 参数说明
名称 是否必选 参数类型 说明
xlog_keep_ratio 否 Integer 灾备实例该字段不生效，主
实例默认10：
● 日志保留空间占可使用
剩余磁盘容量的比例, 可
设置范围为1-99。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 158
云数据库 GaussDB
API 参考 4 API（推荐）
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
– 请求示例
{
"xlog_keep_ratio":50,
"disaster_type" : "stream"
}
响应消息
表 4-199 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.9 结束容灾演练
功能介绍
灾备实例结束容灾演练。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 159
云数据库 GaussDB
API 参考 4 API（推荐）
约束限制
仅支持数据库版本大于等于3.209的实例。
两地三中心场景下不支持此接口。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/simulation-stop
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/simulation-stop
● 参数说明
表 4-200 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-201 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
– 请求示例
{
"disaster_type" : "stream"
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 160
云数据库 GaussDB
API 参考 4 API（推荐）
响应消息
表 4-202 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.10 开启日志保持
功能介绍
主实例开始容灾日志保持。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
仅支持数据库版本大于等于3.209的实例。
两地三中心场景下不支持此接口。
URI
● URI格式
POST
https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/disaster-
recovery/keep-log-start
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/keep-log-start
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 161
云数据库 GaussDB
API 参考 4 API（推荐）
● 参数说明
表 4-203 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 4-204 参数说明
名称 是否必选 参数类型 说明
xlog_keep_ratio 否 Integer 主实例默认10：
● 日志保留空间占可使用
剩余磁盘容量的比例, 可
设置范围为1-99。
disaster_type 是 String 容灾类型。
枚举值：
● stream
– 请求示例
{
"xlog_keep_ratio":50,
"disaster_type" : "stream"
}
响应消息
表 4-205 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 162
云数据库 GaussDB
API 参考 4 API（推荐）
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.11 结束日志保持
功能介绍
主实例结束容灾日志保持。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
仅支持数据库版本大于等于3.209的实例。
两地三中心场景下不支持此接口。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/
disaster-recovery/keep-log-stop
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-recovery/keep-log-stop
● 参数说明
表 4-206 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 163
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-207 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
枚举值：
● stream
– 请求示例
{
"disaster_type" : "stream"
}
响应消息
表 4-208 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
4.6.12 重置容灾配置
功能介绍
重置容灾网络等配置。
1. 将自动“创建委托”以授权DBS云服务访问VPC资源信息、查询IAAS接口。
2. 重置实例容灾网络等配置。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 164
云数据库 GaussDB
API 参考 4 API（推荐）
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.5/{project_id}/instances/{instance_id}/reset-
dr-config
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.5/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
reset-dr-config
● 参数说明
表 4-209 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
无
响应消息
无
● 正常响应样例
无
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 165
云数据库 GaussDB
API 参考 4 API（推荐）
4.7 任务管理
4.7.1 获取任务信息
功能介绍
获取指定任务ID的任务信息。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3/{project_id}/jobs?id={id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/jobs?
id=5cbb8a90-2253-4cff-8a13-49aa8f31dfb5
● 参数说明
表 4-210 请求参数
名称 类型 是否必 描述
选
project_id string 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
id string 是 任务ID。支持通过API接口（除“应用参数模
板”、“增备任务”以外的）返回的异步任
务id查询任务结果。
请求消息
无
响应消息
● 正常响应参数说明
表 4-211 参数说明
名称 参数类型 描述
job Object 任务信息，请参见表job字段数据结
构说明。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 166
云数据库 GaussDB
API 参考 4 API（推荐）
表 4-212 job 字段数据结构说明
名称 参数类型 描述
id String 任务ID。
name String 任务名称。
status String 任务执行状态。
取值：
● 值为“Running”，表示任务正在
执行。
● 值为“Completed”，表示任务执
行成功。
● 值为“Failed”，表示任务执行失
败。
created String 创建时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区
偏移量。
ended String 结束时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区
偏移量。
progress String 任务执行进度。
说明
执行中状态才返回执行进度，例如
“60%”，表示任务执行进度为60%，否
则返回“”。
instance Object 执行任务的实例信息。
请参见表4-213。
fail_reason String 任务执行失败时的错误信息。
表 4-213 instance 字段数据结构说明
名称 参数类型 描述
id String 实例ID。
name String 实例名称。
● 正常响应样例
参数模板列表：
{
"job" : {
"id" : "5cbb8a90-2253-4cff-8a13-49aa8f31dfb5",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 167
云数据库 GaussDB
API 参考 4 API（推荐）
"name" : "CreateGaussDBV5Instance",
"status" : "Completed",
"created" : "2021-07-12T09:22:04+0800",
"ended" : "2021-07-12T10:10:13+0800",
"progress" : "",
"instance" : {
"id" : "b34f8c791f2643578510c093aa2351a8in14",
"name" : "gauss-c1a3"
},
"fail_reason" : null
}
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 168
云数据库 GaussDB
API 参考 5 历史 API
5 历史 API
5.1 实例管理
5.1.1 创建数据库实例
功能介绍
创建GaussDB实例。GaussDB支持创建和主备版实例。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/opengauss/v3/{project_id}/instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
opengauss/v3/054ea741f700d4a32f1bc00f5c80dd4c/instances
● 参数说明
表 5-1 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项
目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 169
云数据库 GaussDB
API 参考 5 历史 API
请求消息
表 5-2 参数说明
名称 是否必 参数类型 说明
选
name 是 String 实例名称。
用于表示实例的名称，同一租户下，同类型
的实例名可重名。
取值范围：4~64个字符之间，必须以字母
开头，区分大小写，可以包含字母、数字、
中划线或者下划线，不能包含其他的特殊字
符。
datastore 是 Object 数据库信息。
详情请参见表5-3。
ha 是 Object 实例部署形态。详情请参见表5-4。
configuration_i 否 String 参数模板ID。当不传该参数时，使用系统默
d 认的参数模板。
port 否 String 数据库端口信息。
GaussDB数据库端口当前只支持设置为
8000，当不传该参数时，默认端口为
8000。
password 是 String 数据库密码。
GaussDB密码取值范围:
非空； 至少包含大写字母（A-Z），小写字
母（a-z），数字（0-9），非字母数字字符
（限定为~!@#%^*-_=+?,）四类字符中的三
类字符；长度8~32个字符。
建议您输入高强度密码，以提高安全性，防
止出现密码被暴力破解等安全风险。
backup_strateg 否 Object 备份策略。
y 详情请参见表5-5。
flavor_ref 是 String 规格码，取值范围：非空。参考数据库实例
规格中GaussDB的“规格编码”列内容获
取。
volume 是 Object volume信息。
详情请参见表5-6。
region 是 String 区域ID。
取值范围：非空，请向企业管理员获取。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 170
云数据库 GaussDB
API 参考 5 历史 API
名称 是否必 参数类型 说明
选
availability_zon 是 String 可用区ID。
e GaussDB取值范围：非空，可选部署在同一
可用区或三个不同可用区，可用区之间用逗
号隔开。详见示例。
● 部署在同一可用区：需要输入三个相同
的可用区。
● 部署在三个不同可用区：需要分别输入
三个不同的可用区。
取值范围：非空，请向企业管理员获取。
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界
面，在虚拟私有云的详情页面查找VPC
ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询VPC列表”的内容。
subnet_id 是 String 子网的网络ID信息，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界
面，单击VPC下的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询子网列表”的内容。
security_group_ 是 String 指定实例所属的安全组。
id ● 方法1：登录虚拟私有云服务的控制台界
面，在安全组的详情页面查找安全组
ID。
● 方法2：获取方法请参见《虚拟私有云
API参考》中“查询安全组列表”的内
容。
charge_info 否 Object 计费类型信息，仅支持按需。
详情请参见表5-7。
time_zone 否 String UTC时区。
● 不选择时，GaussDB默认为UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且只支持整段
时间，如UTC+08:00，不支持UTC
+08:30。
solution 是 String GaussDB支持的部署模式，当前可选的有
triset。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 171
云数据库 GaussDB
API 参考 5 历史 API
表 5-3 datastore 字段数据结构说明
名称 是 参数类型 说明
否
必
选
type 是 String 数据库引擎，取值如下：
GaussDB。
version 否 String 数据库版本。不填时，默认为当前最新版
本。
GaussDB支持如下版本：
● 1.4
● 2.3
表 5-4 ha 字段数据结构说明
名称 是 参数类型 说明
否
必
选
mode 是 String GaussDB当前只支持主备模式，取值：
ha(solution为triset时选择) ，不区分大小
写。
replication_mode 是 String 备机同步参数。
取值：
GaussDB为“sync"
说明
“sync”为同步模式。
consistency 是 String 指定事务一致性类型，取值范围：strong
（强一致性） | eventual(最终一致性)，不
分区大小写。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 172
云数据库 GaussDB
API 参考 5 历史 API
表 5-5 backup_strategy 字段数据结构说明
名称 是 参数类型 说明
否
必
选
start_time 是 String 备份时间段。自动备份将在该时间段内触
发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值必须
为00、15、30或45。
取值示例：
● 08:15-09:15
● 23:00-00:00
keep_days 否 Integer 指定备份文件的可保存天数。
取值范围：1～732。该参数缺省时，默认
填写为7天。
表 5-6 volume 字段数据结构说明
名称 是否 参数类型 说明
必选
type 是 String 磁盘类型。
仅支持LOCALSSD，区分大小写，表示本
地SSD盘。
size 是 Integer 磁盘大小。例如：该参数填写为“40”，
表示为创建的实例分配40GB的磁盘空间。
MCS部署方案：取值范围：（分片数
*40GB）~（分片数*16TB），且大小只能
为分片数*40的整数倍。
BMS部署方案：该参数由所选择的规格自
动计算，不可指定，即使填写，也不会生
效。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 173
云数据库 GaussDB
API 参考 5 历史 API
表 5-7 chargeInfo 字段数据结构说明
名称 是 参数类型 说明
否
必
选
charge_mode 是 String 计费模式。仅支持postPaid，后付费，即
按需付费。
● 请求样例
创建主备版实例：
{
"name": "user_v3_ha_01",
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.3"
},
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"volume": {
"type": "LOCALSSD",
"size": "120"
},
"region": "sa-fb-1",
"availability_zone": "az4.dc0,az4.dc0,az4.dc0",
"vpc_id": "c0a17a45-5e4a-4166-9cd6-cf9846f776a2",
"subnet_id": "ba239f09-7b59-4233-80c9-af2b418803ae",
"security_group_id": "093807ac-4d7a-44c6-b554-b3460dab50cf",
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 7
},
"charge_info": {
"charge_mode": "postPaid"
},
"password": "******",
"configuration_id": "26f22545846040d1a02163a068b6b3a3pr14",
"enterprise_project_id": "",
"time_zone": "UTC+08:00",
"ha":{
"mode":"ha",
"consistency":"strong",
"replication_mode":"sync"
},
"port": "8000",
"solution": "triset"
}
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 174
云数据库 GaussDB
API 参考 5 历史 API
表 5-8 要素说明
名称 参数类型 说明
instance Object 实例信息。
详情请参见表5-9。
job_id String 实例创建的任务id。
仅创建按需实例时会返回该参数。
表 5-9 instance 说明
名称 参数类型 说明
id String 实例id。
name String 实例名称。用于表示实例的名称，同一
租户下，同类型的实例名称可相同。
取值范围：4~64个字符之间，必须以
字母开头，不区分大小写，可以包含字
母、数字、中划线或者下划线，不能包
含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
仅创建按需实例时会返回该参数。
datastore Object 数据库信息。
详情请参见表5-10。
ha Object 数据库部署形态。
详情请参见表5-11。
replica_num Integer 实例副本数。
port String 数据库端口信息，与请求参数相同。
backup_strategy Object 自动备份策略。
详情请参见表5-12。
flavor_ref String 规格码，取值范围：非空。参考数据库
实例规格中GaussDB的“规格编码”列
内容获取。
volume Object volume信息。
详情请参见表5-13。
region String 区域ID。
availability_zone String 可用区ID。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 175
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
security_group_id String 实例所属的安全组。
charge_info Object 付费方式信息，仅支持按需。
详情请参见表5-14。
表 5-10 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎，返回值如下：
GaussDB
version String 数据库版本。
表 5-11 ha 字段数据结构说明
名称 参数类型 说明
mode String GaussDB当前只支持主备模式，取值：
ha(solution为triset时选择) ，不区分大小
写。
replication_ String 备机同步参数。
mode 取值：
● GaussDB为“sync”。
说明
● “sync”为同步模式。
consistency String GaussDB的预留参数：指定事务一致性类
型，取值范围：strong（强一致性） |
eventual(最终一致性)。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 176
云数据库 GaussDB
API 参考 5 历史 API
表 5-12 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内
触发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值必
须为00、15、30或45。
取值示例：
● 08:15-09:15
● 23:00-00:00
如果请求体中不填写
“backup_strategy”字段，则响应体中
“start_time”默认返回
“02:00-03:00”。
keep_days Integer 指定已生成备份文件的可保存天数。
取值范围：1～732。如果请求体中不填
写“backup_strategy”字段，则响应体
中 “keep_days”默认返回“7”。
表 5-13 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
取值如下，区分大小写：
● LOCALSSD，表示本地SSD盘。
size Integer 磁盘大小。
GaussDB分布式实例创建时需指定大
小：要求必须为（分片数 * 40GB）的倍
数，取值范围：（分片数*40GB）~（分
片数*16TB）。
表 5-14 chargeInfo 字段数据结构说明
名称 参数类型 说明
charge_mode String 创建类型，支持按需。
● 正常响应样例
{
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 177
云数据库 GaussDB
API 参考 5 历史 API
"instance": {
"id": "2afb68bc983742308f7a878581762a49in14",
"name": "user_v3_ha_01",
"status": "BUILD",
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.3"
},
"ha": {
"mode": "ha",
"replication_mode": "sync",
"consistency": "strong"
},
"port": "8000",
"volume": {
"type": "LOCALSSD",
"size": 120
},
"region": "sa-fb-1",
"replica_num": 3,
"configuration_id": "26f22545846040d1a02163a068b6b3a3pr14",
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 0
},
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"availability_zone": "az3.dc0,az3.dc0,az3.dc0",
"vpc_id": "aaefc937-c12e-449a-9907-604827337999",
"subnet_id": "ebeaece0-c16c-42aa-a546-0d42d0c68956",
"security_group_id": "290af3b6-289b-4014-a336-b98da9c4fa8e",
"charge_info": {
"charge_mode": "postPaid"
}
},
"job_id": "d7b73e60-4237-43d0-9007-097b7678495d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.1.2 删除数据库实例
功能介绍
删除数据库实例。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 178
云数据库 GaussDB
API 参考 5 历史 API
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/opengauss/v3/{project_id}/instances/{instance_id}
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in01
● 参数说明
表 5-15 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项
目ID/名称。
instance_id 是 实例ID。
请求消息
无
响应消息
● 正常响应要素说明
表 5-16 要素说明
名称 参数类型 说明
job_id String 实例删除的任务id
● 正常响应样例：
{
"job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 179
云数据库 GaussDB
API 参考 5 历史 API
请参见状态码。
错误码
请参见错误码。
5.1.3 查询数据库实例列表
功能介绍
根据指定条件查询实例列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/opengauss/v3/{project_id}/instances?
id={id}&name={name}&type={type}&datastore_type={datastore_type}&vpc_id
={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit}
● URI样例
– 查询所有实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
opengauss/v3/97b026aa9cc4417888c14c84a1ad9860/instances
– 根据指定条件查询实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/97b026aa9cc4417888c14c84a1ad9860/instances?
id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datast
ore_type=GaussDB&vpc_id=19e5d45d-70fd-4a91-87e9-
b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offs
et=0&limit=10
● 参数说明
表 5-17 参数说明
名称 参数类 是否 说明
型 必选
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
id String 否 实例ID。
“*”为系统保留字符，如果id是以“*”起
始，表示按照*后面的值模糊匹配，否则，按
照id精确匹配查询。不能只传入“*”。
name String 否 实例名称。
“*”为系统保留字符，如果name是以“*”
起始，表示按照*后面的值模糊匹配，否则，
按照name精确匹配查询。不能只传入“*”。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 180
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类 是否 说明
型 必选
type String 否 按照实例类型查询。当前支持取值"Ha"（区
分大小写），对应主备式实例。
datastore_ String 否 数据库类型，不区分大小写。
type GaussDB
vpc_id String 否 虚拟私有云ID。
● 方法1：登录虚拟私有云服务的控制台界
面，在虚拟私有云的详情页面查找VPC
ID。
● 方法2：获取方法请参见《虚拟私有云
(VPC) 使用指南》的API参考中“查询VPC
列表”的内容。
subnet_id String 否 子网的网络ID信息。
● 方法1：登录虚拟私有云服务的控制台界
面，单击VPC下的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚拟私有云
(VPC) 使用指南 》的API参考中“查询子
网列表”的内容。
offset Integer 否 索引位置，偏移量。从第一条数据偏移offset
条数据后开始查询，默认为0（偏移0条数
据，表示从第一条数据开始查询），必须为数
字，不能为负数。
limit Integer 否 查询记录数。默认为100，不能为负数，最小
值为1，最大值为100。
请求消息
无。
响应消息
● 正常响应要素说明
表 5-18 参数说明
名称 参数类型 说明
instances Array of objects 实例信息。
详情请参见表5-19。
total_count Integer 总记录数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 181
云数据库 GaussDB
API 参考 5 历史 API
表 5-19 instances 字段数据结构说明
名称 参数类型 说明
id String 实例ID。
name String 创建的实例名称。
status String 实例状态。
取值：
值为“BUILD”，表示实例正在创建。
值为“ACTIVE”，表示实例正常。
值为“FAILED”，表示实例异常。
值为“EXPANDING”，表示实例正在
扩容。
值为“REBOOTING”，表示实例正在
重启。
值为“UPGRADING”，表示实例正在
升级。
值为“RESTORING”，表示实例正在恢
复。
值为“BACKING UP”，表示实例正在
进行备份。
值为“STORAGE FULL”，表示实例磁
盘空间满。
private_ips List<String> 实例内网IP地址列表。CN在的弹性云服
务器创建成功后该值存在，其他情况下
为空字符串。
port Integer 数据库端口号。GaussDB数据库端口当
前只允许为8000。
当不传该参数时，默认端口如下：
8000。
type String 实例类型，取值为"Ha"，对应于主备版
实例。
ha Object 获取分布式实例时返回。
详情请参见表5-20。
region String 实例所在区域。
datastore Object 数据库信息。
详情请参见表5-21。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 182
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
created String 创建时间，格式为“yyyy-mm-dd
hh:mm:ss timezone”。
其中timezone是指时区。
说明：创建时该值为实例下发创建的时
间，创建完成后，该值为创建完成时
间。
updated String 更新时间，格式与“created”字段对应
格式完全相同。
说明：创建时返回值为空，数据库实例
创建成功后该值不为空。
db_user_name String 默认用户名。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
security_group_ String 安全组ID。
id
flavor_ref String 规格码。参考数据库实例规格中
GaussDB的“规格编码”列内容获取。
flavor_info Object 规格信息。
详情请参见表5-22
volume Object Volume信息。
详情请参见表5-23。
backup_strateg Object 备份策略。
y 详情请参见表5-24。
maintenance_w String 可维护时间窗，为UTC时间。
indow
nodes Array of objects 实例节点信息。
详情请参见表5-25。
related_instanc Array of objects 所关联的数据库实例列表。GaussDB不
e 涉及该参数。
instance_mode String enterprise为企业版
time_zone String 时区。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 183
云数据库 GaussDB
API 参考 5 历史 API
表 5-20 ha 字段数据结构说明
名称 参数类型 说明
consistency String 事务一致性类型。取值为“strong”、
“eventual”，分别表示强一致性、最终
一致性。
replication_mo String 备机同步参数。
de 取值：非空。
GaussDB为 “sync”
说明
“sync”为同步模式。
表 5-21 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎。
version String 数据库版本。
表 5-22 flavor_info 字段数据结构说明
名称 参数类型 说明
vcpu Integer cpu核数。
mem Integer 内存大小。
表 5-23 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
size Integer 磁盘大小。
表 5-24 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内触
发。
当前时间指UTC时间。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 184
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
keep_days Integer 已生成的备份文件可以保存的天数。
取值范围：0～732。为0时，表示未设置
自动备份策略或备份策略已关闭。
表 5-25 nodes 字段数据结构说明
名称 参数类型 说明
id String 节点ID。
name String 节点名称。
role String 节点类型，取值为“master”、
“slave”，分别对应于主节点、备节点。
status String 节点状态。
availability_zon String 可用区。
e
● 正常响应样例
实例列表：
{
"instances": [
{
"id": "b331ed66cc3249f78bc20737308c01f4in14",
"status": "ACTIVE",
"name": "gauss-9e88",
"port": 8000,
"type": "enterprise",
"ha": {
"consistency": "strong",
"replication_mode": "sync"
},
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.4"
},
"created": "2021-01-15 01:46:40 UTC",
"updated": "2021-01-15 02:05:03 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 120
},
"nodes": [
{
"id": "02ebf757aaf94074855f49cc6e0e4712no14",
"name": "gauss-9e88_gaussdbv5cn_2",
"role": "master",
"status": "ACTIVE",
},
{
"id": "0a87b8ecbfeb46aba1409cfc0f0d5c34no14",
"name": "gauss-9e88_gaussdbv5cn_0",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 185
云数据库 GaussDB
API 参考 5 历史 API
"role": "master",
"status": "ACTIVE",
},
{
"id": "2d9fec1ab3834936b074d63acf48b1f2no14",
"name": "gauss-9e88_gaussdbv5dn3_2",
"role": "master",
"status": "ACTIVE",
},
{
"id": "48bb08a2d635435891ac0caa1c0bf2e3no14",
"name": "gauss-9e88_gaussdbv5dn1_0",
"role": "master",
"status": "ACTIVE",
},
{
"id": "5df830f652204827ada32f8bc28b107eno14",
"name": "gauss-9e88_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "8a97a246cee841b38c5b47290d4c9c38no14",
"name": "gauss-9e88_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
},
{
"id": "8c1a3f8eecca4d9e9974a868bb6dd942no14",
"name": "gauss-9e88_gaussdbv5dn2_0",
"role": "master",
"status": "ACTIVE",
},
{
"id": "9bd0c80b8a684cc9bd7d99dd5adffb07no14",
"name": "gauss-9e88_gaussdbv5dn3_1",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "9e2a3cd541e249d4af5aa57c5d3a7f39no14",
"name": "gauss-9e88_gaussdbv5dn1_2",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "b046d28989ec4ae5a1a9ab20fe65f248no14",
"name": "gauss-9e88_gaussdbv5dn2_2",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "b614cc12fd3742dbb230245f88a7bf00no14",
"name": "gauss-9e88_gaussdbv5dn3_0",
"role": "slave",
"status": "ACTIVE",
},
{
"id": "caba8e88c3c84ae58202f1f589490611no14",
"name": "gauss-9e88_gaussdbv5dn2_1",
"role": "slave",
"status": "ACTIVE",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 186
云数据库 GaussDB
API 参考 5 历史 API
}
],
"private_ips": [
"192.168.28.81 / 192.168.27.52 / 192.168.16.253"
],
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "prePaid"
},
"backup_strategy": {
"start_time": "19:00-20:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "6e76681b-a2f5-4c5f-97c5-ba4fd3c0dfb2",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
"order_id": "CS2101150917EUW8N"
},
{
"id": "226b4afcfcc84c86bf1b9cb345d3b00fin14",
"status": "ACTIVE",
"name": "UTS-gauss-ad53-2C3D",
"port": 8000,
"type": "enterprise",
"ha": {
"consistency": "strong",
"replication_mode": "sync"
},
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"created": "2021-01-08 09:18:27 UTC",
"updated": "2021-01-14 13:25:03 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 120
},
"nodes": [
{
"id": "07538a1def584cee99e2a5685eeab36ano14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "21f41baba1e2454f82331b7cb5aeabe5no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 187
云数据库 GaussDB
API 参考 5 历史 API
{
"id": "2909771a3b3e4e3998f9388e77d22391no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "2bd9a90a5da242a6b0743a7f597f6106no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "77092f1dadb74d3ea13d28269cdd3590no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "a46bfaa6d5a24355a60fce7432b964cano14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "aa5277736f3844e2a7adeb9de529e2b1no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b1d798e4ea7344dfa95032984bc6cfd7no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "b9a46540186f4c0781eabaa2a79594cbno14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "d283813030364060ab64371d50294977no14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "eb7bce29b2284cd290405eaddc1b1a1eno14",
"name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_0",
"role": "master",
"status": "FAILED",
"availability_zone": "az2xahz"
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 188
云数据库 GaussDB
API 参考 5 历史 API
}
],
"private_ips": [
"192.168.30.44 / 192.168.29.231"
],
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "prePaid"
},
"backup_strategy": {
"start_time": "18:00-19:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
},
{
"id": "706c65c3dd7d497ab16f5b3a113690abin14",
"status": "ACTIVE",
"name": "UTS-gauss-7362",
"port": 8000,
"type": "enterprise",
"ha": {
"replication_mode": "sync"
},
"region": "cn-xianhz-1",
"datastore": {
"type": "GaussDB",
"version": "1.2"
},
"created": "2020-12-23 03:21:41 UTC",
"updated": "2021-01-15 02:32:13 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 80
},
"nodes": [
{
"id": "25b7f16ee4084b7884d52f1bdfab4e68no14",
"name": "UTS-gauss-7362_gaussdbv5dn1_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "ad6f02f31744422fa8ce487e81c9e7afno14",
"name": "UTS-gauss-7362_gaussdbv5cn_0",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 189
云数据库 GaussDB
API 参考 5 历史 API
{
"id": "b30c56582bf44a548e3bb5b5af6c4773no14",
"name": "UTS-gauss-7362_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
},
{
"id": "f79ea0600cba42b2888bd9bd67e52a79no14",
"name": "UTS-gauss-7362_gaussdbv5dn1_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az2xahz"
}
],
"private_ips": [
"192.168.26.70"
],
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "postPaid"
},
"backup_strategy": {
"start_time": "16:00-17:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
},
{
"id": "4ad42d079a3948d88c28d6236211b21ein14",
"status": "ACTIVE",
"name": "UTS-gauss-4336",
"port": 8000,
"type": "enterprise",
"ha": {
"replication_mode": "sync"
},
"region": "cn-xianhz-1",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"created": "2020-12-03 14:28:53 UTC",
"updated": "2021-01-14 13:20:10 UTC",
"volume": {
"type": "ULTRAHIGH",
"size": 40
},
"nodes": [
{
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 190
云数据库 GaussDB
API 参考 5 历史 API
"id": "254dbda6f03643519ad64b39481bd11cno14",
"name": "UTS-gauss-4336_gaussdbv5dn1_2",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az1xahz"
},
{
"id": "6ad76d4db26443c2a93b280739a31558no14",
"name": "UTS-gauss-4336_gaussdbv5dn1_1",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az1xahz"
},
{
"id": "9fdebf821bdf444a8689b19c0ff588ceno14",
"name": "UTS-gauss-4336_gaussdbv5cn_0",
"role": "master",
"status": "FAILED",
"availability_zone": "az1xahz"
},
{
"id": "dd64bdbc02a542d88823b1582f772d25no14",
"name": "UTS-gauss-4336_gaussdbv5cn_1",
"role": "master",
"status": "ACTIVE",
"availability_zone": "az1xahz"
},
{
"id": "de3c41461045466faf6c2b96eb709540no14",
"name": "UTS-gauss-4336_gaussdbv5dn1_0",
"role": "slave",
"status": "ACTIVE",
"availability_zone": "az1xahz"
}
],
"private_ips": [
"192.168.30.93 / 192.168.29.232"
],
"db_user_name": "root",
"vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc",
"subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05",
"security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163",
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in",
"flavor_info": {
"vcpu": 2,
"mem": 16
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "postPaid"
},
"backup_strategy": {
"start_time": "18:00-19:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00",
"instance_mode":"enterprise"
}
],
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 191
云数据库 GaussDB
API 参考 5 历史 API
"total_count": 4
}
● 实例详情：
{
"instances": [
{
"id": "bab2fb1fc43a4b3e9c288fef9cd60b69in14",
"status": "BUILD",
"name": "user_v3_ha_01",
"port": 8000,
"type": "Ha",
"ha": {
"consistency": "strong",
"replication_mode": "sync"
},
"region": "sa-fb-1",
"datastore": {
"type": "GaussDB(for opengauss)",
"version": "1.4"
},
"created": "2021-03-02 09:30:30 UTC",
"updated": "2021-03-14 13:20:00 UTC",
"volume": {
"type": "LOCALSSD",
"size": 120
},
"nodes": [
{
"id": "2d4f4215ef27453daf8b144c32ac3a9dno14",
"name": "user_v3_ha_01_root_2",
"role": "slave",
"status": "FAILED",
"availability_zone": "az4.dc0"
},
{
"id": "9a6645a190134f61884be0cb450143dbno14",
"name": "user_v3_ha_01_root_0",
"role": "master",
"status": "FAILED",
"availability_zone": "az4.dc0"
},
{
"id": "a1017382f3994b028ab1fae5dc999decno14",
"name": "user_v3_ha_01_root_1",
"role": "slave",
"status": "FAILED",
"availability_zone": "az4.dc0"
}
],
"tags": [],
"private_ips": [
"192.168.0.107 / 192.168.0.187 / 192.168.0.201"
],
"public_ips": [],
"db_user_name": "root",
"vpc_id": "c0a17a45-5e4a-4166-9cd6-cf9846f776a2",
"subnet_id": "ba239f09-7b59-4233-80c9-af2b418803ae",
"security_group_id": "093807ac-4d7a-44c6-b554-b3460dab50cf",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.arm8.ha",
"flavor_info": {
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 192
云数据库 GaussDB
API 参考 5 历史 API
"vcpu": 8,
"mem": 64
},
"switch_strategy": "Reliability",
"charge_info": {
"charge_mode": "postPaid"
},
"backup_strategy": {
"start_time": "17:00-18:00",
"keep_days": 7
},
"maintenance_window": "18:00-22:00",
"enterprise_project_id": "0",
"time_zone": "UTC+08:00"
"instance_mode":"enterprise"
}
],
"total_count": 1
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.1.4 同城切换 AZ
功能介绍
切换主DN组至对应AZ。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
注意事项
切换完成后，可能会导致集群主备分布不均衡，如果需要将集群重新切回均衡状态，
可以参考实例主备状态重置，将集群主备状态切回。
URI
● URI格式
POST https://{Endpoint}/opengauss/v3/{project_id}/instances/{instance_id}/
switch-az
● URI样例
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 193
云数据库 GaussDB
API 参考 5 历史 API
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/switch-az
● 参数说明
表 5-26 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 5-27 参数说明
名称 是否必选 参数类型 说明
availability_zone 是 String 需要将主DN切换到的AZ。
● 请求样例
{
"availability_zone": "az3.dc0"
}
响应消息
● 正常响应要素说明
表 5-28 要素说明
名称 参数类型 说明
job_id String 同城切换AZ的任务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 194
云数据库 GaussDB
API 参考 5 历史 API
● 异常
请参见状态码。
错误码
请参见错误码。
5.1.5 实例主备状态重置
功能介绍
将数据库实例恢复为初始配置的主备状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
● 实例在创建、变更规格、异常等状态下不能执行该操作。
● 该功能不支持1.x版本的主备版实例。
URI
● URI格式
PUT https://{Endpoint}/opengauss/v3/{project_id}/instances/{instance_id}/
rebalance
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/rebalance
表 5-29 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 是 String 实例ID。在实例详情页获取。
请求消息
无。
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 195
云数据库 GaussDB
API 参考 5 历史 API
响应参数
表 5-30 要素说明
参数 参数类型 描述
job_id String 任务ID。
● 正常响应样例
{
"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.1.6 查询实例主备平衡状态
功能介绍
查询实例是否发生过主备切换而导致主机负载不均衡。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/opengauss/v3/{project_id}/instances/{instance_id}/
balance
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0c8243400d37468bb4aed3cc94c2911d/instances/
f9b5f9b296ec6808e067in14/balance
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 196
云数据库 GaussDB
API 参考 5 历史 API
表 5-31 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
无。
响应消息
● 正常响应要素说明
表 5-32 要素说明
名称 参数类型 说明
balanced boolean 平衡状态。显示是否有
集群实例发生过主备切
换而导致主机负载不均
衡。
● 返回"true"，均衡。
● 返回"false"，不均
衡。
● 正常响应样例
{
"balanced": true
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 197
云数据库 GaussDB
API 参考 5 历史 API
5.2 备份管理
5.2.1 查询备份列表
功能介绍
获取备份列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
该接口仅支持查询GaussDB的手动全量备份及自动全量备份。
URI
● URI格式
GET https://{Endpoint}/opengauss/v3/{project_id}/backups?
instance_id={instance_id}&backup_id={backup_id}&backup_type={backup_typ
e}&offset={offset}&limit={limit}&begin_time={begin_time}&end_time={end_ti
me}
● URI样例
– 查询所有备份列表
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups
– 根据指定条件查询实例列表
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0483b6b16e954cb88930a360d2c4e663/backups?
instance_id=88be33e4c5a64ceba42b42da89310111in14&backup_id=88be1234
c5a64ceba42b42da89310111br14&backup_type=auto&begin_time=2022-05-0
9T16:15:50+0800&end_time=2022-05-09T16:20:45+0800&limit=1&offset=1
● 参数说明
表 5-33 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
instance_id 否 String 实例ID。
backup_id 否 String 备份ID，严格匹配UUID规
则。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 198
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
backup_type 否 String 备份类型，取值范围：
● auto 自动全量备份
● manual 手动全量备份
● Snapshot_Xbsa xbsa 手动
全量备份
offset 否 Integer 索引位置，偏移量。从第一条
数据偏移offset条数据后开始
查询，默认为0（偏移0条数
据，表示从第一条数据开始查
询），必须为数字，不能为负
数。
最小值：0
limit 否 Integer 查询记录数。默认为100，不
能为负数，最小值为1，最大
值为100。
最小值：1
最大值：100
begin_time 否 String 查询开始时间，格式为
“yyyy-mm-
ddThh:mm:ssZ”。其中，T指
某个时间的开始；Z指时区偏
移量。与end_time必须同时使
用。
end_time 否 String 查询结束时间，格式为
“yyyy-mm-
ddThh:mm:ssZ”，且大于查
询开始时间。其中，T指某个
时间的开始；Z指时区偏移
量。与begin_time必须同时使
用。
请求消息
无。
响应消息
● 正常响应要素说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 199
云数据库 GaussDB
API 参考 5 历史 API
表 5-34 参数说明
参数 参数类型 描述
backups Array of 备份信息。
objects 详情请参见表5-35。
total_count Long 备份文件的总数。
表 5-35 backups 字段数据结构说明
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
description String 备份文件描述信息。
begin_time String 备份开始时间，格式为"yyyy-mm-
ddThh:mm:ssZ"。 其中，T指某个时间的开
始；Z指时区偏移量。
end_time String 备份结束时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。 其中，T指某个时间的开
始；Z指时区偏移量。
status String 备份状态
枚举值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
size Double 备份大小(单位：MB)。
type String 备份类型
取值：
● auto：自动全量备份。
● manual：手动全量备份。
datastore Object 数据库信息。
详情请参见表5-36
instance_id String 实例ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 200
云数据库 GaussDB
API 参考 5 历史 API
表 5-36 datastore 字段数据结构说明
参数 参数类型 描述
type String 数据库引擎，不区分大小写，取值如下：
GaussDB。
version String 数据库版本。不填时，默认为当前最新版本。
● 正常响应样例
{
"backups": [
{
"id": "a696cd25e4fc453aa503650225cece8bbr14",
"name": "GaussDB-hly-ha-20220509080110906",
"description": null,
"status": "FAILED",
"size": 0.0,
"type": "auto",
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.4"
},
"begin_time": "2022-05-09T16:01:10+0800",
"end_time": "2022-05-09T16:04:31+0800",
"instance_id": "164abc6d35114095bb849d007b19db3bin14"
},
{
"id": "5651c62a7f12461c98020dd3abfe24ccbr14",
"name": "GaussDB-hly-master-20220509022658257",
"description": null,
"status": "FAILED",
"size": 0.0,
"type": "auto",
"datastore": {
"type": "GaussDB",
"version": "1.4"
},
"begin_time": "2022-05-09T10:26:58+0800",
"end_time": "2022-05-09T10:30:17+0800",
"instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
}
],
"total_count": 167
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 201
云数据库 GaussDB
API 参考 5 历史 API
错误码
请参见错误码。
5.2.2 创建手动备份
功能介绍
创建手动备份。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/opengauss/v3/{project_id}/backups
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups
● 参数说明
表 5-37 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
请求消息
● 参数说明
表 5-38 参数说明
参数 是否必选 参数类型 描述
instance_id 是 String 实例ID。
name 是 String 备份名称，4~64个字符，必须
以英文字母开头，区分大小
写，可以包含英文字母、数
字、中划线或者下划线，不能
包含其他特殊字符。
最小长度：4
最大长度：64
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 202
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
description 否 String 备份描述，不能包含>!<"&'=
特殊字符，不大于256个字
符。
最大长度：256
backup_type 否 String 创建备份的类型，缺省值为
"completed" 。
取值：
● completed: 全备。
● differential: 增备。
● 请求样例
创建手动备份
{
"instance_id" : "7e01ac5ac5274957ba506f3851d11d51in14",
"name" : "backupwqwq3",
"description" : "manual backup"
}
响应消息
● 正常响应要素说明
表 5-39 响应 Body 参数
参数 参数类型 描述
backup Object 备份信息。
详情请参见表5-40
job_id String 任务ID。
表 5-40 backup 字段数据结构说明
参数 参数类型 描述
id String 备份ID。
name String 备份名称。
description String 备份描述。
begin_time String 备份开始时间，格式为“yyyy-mm-
ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 203
云数据库 GaussDB
API 参考 5 历史 API
参数 参数类型 描述
status String 备份状态，取值：
● BUILDING：备份中。
● COMPLETED：备份完成。
● FAILED：备份失败。
● DELETING：备份删除中。
type String 备份类型，“manual”表示手动全量备份
instance_id String 实例ID。
● 正常响应样例
{
"backup": {
"id": "e76112bfb2074871bf54cb8df5af7f64br14",
"name": "backupwqwq32",
"description": "mannual backup",
"status": "BUILDING",
"type": "manual",
"begin_time": "2022-05-09T18:02:31+0800",
"instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
},
"job_id": "e4733090-b2c8-4ea7-a33a-f55f65723fb3"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.2.3 删除手动备份
功能介绍
删除手动备份。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
DELETE https://{Endpoint}/opengauss/v3/{project_id}/backups/{backup_id}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 204
云数据库 GaussDB
API 参考 5 历史 API
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/054ea741f700d4a32f1bc00f5c80dd4c/backups/
e28d08754b1a490fb2b3540ed013a7fbbr14
● 参数说明
表 5-41 参数说明
参数 是否必选 参数类型 描述
project_id 是 String 租户在某一region下的project
ID。
获取方法请参见获取项目ID/
名称。
backup_id 是 String 备份ID，严格匹配UUID规
则。
请求消息
无。
响应消息
● 正常响应要素说明
无。
● 正常响应样例
无。
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.2.4 恢复到新实例
功能介绍
根据备份恢复新实例。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 205
云数据库 GaussDB
API 参考 5 历史 API
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
接口约束
目标实例与源实例的数据库版本和实例类型必须一致。
目标实例规格必须大于等于源实例规格。
仅支持ECS和MCS的金融版（标准型）和1主3备形态的实例。
URI
● URI格式
POST https://{Endpoint}/opengauss/v3/{project_id}/instances
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/
opengauss/v3/0483b6b16e954cb88930a360d2c4e663/instances
● 参数说明
表 5-42 参数说明
参数 是否必选 描述
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
请求消息
表 5-43 参数说明
参数 是否必选 参数类型 描述
name 是 String 实例名称。
用于表示实例的名称，同一租户
下，同类型的实例名可重名。
取值范围：4~64个字符之间，
必须以字母开头，区分大小写，
可以包含字母、数字、中划线或
者下划线，不能包含其他的特殊
字符。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 206
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
availability_zo 是 String 可用区ID。
ne GaussDB取值范围：非空，可选
部署在同一可用区或三个不同可
用区，可用区之间用逗号隔开。
详见示例。
● 部署在同一可用区：需要输
入三个相同的可用区。
● 部署在三个不同可用区：需
要分别输入三个不同的可用
区。
取值范围：非空，请向企业管理
员获取。
flavor_ref 是 String 规格码，取值范围：非空。参考
数据库实例规格中GaussDB的
“规格编码”列内容获取。
volume 是 Object volume信息。
详情请参见表5-44
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务
的控制台界面，在虚拟私有
云的详情页面查找VPC ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
VPC列表”的内容。
subnet_id 是 String 子网的网络ID信息，获取方法如
下：
● 方法1：登录虚拟私有云服务
的控制台界面，单击VPC下
的子网，进入子网详情页
面，查找网络ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
子网列表”的内容。
security_grou 是 String 指定实例所属的安全组。
p_id ● 方法1：登录虚拟私有云服务
的控制台界面，在安全组的
详情页面查找安全组ID。
● 方法2：获取方法请参见《虚
拟私有云API参考》中“查询
安全组列表”的内容。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 207
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
password 是 String 数据库密码。
GaussDB密码取值范围:
非空； 至少包含大写字母（A-
Z），小写字母（a-z），数字
（0-9），非字母数字字符（限
定为~!@#%^*-_=+?,）四类字符
中的三类字符；长度8~32个字
符。
建议您输入高强度密码，以提高
安全性，防止出现密码被暴力破
解等安全风险。
charge_info 否 Object 付费方式信息，支持按需。
详情请参见表5-45。
backup_strate 否 Object 自动备份策略。
gy 详情请参见表5-47。
restore_point 是 Object 恢复数据源对象。
详情请参见表5-46。
configuration_ 否 String 参数组ID。当不传该参数时，使
id 用系统默认的参数模板。
port 否 String GaussDB数据库端口当前只支持
设置为8000，当不传该参数
时，默认端口为8000。
time_zone 否 String UTC时区。
● 不选择时，GaussDB默认为
UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且
只支持整段时间，如UTC
+08:00，不支持UTC
+08:30。
master_az 否 String 主可用区ID。取值为
availability_zone三个可用区ID
其一。当原实例存在单独的仲裁
可用区时必传，其他情况不需要
填写。
arbitration_az 否 String 仲裁可用区ID。取值为
availability_zone三个可用区ID
其一。当原实例存在单独的仲裁
可用区时必传，其他情况不需要
填写。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 208
云数据库 GaussDB
API 参考 5 历史 API
参数 是否必选 参数类型 描述
xbsa_ssl_certs 否 Object xbsa证书信息。
详情请参见表5-48。
表 5-44 volume 字段数据结构说明
参数 是否必选 参数类型 描述
type 是 String 磁盘类型。
仅支持LOCALSSD，
ULTRAHIGH。
size 是 Integer 磁盘大小,需要大于等于原实
例。例如：该参数填写为
“40”，表示为恢复的实例分
配40GB的磁盘空间。
MCS部署方案：取值范围：（分
片数*40GB）~（分片数
*16TB），且大小只能为分片数
*40的整数倍。
表 5-45 charge_info 字段数据结构说明
参数 是否必选 参数类型 描述
charge_mode 是 String 计费模式。支持postPaid，后付
费，即按需付费。
表 5-46 restore_point 字段数据结构说明
参数 是否必选 参数类型 描述
instance_id 是 String 源实例ID。
backup_id 是 String 用于恢复的备份ID。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 209
云数据库 GaussDB
API 参考 5 历史 API
表 5-47 backup_strategy 字段数据结构说明
参数 是否必选 参数类型 描述
start_time 是 String 备份时间段。自动备份将在该时
间段内触发。
取值范围：非空，格式必须为
hh:mm-HH:MM且有效，当前
时间指UTC时间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且
取值必须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days 否 Integer 指定备份文件的可保存天数。
取值范围：0～732，开放
“gaussdb_feature_supportCo
nsoleBackupPolicyDay_36500
”白名单后，支持备份文件最长
保留天数36500天。该参数缺省
或为0时，默认填写为30天。
表 5-48 xbsa_ssl_certs 字段数据结构说明
参数 是否必选 参数类型 描述
ca_cert_pem 是 String 根证书文件内容。base64 编
码。
client_crt 是 String 用户证书内容。base64 编码。
client_key 是 String 用户私钥内容。base64 编码。
rand_pass 是 String 私钥文件的密码。
● 请求样例
恢复实例：
{
"name": "targetInst",
"availability_zone": "aaa,bbb,ccc",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.x868.co",
"volume": {
"type": "LOCALSSD",
"size": 160
},
"vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
"subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
"security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 210
云数据库 GaussDB
API 参考 5 历史 API
"password": "******",
"restore_point": {
"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin14",
"backup_id": "2f4ddb93b9014b0893d81d2e472f30febr14"
},
"configuration_id": "52e86e87445847a79bf807ceda213165pr01",
"port": 8000,
"time_zone": "UTC+04:00",
"master_az": "aaa",
"arbitration_az": "bbb"
}
响应消息
● 正常响应要素说明
表 5-49 要素说明
参数 参数类型 描述
instance Object 实例信息。
详情请参见表5-50。
job_id String 恢复新实例的任务id。
表 5-50 instance 说明
参数 参数类型 描述
id String 实例id。
name String 实例名称。 用于表示实例的名称，同一租户
下，同类型的实例名可重名。
取值范围：4~64个字符之间，必须以字母开
头，区分大小写，可以包含字母、数字、中划
线或者下划线，不能包含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
datastore Object 数据库信息。
详情请参见表5-51
ha Object 实例部署形态。
详情请参见表5-52
port String 数据库端口信息。 当不传该参数时，默认端口
8000。
volume Object volume信息。
详情请参见表5-53
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 211
云数据库 GaussDB
API 参考 5 历史 API
参数 参数类型 描述
backup_strat Object 自动备份策略。
egy 详情请参见表5-54
replica_num Integer 实例副本数。
region String 区域ID。
flavor_ref String 规格码。
availability_z String 可用区ID。可选部署在同一可用区或三个不同
one 可用区，可用区之间用逗号隔开。
取值范围：非空，请向企业管理员获取。
vpc_id String 虚拟私有云ID。
subnet_id String 子网ID。
security_grou String 安全组ID。
p_id
charge_info Object 付费方式信息，支持按需。
详情请参见表5-55。
表 5-51 datastore 字段数据结构说明
参数 参数类型 描述
type String 数据库引擎，返回值如下： GaussDB。
枚举值：
● GaussDB。
version String 数据库版本。
表 5-52 ha 字段数据结构说明
参数 参数类型 描述
mode String GaussDB 分布式模式，返回值为：enterprise
（企业版）；主备版，返回值为：
centralization_standard(主备版)。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 212
云数据库 GaussDB
API 参考 5 历史 API
参数 参数类型 描述
replication_ String 备机同步参数。
mode 取值：
GaussDB为“sync”。
说明
“sync”为同步模式。
枚举值：
● sync
consistency String GaussDB的预留参数：指定实例一致性类型，
取值范围：strong（强一致性） | eventual(最
终一致性)。
枚举值：
● strong
● eventual
表 5-53 volume 字段数据结构说明
参数 参数类型 描述
type String 磁盘类型。
取值如下，区分大小写：
● LOCALSSD
枚举值：
● LOCALSSD
size Integer 磁盘大小。
GaussDB分布式实例恢复时需指定大小：要求
必须为（分片数 * 40GB）的倍数，取值范围：
（分片数40GB）~（分片数16TB）。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 213
云数据库 GaussDB
API 参考 5 历史 API
表 5-54 backup_strategy 字段数据结构说明
参数 参数类型 描述
start_time String 备份时间段。自动备份将在该时间段
内触发。
取值范围：非空，格式必须为hh:mm-
HH:MM且有效，当前时间指UTC时
间。
● HH取值必须比hh大1。
● mm和MM取值必须相同，且取值
必须为整点。
取值示例：
● 08:00-09:00
● 23:00-00:00
keep_days Integer 指定备份文件的可保存天数。
取值范围：0～732，开放
“gaussdb_feature_supportConsoleB
ackupPolicyDay_36500”白名单后，
支持备份文件最长保留天数36500天。
该参数缺省时，默认填写为30天。
表 5-55 charge_info 字段数据结构说明
参数 参数类型 描述
charge_mode String 计费模式。支持postPaid，后付费，即按需付
费。
● 正常响应样例
{
"instance": {
"id": "2gfdsh844a4023a776fc5c5fb71fb4in14",
"name": "gaussdb-instance-rep2",
"status": "BUILD",
"datastore": {
"type": "GaussDB(for openGauss)",
"version": "1.4"
},
"ha": {
"mode": "enterprise",
"consistency": "strong",
"replication_mode": "sync"
},
"volume": {
"type": "LOCALSSD",
"size": 160
},
"port": "8000",
"replica_num": 3,
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 214
云数据库 GaussDB
API 参考 5 历史 API
"region": "regionA",
"flavor_ref": "gaussdb.opengauss.ee.ld.2xlarge.x868.co",
"availability_zone": "aaa,bbb,ccc",
"vpc_id": "490a4a08-ef4b-44c5-94be-3051ef9e4fce",
"subnet_id": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f",
"security_group_id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5",
"charge_info": {
"charge_mode": "postPaid"
},
},
"job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3 容灾管理（V3.1）
5.3.1 查询可搭建容灾实例列表
功能介绍
根据主实例查询可搭建容灾的实例列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/disaster/instances/
candidates
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/4a52a8a8f63d4c6d966dff0e20b69738/disaster/instances/candidates
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 215
云数据库 GaussDB
API 参考 5 历史 API
表 5-56 参数说明
名称 是否必选 参 说明
数
类
型
project_id 是 Stri 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
disaster_type 是 Stri 容灾类型，枚举值:
ng stream；
dorado；
slave_region 是 Stri 备region。
ng
slave_project_ 是 Stri 备端项目id。
id ng
master_instan 是 Stri 主实例id。
ce_id ng
limit 否 Int 查询记录数。为空时，默认为100。最
ege 小值为1，最大值为100。
r
offset 否 Int 索引位置，偏移量。从第一条数据偏移
ege offset条数据后开始查询，默认为0（偏
r 移0条数据，表示从第一条数据开始查
询），必须为数字，不能为负数。
● 请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3.1/4a52a8a8f63d4c6d966dff0e20b69738/
disaster/instances/candidates?disaster_type=&slave_region=sa-
fb-1&slave_project_id=4a52a8a8f63d4c6d966dff0e20b69738&master_instance_id=d1060faf
0d3743dd8830b39e7423bc9ain14&offset=0&limit=10
请求消息
无
响应消息
表 5-57 响应 Body 参数列表
名称 参数类型 说明
id String 主实例id。
name String 主实例名称。
total Integer 总记录数。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 216
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
slave_instance Array of Object 可搭建容灾备实例列表。
_candidates
表 5-58 slave_instance_candidates 字段数据结构说明
名称 参数类型 说明
id String 实例id。
name String 实例名称。
● 正常响应样例
{
"id": "d1060faf0d3743dd8830b39e7423bc9ain14",
"name": "test-1",
"total": 1,
"slave_instance_candidates": [
{
"id": "fe55ba437e8f4e1a836c866ec7cf3f8cin14",
"name": "slave-test-1"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.2 容灾操作校验
功能介绍
容灾操作前校验操作是否可以执行。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 217
云数据库 GaussDB
API 参考 5 历史 API
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/operation-precheck
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
a7d62bf77aa04fceb52fbd57181c9e3ein14/disaster/operation-precheck
● 参数说明
表 5-59 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
● 请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3.1/4a52a8a8f63d4c6d966dff0e20b69738/
instances/234b7837d830484890f6a1e55b732401in14/disaster/operation-precheck
请求消息
● 参数说明
表 5-60 参数说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
dest_region 是 String 对端region。
dest_instance_id 是 String 对端region实例id。
dest_project_id 是 String 对端region项目id。
operate 是 String 操作类型。
枚举值:
● construct
● switchover
● failover
● stop
● simulation_start
● simulation_end
● dr_log_keep_start
● dr_log_keep_end
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 218
云数据库 GaussDB
API 参考 5 历史 API
– 请求示例
{
"disaster_type":"stream",
"dest_region":"sa-fb-1",
"dest_instance_id":"e23ba4d51161428a8b6a0f435aff16d8in13",
"dest_project_id":"4a52a8a8f63d4c6d966dff0e20b69738",
"operate":"construct"
}
响应消息
表 5-61 响应 Body 参数列表
名称 参数类型 说明
enable Boolean 是否可操作。
deny_reason String 不可操作原因。
● 正常响应样例
{
"enable":true,
"deny_reason":""
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.3 查询容灾集群监控状态
功能介绍
查询实例搭建容灾后实时容灾状态。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 219
云数据库 GaussDB
API 参考 5 历史 API
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/monitor
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
a7d62bf77aa04fceb52fbd57181c9e3ein14/disaster/monitor
● 参数说明
表 5-62 参数说明
名称 是否必选 参 说明
数
类
型
project_id 是 Stri 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
instance_id 是 Stri 实例ID。
ng
dest_region 是 Stri 对端region。
ng
dest_project_i 是 Stri 对端region项目id。
d ng
dest_instance 是 Stri 对端region实例id。
_id ng
请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/v3.1/4a52a8a8f63d4c6d966dff0e20b69738/
instances/4d653d1caf0e4a49b4753713fac679e3in14/disaster/monitor?dest_region=sa-
fb-1&dest_project_id=4a52a8a8f63d4c6d966dff0e20b69738&dest_instance_id=d1060faf0d3
743dd8830b39e7423bc9ain14
请求消息
无
响应消息
表 5-63 响应 Body 参数列表
名称 参数类型 说明
instance_id String 实例id。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 220
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
status String 容灾状态。
rpo String 数据恢复点目标。
rto String 数据恢复时间目标。
rpo_threshold String rpo阈值。
rto_threshold String rto阈值。
switchover_pro String 主从切换进度。该值为一个百分数。例
gress 如：40%
failover_progr String 容灾升主进度。该值为一个百分数。例
ess 如：40%
dest_disaster_s Object 对端region实例容灾状态
tatus
表 5-64 dest_disaster_status 字段数据结构说明
名称 参数类型 说明
instance_id String 实例id。
status String 容灾状态。
rpo String 数据恢复点目标。
rto String 数据恢复时间目标。
rpo_threshold String rpo阈值。
rto_threshold String rto阈值。
switchover_ String 主从切换进度。该值为一个百分数。例
progress 如：40%
failover_progr String 主从切换进度。该值为一个百分数。例
ess 如：40%
● 正常响应样例
{
"rpo":"0",
"rto":"0",
"status":"archive",
"instance_id":"b3692282395340c5b5421ecf3d7bd6adin14",
"rto_threshold":"900",
"rpo_threshold":"10",
"failover_progress":"",
"switchover_ progress ":"",
"dest_disaster_status":{
"rpo":"0",
"rto":"0",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 221
云数据库 GaussDB
API 参考 5 历史 API
"status":"failover",
"instance_id":"dd93e98e103b4fc4b5a978a6bd6f03a9in14",
"rto_threshold":"900",
"rpo_threshold":"10",
"failover_ progress":"40%",
"switchover_ progress":"",
}
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.4 查询容灾关系列表
功能介绍
查询容灾关系列表。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
GET https://{Endpoint}/gaussdb/v3.1/{project_id}/disaster/relations
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/disaster/relations
● 参数说明
表 5-65 参数说明
名称 参 是否必选 说明
数
类
型
project_id Stri 是 租户在某一region下的project ID。
ng 获取方法请参见获取项目ID/名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 222
云数据库 GaussDB
API 参考 5 历史 API
名称 参 是否必选 说明
数
类
型
instance_nam Stri 否 实例名称，可查询过滤两端实例。
e ng
limit Int 否 查询记录数。为空时，默认为100。最
ege 小值为1，最大值为100。
r
offset Int 否 索引位置，偏移量。从第一条数据偏移
ege offset条数据后开始查询，默认为0（偏
r 移0条数据，表示从第一条数据开始查
询），必须为数字，不能为负数。
请求示例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/4a52a8a8f63d4c6d966dff0e20b69738/disaster/relations?
limit=&offset=0&instance_name=test
请求消息
无
响应消息
表 5-66 响应 Body 参数列表
名称 参数类型 说明
total Integer 总记录数。
relations Array of Object 容灾关系详情。
表 5-67 relations 字段数据结构说明
名称 参数类型 说明
disaster_type String 容灾类型。
枚举值:
● stream
name String 容灾任务名称。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 223
云数据库 GaussDB
API 参考 5 历史 API
名称 参数类型 说明
disaster_role String 容灾角色。
枚举值:
● disaster
● master
created String 创建时间，格式为“yyyy-mm-dd
hh:mm:ss”。
updated String 更新时间，格式为“yyyy-mm-dd
hh:mm:ss”。
slave_region_in Object 备region实例信息。
stance_info
master_region_i Object 主region实例信息。
nstance_info
synchronization String 容灾关系唯一id。
_id
id String 容灾记录id。
instance_id String 当前region实例id。
status String 容灾记录状态。
表 5-68 region_instance_info 字段数据结构说明
名称 参数类型 说明
instance_id String 实例id。
instance_name String 实例名称。
project_id String 实例项目id。
project_name String 实例项目名称。
region String 实例所属region。
instance_statu String 实例状态。
s
action Array of String 实例当前正在执行的action列表。
● 正常响应样例
{
"total": 1,
"relations": [
{
"name": "DR-task-0962",
"created": "2022-06-16 09:39:51",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 224
云数据库 GaussDB
API 参考 5 历史 API
"updated": "2022-06-16 09:44:55",
"id": "30b74120-4b50-495d-8174-7eeddf7feac5",
"status": "normal",
"disaster_type": "stream",
"disaster_role": "disaster",
"slave_region_instance_info": {
"region": "sa-fb-1",
"action": [
"STREAM_DISASTER_RELATION_SLAVE_TAG"
],
"instance_id": "d1060faf0d3743dd8830b39e7423bc9ain14",
"instance_name": "hly-0609-02",
"project_id": "4a52a8a8f63d4c6d966dff0e20b69738",
"project_name": "sa-fb-1_GaussDB",
"instance_status": "normal"
},
"master_region_instance_info": {
"region": "sa-fb-1",
"action": [
"STREAM_DISASTER_RELATION_MASTER_TAG"
],
"instance_id": "54d4b9fb131745fcba32cb90a05cabb8in14",
"instance_name": "hly-0609-01",
"project_id": "4a52a8a8f63d4c6d966dff0e20b69738",
"project_name": "sa-fb-1_GaussDB",
"instance_status": "normal"
},
"synchronization_id": "81da4032-1402-4b3e-b0e0-54c2f234a842",
"instance_id": "d1060faf0d3743dd8830b39e7423bc9ain14"
}
]
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
200
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.5 搭建容灾关系
功能介绍
搭建容灾关系。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
从主实例端下发。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 225
云数据库 GaussDB
API 参考 5 历史 API
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/construct
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
9089bbf7377442daa55bc28d514c08bdin14/disaster/construct
● 参数说明
表 5-69 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 5-70 参数说明
名称 是否必选 参数类型 说明
disaster_construc 是 Array of 搭建容灾请求参数
t_list Object
表 5-71 disaster_construct_list 参数结构说明
名称 是否必选 参数类型 说明
disaster_type 是 String 容灾类型。
slave_region 是 String 备region。
slave_project_id 是 String 备端项目id。
slave_instance_id 是 String 备实例id。
– 请求示例
{
"disaster_construct_list":[
{
"disaster_type":"stream",
"slave_region":"sa-fb-1",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 226
云数据库 GaussDB
API 参考 5 历史 API
"slave_project_id":"4a52a8a8f63d4c6d966dff0e20b69738",
"slave_instance_id":"54d4b9fb131745fcba32cb90a05cabb8in14"
}
]
}
响应消息
表 5-72 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
synchronizatio String 容灾关系唯一id。
n_id
● 正常响应样例
{
"master_job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7",
"slave_job_id":"f88479d2-e2af-4585-a0b8-6e66966d7484",
"synchronization_id":"2d03c2d1-e113-4784-9581-6b66d038817d"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.6 备实例容灾升主
功能介绍
容灾升主（failover），灾备实例端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 227
云数据库 GaussDB
API 参考 5 历史 API
约束限制
在灾备region下发。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.2/{project_id}/instances/{instance_id}/
failover
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.2/0483b6b16e954cb88930a360d2c4e663/instances/
c04c789b6baa4b6dbcc139c5226f3a2cin14/failover
● 参数说明
表 5-73 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
表 5-74 参数说明
名称 是否必选 参数类型 说明
is_support_restore 否 Boolean 是否支持容灾回切(仅支持数
据库版本大于等于3.200)
● true支持
false不支持(默认false)
● 正常响应样例
{
"is_support_restore": true
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 228
云数据库 GaussDB
API 参考 5 历史 API
响应消息
表 5-75 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"8bf0175e-562e-45f6-942a-2e2c72c577d7"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.7 解除容灾关系
功能介绍
解除容灾关系，从容灾主实例端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
约束限制
从容灾主region端下发。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/relations/{synchronization_id}/release
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
c04c789b6baa4b6dbcc139c5226f3a2cin14/disaster/relations/2d03c2d1-
e113-4784-9581-6b66d038817d/release
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 229
云数据库 GaussDB
API 参考 5 历史 API
● 参数说明
表 5-76 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
synchronization 是 容灾关系唯一id。
_id
请求消息
● 参数说明
无
响应消息
表 5-77 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
"slave_job_id":"e5d837c9-161d-44ca-8cd2-a302409a5ee5"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 230
云数据库 GaussDB
API 参考 5 历史 API
5.3.8 灾备实例主从切换
功能介绍
灾备实例主从切换（switchover），可在主备任意一端下发。
● 调用接口前，您需要提前获取终端节点，即下文中的Endpoint值。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/relations/{synchronization_id}/switchover
● URI样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/disaster/relations/e4b98979-5d3b-4805-
a804-47158bcec818/switchover
● 参数说明
表 5-78 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
synchronization 是 容灾关系唯一id。
_id
请求消息
● 参数说明
无
响应消息
表 5-79 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 231
云数据库 GaussDB
API 参考 5 历史 API
"slave_job_id":"8c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.9 重建容灾关系
功能介绍
● 流容灾备升主选择支持容灾回切，实现容灾关系的重建任务。
● 仅支持数据库版本大于等于3.200.。
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster/relations/{synchronization_id}/restore
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster/relations/e4b98979-5d3b-4805-a804-47158bcec818/restore
● 参数说明
表 5-80 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
synchronization 是 容灾关系唯一id。
_id
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 232
云数据库 GaussDB
API 参考 5 历史 API
请求消息
● 参数说明
无
响应消息
表 5-81 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
"slave_job_id":"8c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.10 开启容灾演练
功能介绍
● 灾备实例开始容灾演练。
● 仅支持数据库版本大于等于3.200的实例
URI
● URI格式
POST
https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/disaster-
simulation/start
● URL样例
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 233
云数据库 GaussDB
API 参考 5 历史 API
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-simulation/start
● 参数说明
表 5-82 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 5-83 参数说明
名称 是否必选 参数类型 说明
xlog_keep_ratio 否 Integer 灾备实例该字段不生效，主
实例默认10：
● 日志保留空间占可使用
剩余磁盘容量的比例, 可
设置范围为1-99。
– 请求示例
{
"xlog_keep_ratio":50
}
响应消息
表 5-84 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
"slave_job_id":"8c242441-fdcc-404f-ba78-f7856aed3edf"
}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 234
云数据库 GaussDB
API 参考 5 历史 API
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.11 结束容灾演练
功能介绍
● 灾备实例结束容灾演练。
● 仅支持数据库版本大于等于3.200的实例
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3.1/{project_id}/instances/{instance_id}/
disaster-simulation/stop
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/gaussdb/
v3.1/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in14/
disaster-simulation/stop
● 参数说明
表 5-85 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
无
● 请求示例
{}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 235
云数据库 GaussDB
API 参考 5 历史 API
响应消息
表 5-86 响应 Body 参数列表
名称 参数类型 说明
master_job_id String 主端任务id。
slave_job_id String 备端任务id。
● 正常响应样例
{
"master_job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf",
"slave_job_id":"8c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.12 开启日志保持
功能介绍
● 主实例开始容灾日志保持。
● 仅支持数据库版本大于等于3.200的实例
URI
● URI格式
POST
https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/disaster-data-
cache/start
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/disaster-data-cache/start
● 参数说明
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 236
云数据库 GaussDB
API 参考 5 历史 API
表 5-87 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
表 5-88 参数说明
名称 是否必选 参数类型 说明
xlog_keep_ratio 否 Integer 灾备实例该字段不生效，主
实例默认10：
● 日志保留空间占可使用
剩余磁盘容量的比例, 可
设置范围为1-99。
– 请求示例
{
"xlog_keep_ratio":50
}
响应消息
表 5-89 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 237
云数据库 GaussDB
API 参考 5 历史 API
● 异常
请参见状态码。
错误码
请参见错误码。
5.3.13 结束日志保持
功能介绍
● 主实例结束容灾日志保持。
● 仅支持数据库版本大于等于3.200的实例
URI
● URI格式
POST https://{Endpoint}/gaussdb/v3/{project_id}/instances/{instance_id}/disaster-
data-cache/stop
● URL样例
https://gaussdb.sa-fb-2.hcsglobal.com/
gaussdb/v3/0483b6b16e954cb88930a360d2c4e663/instances/
dsfae23fsfdsae3435in14/disaster-data-cache/stop
● 参数说明
表 5-90 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的project ID。
获取方法请参见获取项目ID/名称。
instance_id 是 实例ID。
请求消息
● 参数说明
无
● 请求示例
{}
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 238
云数据库 GaussDB
API 参考 5 历史 API
响应消息
表 5-91 响应 Body 参数列表
名称 参数类型 说明
job_id String 任务id。
● 正常响应样例
{
"job_id":"9c242441-fdcc-404f-ba78-f7856aed3edf"
}
● 异常响应
请参见异常请求结果。
状态码
● 正常
202
● 异常
请参见状态码。
错误码
请参见错误码。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 239
云数据库 GaussDB
API 参考 6 附录
6 附录
6.1 异常请求结果
异常响应要素说明
表 6-1 异常响应要素说明
名称 参数类型 说明
error_code String 提交任务异常时返回的错误编码。
error_msg String 提交任务异常时返回的错误描述信息。
响应样例
{
"error_code": "DBS.200022",
"error_msg": "实例名称已存在。"
}
6.2 状态码
状态码如表6-2所示：
表 6-2 状态码
状态码 编码 错误码说明
100 Continue 继续请求。
这个临时响应用来通知客户端，它的部分请求已经
被服务器接收，且仍未被拒绝。
101 Switching 切换协议。只能切换到更高级的协议。
Protocols 例如，切换到HTTP的新版本协议。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 240
云数据库 GaussDB
API 参考 6 附录
状态码 编码 错误码说明
200 OK 请求成功。
201 Created 创建类的请求完全成功。
202 Accepted 已经接受请求，但未处理完成。
203 Non- 非授权信息，请求成功。
Authoritative
Information
204 NoContent 请求完全成功，同时HTTP响应不包含响应体。
在响应OPTIONS方法的HTTP请求时返回此状态
码。
205 Reset Content 重置内容，服务器处理成功。
206 Partial Content 服务器成功处理了部分GET请求。
300 Multiple Choices 多种选择。请求的资源可包括多个位置，相应可返
回一个资源特征与地址的列表用于用户终端（例
如：浏览器）选择。
301 Moved 永久移动，请求的资源已被永久的移动到新的
Permanently URI，返回信息会包括新的URI。
302 Found 资源被临时移动。
303 See Other 查看其它地址。
使用GET和POST请求查看。
304 Not Modified 所请求的资源未修改，服务器返回此状态码时，不
会返回任何资源。
305 Use Proxy 所请求的资源必须通过代理访问。
306 Unused 已经被废弃的HTTP状态码。
400 BadRequest 非法请求。
建议直接修改该请求，不要重试该请求。
401 Unauthorized 在客户端提供认证信息后，返回该状态码，表明服
务端指出客户端所提供的认证信息不正确或非法。
402 Payment 保留请求。
Required
403 Forbidden 请求被拒绝访问。
返回该状态码，表明请求能够到达服务端，且服务
端能够理解用户请求，但是拒绝做更多的事情，因
为该请求被设置为拒绝访问，建议直接修改该请
求，不要重试该请求。
404 NotFound 所请求的资源不存在。
建议直接修改该请求，不要重试该请求。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 241
云数据库 GaussDB
API 参考 6 附录
状态码 编码 错误码说明
405 MethodNotAllow 请求中带有该资源不支持的方法。
ed 建议直接修改该请求，不要重试该请求。
406 Not Acceptable 服务器无法根据客户端请求的内容特性完成请求。
407 Proxy 请求要求代理的身份认证，与401类似，但请求者
Authentication 应当使用代理进行授权。
Required
408 Request Time-out 服务器等候请求时发生超时。
客户端可以随时再次提交该请求而无需进行任何更
改。
409 Conflict 服务器在完成请求时发生冲突。
返回该状态码，表明客户端尝试创建的资源已经存
在，或者由于冲突请求的更新操作不能被完成。
410 Gone 客户端请求的资源已经不存在。
返回该状态码，表明请求的资源已被永久删除。
411 Length Required 服务器无法处理客户端发送的不带Content-Length
的请求信息。
412 Precondition 未满足前提条件，服务器未满足请求者在请求中设
Failed 置的其中一个前提条件。
413 Request Entity 由于请求的实体过大，服务器无法处理，因此拒绝
Too Large 请求。为防止客户端的连续请求，服务器可能会关
闭连接。如果只是服务器暂时无法处理，则会包含
一个Retry-After的响应信息。
414 Request-URI Too 请求的URI过长（URI通常为网址），服务器无法处
Large 理。
415 Unsupported 服务器无法处理请求附带的媒体格式。
Media Type
416 Requested range 客户端请求的范围无效。
not satisfiable
417 Expectation 服务器无法满足Expect的请求头信息。
Failed
422 UnprocessableEnt 请求格式正确，但是由于含有语义错误，无法响
ity 应。
429 TooManyRequest 表明请求超出了客户端访问频率的限制或者服务端
s 接收到多于它能处理的请求。建议客户端读取相应
的Retry-After首部，然后等待该首部指出的时间后
再重试。
500 InternalServerErr 表明服务端能被请求访问到，但是不能理解用户的
or 请求。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 242
云数据库 GaussDB
API 参考 6 附录
状态码 编码 错误码说明
501 Not Implemented 服务器不支持请求的功能，无法完成请求。
502 Bad Gateway 充当网关或代理的服务器，从远端服务器接收到了
一个无效的请求。
503 ServiceUnavailabl 被请求的服务无效。
e 建议直接修改该请求，不要重试该请求。
504 ServerTimeout 请求在给定的时间内无法完成。客户端仅在为请求
指定超时（Timeout）参数时会得到该响应。
505 HTTP Version not 服务器不支持请求的HTTP协议的版本，无法完成
supported 处理。
6.3 错误码
错误码列表：
表 6-3 错误码列表
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 Parameter error. 参数错误。 检查传入的参数或URL是否全
0001 部正确。
400 DBS.20 Parameter error. 参数错误。 检查传入的参数或URL是否全
0004 部正确。
400 DBS.20 The request is 请求为空，请 请输入请求参数后重试。
0006 null. Enter a 输入请求参
request 数。
parameter.
400 DBS.20 Invalid DB 实例名非法。 请参考对应实例名的参数说
0021 instance name. 明输入符合要求的实例名后
重试。
400 DBS.20 Storage space is 卷大小超出允 检查磁盘大小的值是否正
0023 out of range. 许范围。 确。
400 DBS.20 Invalid region. Region非法。 请输入正确的 Region ID。
0024
400 DBS.20 Invalid AZ. 可用区取值非 检查可用区的参数是否正
0025 法。 确，可用区是否存在。
400 DBS.20 Invalid storage 卷类型非法。 检查磁盘的类型是否正确，
0026 type. 是否符合要求。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 243
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 Storage space 卷大小不是10 检查磁盘大小是否是10的倍
0027 must be a 的整数倍。 数。
multiple of 10.
400 DBS.20 The DB engine 不支持的数据 检查数据库引擎或版本是否
0040 or version is not 库类型或版 支持。
supported. 本。
400 DBS.20 Invalid database 数据库版本非 检查数据库的版本号是否支
0041 version. 法。 持。
400 DBS.20 The DB engine 不支持的数据 检查数据库类型或版本是否
0042 does not exist. 库类型或版 正确。
本。
400 DBS.20 Invalid HA同步模式非 检查同步模式是否正确。
0043 synchronize 法。
model.
400 DBS.20 Invalid VPC ID. VPC id非法。 检查VPC id是否正确。
0048
400 DBS.20 Invalid subnet 子网的网络id 检查子网ID是否正确。
0049 ID. 非法。
400 DBS.20 Invalid HA 不合法的ha模 检查HA模式是否正确。
0051 mode. 式。
400 DBS.20 Invalid database 数据库root密 检查数据库root密码是否符合
0052 root password. 码非法。 要求。
400 DBS.20 The selected 所选规格不存 检查所选规格是否正确。
0053 specifications 在。
do not exist.
400 DBS.20 Invalid 所选规格非 检查规格码是否正确，规格
0054 specifications. 法。 在当前可用区是否存在，规
格是否支持。
400 DBS.20 The maximum 节点个数达到 检查节点个数是否已达到最
0056 number of 最大值。 大值。
nodes has been
reached.
400 DBS.20 Invalid cluster 集群模式非 检查集群模式是否合法。
0063 mode. 法。
400 DBS.20 This is a weak 这是一个弱密 请参考对应的密码参数说
0068 password. 码，请输入一 明，输入符合密码复杂度要
Please enter a 个强度大一些 求，且强度更高的密码。
strong 的密码.
password.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 244
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 The DB instance 实例或节点非 检查实例或节点状态。
0076 and node must 正常状态。
be in the
Available state.
400 DBS.20 This operation is 实例状态不允 检查实例的状态或实例正在
0086 not allowed by 许做该操作。 进行的操作是否与请求冲
the DB instance 突。
status.
400 DBS.20 The number of 单个实例标签 检查实例标签数量是否达到
0087 tags added for 数量达到最大 了最大配额。
the DB instance 配额。
has reached the
quota.
400 DBS.20 The tag already 该资源标签已 检查标签是否已存在。
0098 exists. 存在。
400 DBS.20 The engine 该引擎版本不 检查该引擎版本是否高于
0175 version is not 支持设置切换 1.2.2。
permitted to 策略。
enable force
switch.
400 DBS.20 Failed to query 查询实例失 检查查询的实例是否存在或
0203 the DB instance. 败。 重试。
400 DBS.20 Storage space 卷大小不是10 检查磁盘大小是否是10的倍
0302 must be a 的整数倍。 数。
multiple of 10.
400 DBS.20 The scale-up 扩容次数达到 检查扩容次数是否达到最大
0303 times have 最大限制。 限制。
reached the
maximum
value.
400 DBS.20 The new 扩容参数不合 检查扩容参数是否合法。
0306 storage space 法。
must be greater
than or equal to
the original
storage space.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 245
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 The new 备机扩容后的 检查备机扩容后的大小是否
0308 storage space 大小不能超过 超过了主机。
after scaling up 主机。
cannot be
greater than
that of the
primary DB
instance.
400 DBS.20 Parameter error. 参数错误 检查传入的参数或URL是否全
0405 部正确。
400 DBS.20 The parameter 参数值超出范 检查参数值是否超出范围。
0461 value is out of 围。
range.
400 DBS.20 New password 新密码不能与 检查新旧密码是否符合要
0475 should not 旧密码相同。 求。
equal to the old
ones.
400 DBS.20 Invalid database 数据库版本非 检查数据库的版本号是否支
0504 version. 法。 持。
400 DBS.20 Invalid KMS key 密钥非法。 检查密钥是否正确。
0506 ID.
400 DBS.20 The KMS key is 密钥失效或已 检查密钥是否正确。
0507 invalid or has 删除。
been deleted.
400 DBS.20 The job does 任务不存在。 检查任务是否正确。
0543 not exist.
400 DBS.20 The database 数据库不存 检查数据库名称是否合法。
0823 does not exist. 在。
400 DBS.20 The database 数据库帐号不 检查数据库用户名称是否合
0824 account does 存在。 法。
not exist.
400 DBS.20 Modifying 不允许在只读 请确认权限后操作。
0825 permission is 实例上执行修
not allowed on 改权限操作。
read replicas.
400 DBS.20 Agent async 调用agent异步 请检查agent连接是否正常。
0943 requet failed. 请求失败。
400 DBS.20 The backup 备份类型不存 检查备份类型。
1004 type does not 在。
exist.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 246
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 This operation is 实例状态不允 检查实例的状态或实例正在
1014 not allowed by 许做该操作。 进行的操作是否与请求冲
the DB instance 突。
status.
409 DBS.20 Another 该实例正在进 该实例正在进行其它操作，
1015 operation is 行其它操作， 无法执行该操作，请稍后重
being 无法执行该操 试。
performed on 作，请稍后重
the DB instance. 试。
400 DBS.20 The restoration 恢复任务不存 该实例没有相关恢复任务或
1019 task does not 在. 者不需要进行恢复后的数据
exist. 确认。
400 DBS.20 The database 输入的数据库 检查数据库名是否正确。
1035 name must be 名重复或者输
different from 入的数据库名
the original and 与目标库上的
target database 重复。
names.
400 DBS.20 Invalid backup 备份周期非 检查备份周期是否正确，是
1101 cycle. 法。 否符合要求。
400 DBS.20 Invalid backup 备份开始时间 检查备份开始时间是否符合
1103 start time. 非法。 要求，备份开始时间和备份
结束时间的关系是否正确。
400 DBS.20 Invalid retention 保留天数非 检查保留天数是否合法。
1106 days. 法。
400 DBS.20 The backup file 备份文件不存 检查该备份是否存在，备份
1203 does not exist. 在。 是否匹配实例。
400 DBS.20 The DB engine 不支持的数据 检查数据库引擎或版本是否
1207 or version is not 库类型或版 支持。
supported. 本。
400 DBS.20 The operation is 备份状态不允 请明确具体操作约束，按照
1208 not allowed by 许。 约束进行操作。
the backup
status.
400 DBS.20 Invalid backup 备份名非法。 检查备份名称是否合法。
1210 name.
400 DBS.21 Incorrect 参数组配额错 检查参数组配额是否正确。
2002 parameter 误。
group quota.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 247
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.21 Operation not 不支持此操 检查实例的状态或实例正在
2003 allowed. 作。 进行的操作是否与请求冲
突。
400 DBS.21 Parameter 参数组更新错 检查参数是否正确。
2004 group update 误。
error.
400 DBS.21 The node does 节点不属于 检查节点及所属组是否正
2005 not belong to 组。 确。
the group.
400 DBS.21 The DB engine 引擎不存在。 检查数据库引擎是否正确。
2007 does not exist.
400 DBS.21 The DB engine 不支持的引 检查数据库引擎是否支持。
2008 is not 擎。
supported.
400 DBS.21 Task processing 任务处理失 稍后请重试，或联系技术支
2009 failed. 败。 持。
400 DBS.21 The parameter 绑定正在执 稍后请重试。
2010 group is being 行。
applied.
400 DBS.21 Application 绑定失败。 重新绑定或联系技术支持。
2011 failed.
400 DBS.21 The parameter 参数不存在。 检查参数是否正确。
2012 does not exist.
400 DBS.21 The node does 节点没有默认 检查默认参数组。
2014 not have a 参数组。
default
parameter
group.
400 DBS.21 Partial success. 部分成功。 检查任务部分失败原因或联
2015 系技术支持。
400 DBS.21 Parameter 参数更新失 检查参数是否正确。
2016 update failed. 败。
400 DBS.21 Invalid 参数非法。 检查参数是否正确。
2017 parameter.
400 DBS.21 Update failed. 更新失败。 检查更新失败原因或联系技
2025 术支持。
400 DBS.21 The parameter 参数组名已存 检查参数是否正确。
2030 template name 在。
already exists.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 248
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.21 The parameter 参数模板已被 检查参数模板是否正确。
2032 template has 应用。
been applied.
400 DBS.21 Parameters are 参数设置不正 检查参数设置是否正确。
2037 incorrectly set. 确。
400 DBS.21 Insufficient 内部资源配额 检查内部资源配额。
6028 internal 不足。
resource quota.
400 DBS.21 The queried 操作节点不属 检查操作节点信息是否正
6030 node does not 于该实例。 确。
belong to the
current
instance.
400 DBS.28 Parameter error. 参数错误。 检查参数是否正确。
0001
500 DBS.28 Server failure. 服务器错误。 请联系客服管理员或者稍后
0005 重试。
400 DBS.28 The request is 请求为空，请 检查请求参数是否正确。
0006 null. Enter a 输入请求参
request 数。
parameter.
400 DBS.28 Invalid backup 备份文件id非 检查备份文件id是否合法
0124 file id 法
400 DBS.28 Invalid backup 备份描述不合 检查备份描述是否合法。
0127 description. 法。
400 DBS.28 The database 请检查数据库 检查数据库名称是否正确。
0128 information of 名，确认所填
the DB instance 数据库名信
is not found. 息，找不到该
Check the 实例的数据库
database name 信息。
to see whether
the instance
database
information
exists.
400 DBS.28 This is a weak 这是一个弱密 请参考对应的密码参数说
0203 password. 码，请输入一 明，输入符合密码复杂度要
Please enter a 个强度大一些 求，且强度更高的密码。
strong 的密码.
password.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 249
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 Invalid 输入参数不合 检查参数是否正确。
0204 parameter. 法。
400 DBS.28 Invalid retention 保留天数非 检查保留天数是否合法。
0214 days. 法。
400 DBS.28 Invalid backup 备份周期非 检查备份周期是否合法。
0215 cycle. 法。
400 DBS.28 Invalid backup 备份开始时间 检查备份开始时间是否合
0216 start time. 非法。 法。
400 DBS.28 Invalid DB 实例名非法。 检查实例名称是否合法。
0234 instance name.
400 DBS.28 Invalid database 数据库类型非 检查数据库类型是否正确。
0235 type. 法
400 DBS.28 Invalid database 数据库版本非 检查数据库版本是否正确。
0236 version. 法。
400 DBS.28 Datastore not Datastore为 检查Datastore是否合法。
0237 specified. 空。
400 DBS.28 The DB engine 不支持的数据 检查数据库引擎或版本是否
0238 or version is not 库类型或版 支持。
supported. 本。
400 DBS.28 Invalid 所选规格非 检查所选规格是否正确。
0239 specifications. 法。
400 DBS.28 Invalid storage 卷类型非法。 检查磁盘的类型是否正确，
0241 type. 是否符合要求。
400 DBS.28 Storage space is 卷大小超出允 检查磁盘大小的值是否正
0242 out of range. 许范围。 确。
400 DBS.28 The region or Region或可用 请输入正确的 Region ID或可
0244 AZ does not 区不存在 用区。
exist.
400 DBS.28 Invalid database 数据库root密 检查数据库root密码是否符合
0246 root password 码非法。 要求。
400 DBS.28 Invalid backup 备份保留天数 检查保留天数是否合法。
0250 retention days. 非法。
400 DBS.28 Invalid backup 备份周期不合 检查备份周期是否符合要
0251 cycle. 法。 求。
400 DBS.28 Invalid backup 备份开始时间 检查备份开始时间是否符合
0253 start time. 非法。 要求，备份开始时间和备份
结束时间的关系是否正确。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 250
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 The parameter 参数不存在。 检查参数是否正确。
0270 does not exist.
400 DBS.28 The parameter 参数值超出范 检查参数是否正确。
0271 value is out of 围。
range.
400 DBS.28 The tag key 新增标签存在 请检查请求参数中的标签键
0272 must be unique. 重复的键值。 值。
400 DBS.28 Invalid object 对象名称非 检查对象名称是否合法。
0277 name. 法。
400 DBS.28 Invalid AZ. 可用区取值非 检查可用区的参数是正确，
0285 法。 可用区是否存在。
400 DBS.28 Invalid 规格非法。 检查规格是否合法。
0288 FlavorRef.
400 DBS.28 Invalid storage 存储空间大小 检查存储空间大小是否合
0311 space size. 非法。 法。
400 DBS.28 Invalid storage 硬盘信息不合 检查硬盘信息是否合法。
0325 information. 法。
400 DBS.28 Invalid cluster 集群模式非 检查集群模式是否合法。
0342 mode. 法。
400 DBS.28 Invalid database 数据库端口号 检查数据库端口号是否合
0364 port. 无效。 法。
400 DBS.28 Invalid billing 付款模式无 检查传入的付款模式是否正
0365 mode. 效。 确。
400 DBS.28 Invalid HA Ha模式非法。 检查HA模式是否合法。
0402 mode.
400 DBS.28 Invalid DB 实例ID或者节 检查实例ID是否合法。
0404 instance ID or 点ID非法。
node ID format.
400 DBS.28 Invalid node ID. 节点ID非法。 检查节点ID是否合法。
0407
400 DBS.28 Invalid backup 备份结束时间 检查备份结束时间是否合
0416 end time. 非法。 法。
400 DBS.28 Invalid backup 备份时间非 检查备份回见是否合法。
0417 time. 法。
400 DBS.28 Invalid 不合法的企业 检查企业项目ID是否符合要
0433 enterprise 项目ID。 求。
project ID.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 251
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 Invalid 所选规格码非 检查规格码是否合法。
0434 specification 法。
code.
400 DBS.28 Invalid records. 无效的查询记 检查查询记录数是否合法。
0439 The number of 录数，请输入
records must be 小于等于100的
an integer less 正整数。
than or equal to
100.
400 DBS.28 Invalid offset, 无效的偏移 检查偏移量是否合法。
0440 please enter a 量，请输入非
non negative 负整数
integer.
400 DBS.28 Invalid time 不合法的time 检查时区参数是否填写正
0447 zone. zone。 确。
400 DBS.28 This operation 不能对冻结的 解冻该实例，再重试。
0449 cannot be 对象执行该操
performed 作。
because the
object is frozen.
400 DBS.28 Invalid time 无效的查询时 请输入正确的查询时间。
0472 range. 间。
400 DBS.28 Invalid 协调节点数量 检查协调节点数量是否合
0600 coordinator 非法。 法。
node quantity.
400 DBS.28 Invalid shard 分片数量非 检查分片数量是否合法。
0601 quantity. 法。
400 DBS.28 Invalid number 扩容分片数非 检查扩容分片数量是否合
0604 of added shards 法。 法。
for cluster
capacity
expansion.
400 DBS.28 Differential 差异备份周期 检查差异备份周期是否合
0618 backup cycle 无效。 法。
invalid.
400 DBS.28 Invalid replica 副本数非法。 检查副本数量是否合法。
0628 count.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 252
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 The database 数据库版本不 检查副本数量是否合法，或
0629 version does not 支持2副本实 者修改为支持的数据库版
support two- 例。 本，再重试。
replica
instances.
400 DBS.28 Two-replica 2副本实例只支 检查2副本实例可用区是否合
0630 instances can 持单可用区。 法。
only be
deployed within
a single AZ.
400 DBS.28 Invalid database 数据库名非 检查数据库名称是否合法。
0631 name. 法。
400 DBS.28 Invalid schema. 数据库模式非 检查数据库模式是否合法
0632 法。
400 DBS.28 Invalid source 源Node Group 检查源Node Group是否合
0633 node group. 非法。 法。
400 DBS.28 Invalid target 目标Node 检查目标Node Group是否合
0634 node group. Group非法。 法。
400 DBS.28 Invalid Solution Solution非法。 检查solution参数是否填写正
0635 确。
400 DBS.29 Parameter error. 参数错误。 检查传入的参数或URL是否全
0000 部正确，是否符合要求。
400 DBS.29 Parameter error. 参数错误。 检查参数是否填写正确。
0001
403 DBS.20 The DB instance 实例ID和用户 检查实例ID或用户ID是否正
0010 ID or user ID ID可能为空， 确，或者检查访问权限。
may be null, or 或者操作越
the operation is 权。
not authorized.
403 DBS.20 Resource not 访问资源不存 修改资源ID或者检查访问权
0044 found or 在，或者无访 限。
permission 问权限。
denied.
403 DBS.20 No permission 没有设置切换 检查是否有设置切换策略参
0174 to enable force 策略参数的权 数的权限。
switch. 限。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 253
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
403 DBS.20 The DB instance 实例ID和用户 检查实例ID或用户ID是否正
0604 ID or user ID ID可能为空， 确，获取检查访问权限。
may be null, or 或者操作越
the operation is 权。
not authorized.
403 DBS.20 You are not 不能在只读实 检查只读实例操作限制。
0810 allowed to 例创建数据
create 库。
databases on
read replicas.
403 DBS.20 You are not 不能在只读实 检查只读实例操作限制。
0819 allowed to 例执行删除数
delete database 据库用户。
users on read
replicas.
403 DBS.28 The account is 账户受限。 检查帐号是否权限不足。
0020 restricted.
400 DBS.28 This operation is 集群状态受 检查集群状态是否正常。
0800 not allowed by 限，操作不允
the cluster 许执行。
status.
400 DBS.28 This operation is 1.X内核版本不 检查操作实例内核版本，如
0804 not allowed for 支持对主备版 要必要需要升级内核版本。
primary/standby 实例进行操
instances with 作。
kernel version
1.x
400 DBS.28 The component 组件ID必须是 检查组件ID状态，不允许传
0828 ID must be the 备DN。 入主DN组件ID。
standby DN ID.
403 DBS.20 Resource not 访问资源不存 修改资源ID或者检查访问权
1003 found or 在，或者无访 限
permission 问权限。
denied.
403 DBS.28 Resource not 访问资源不存 修改资源ID或者检查访问权
0015 found or 在，或者无访 限
permission 问权限。
denied.
403 DBS.28 Invalid token. Token非法。 请检查token是否正确，或者
0056 重新获取token后再试
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 254
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
404 DBS.20 The DB instance 实例不存在。 检查租户是否拥有该实例，
0002 does not exist. 实例名或实例ID是否正确，
实例是否存在。
404 DBS.20 The ECS 请检查数据 检查实例虚拟机是否正常。
0008 information of 库，确认实例
the DB instance 的虚拟机信
cannot be 息，找不到该
found. 实例的虚拟机
信息。
404 DBS.20 The original DB 源实例不存 检查源实例是否存在。
0013 instance does 在。
not exist.
404 DBS.20 The DB instance 实例不存在。 查租户是否拥有该实例，实
0045 does not exist. 例名或实例ID是否正确，实
例是否存在。
404 DBS.20 The security 安全组不存 检查安全组是否正确。
0050 group does not 在，或不属于
exist or does 该VPC。
not belong to
the VPC.
404 DBS.20 The DB instance 实例异常，无 检查实例或节点状态。
0408 abnormal, no 正常节点。
normal nodes.
404 DBS.20 The region or Region或可用 请输入正确的 Region ID或可
0470 AZ does not 区不存在。 用区。
exist.
404 DBS.20 The subnet does 子网不存在， 检查子网是否正确。
0501 not exist or 或不属于该
does not belong VPC。
to the VPC.
404 DBS.20 The VPC does VPC不存在， 检查VPC是否正确。
0503 not exist or 或不属于该用
does not belong 户。
to the user.
404 DBS.20 The DB instance 该实例不存 查租户是否拥有该实例，实
0602 does not exist. 在。 例名或实例ID是否正确，实
例是否存在。
404 DBS.20 The backup file 备份文件不存 检查该备份是否存在，备份
1010 does not exist. 在。 是否匹配实例。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 255
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
404 DBS.20 The DB instance 实例不存在或 查租户是否拥有该实例，实
1028 does not exist. 已删除。 例名或实例ID是否正确，实
例是否存在。
404 DBS.21 The parameter 参数组不存 检查参数组是否存在。
2001 group does not 在。
exist.
404 DBS.21 The object does 对象不存在。 请确定操作的对象存在。
2013 not exist.
404 DBS.29 The selected 所选规格不存 检查所选规格是否正确。
0002 specifications 在。
do not exist.
404 DBS.29 The DB instance 该实例不存 检查租户是否拥有该实例，
0005 does not exist. 在。 实例名或实例ID是否正确，
实例是否存在。
404 DBS.29 The DB instance 实例不存在。 检查租户是否拥有该实例，
0011 does not exist. 实例名或实例ID是否正确，
实例是否存在。
404 DBS.29 Resource not 未找到资源。 检查入参是否正确，实例是
0013 found. 否存在。
409 DBS.20 Another 该实例正在进 检查实例的状态或实例正在
0011 operation is 行其它操作或 进行的操作是否与请求冲
being 该实例故障， 突。
performed on 无法执行该操
the DB instance 作，请稍后重
or the DB 试。
instance is
faulty.
409 DBS.20 This operation 该操作与当前正在 检查实例的状态或实例正在
conflicts with the 运行的任务是冲突
0019 currently running 的，请自行排查。 进行的操作是否与请求冲
task, please 突。
troubleshoot by
yourself.
409 DBS.20 The DB instance 实例名称已存 请输入一个与已存在的实例
0022 name already 在。 不相同的实例名。
exists.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 256
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
409 DBS.20 Another 该实例正在进 检查实例的状态或实例正在
0047 operation is 行其它操作或 进行的操作是否与请求冲
being 该实例故障， 突。
performed on 无法执行该操
the DB instance 作，请稍后重
or the DB 试。
instance is
faulty.
409 DBS.20 This operation 当前实例状态 检查实例存储空间是否已
0316 cannot be 为存储空间 满。
performed 满，不能进行
because the DB 该操作。
instance status
is Storage full.
409 DBS.20 Invalid 操作不合法。 检查请求是否合法。
0402 operation.
409 DBS.20 The database 数据库名称已 检查数据库名称是否合法。
0826 name already 存在。
exists.
409 DBS.20 The database 帐号名称已存 检查数据库用户是否合法。
0827 user already 在。
exists.
409 DBS.20 Built-in 数据库内置帐 检查用户操作权限。
0828 database 号，用户不可
accounts cannot 操作。
be edited.
409 DBS.20 The backup 备份名称已存 请确定操作的对象是否存
1201 name already 在。 在。
exists.
409 DBS.20 Another 该实例正在进 检查实例的状态或实例正在
1202 operation is 行其它操作或 进行的操作是否与请求冲
being 该实例故障， 突。
performed on 无法执行该操
the DB instance 作，请稍后重
or the DB 试。
instance is
faulty.
409 DBS.20 Backup is in 正在备份中， 等待备份完成后，再重试。
1205 progress, please 请稍等。
wait.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 257
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
409 DBS.21 Another 该实例正在进 检查实例的状态或实例正在
2006 operation is 行其它操作或 进行的操作是否与请求冲
being 该实例故障， 突。
performed on 无法执行该操
the DB instance 作，请稍后重
or the DB 试。
instance is
faulty.
409 DBS.21 Failed to 无法更改数据 检查实例的状态或实例正在
2033 change 库实例的参数 进行的操作是否与请求冲
parameter 组值，因为当 突。
template values 前正在操作数
because the DB 据库实例。
instance is
currently being
operated.
409 DBS.28 This operation 实例当前状态 检查实例的状态是否正常或
0011 cannot be 异常或已删 者该实例是否已经被删除
performed 除，不允许做 了。
because the DB 该操作。
instance is
abnormal or
has been
deleted.
409 DBS.28 Operation not 实例类型或状 检查实例的状态或实例正在
0406 allowed by the 态受限，操作 进行的操作是否与请求冲
DB instance 不允许。 突。
type or status.
413 DBS.20 The number of 实例数量达到 检查配额。
0046 DB instances 配额。
has reached the
quota.
413 DBS.29 The number of 实例数量达到 检查配额。
0003 DB instances 配额。
has reached the
quota.
422 DBS.21 The parameter 参数错误。 检查参数是否正确。
2019 cannot be
processed.
500 DBS.10 Server failure. 服务器错误。 请联系客服管理员或者稍后
8000 重试。
500 DBS.10 Server failure. 服务器错误。 请联系客服管理员或者稍后
8002 重试。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 258
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
500 DBS.10 Server failure. 服务器错误。 请联系客服管理员或者稍后
8005 重试。
500 DBS.20 Server failure. 服务器错误。 请联系客服管理员或者稍后
0005 重试。
500 DBS.20 Server failure. 服务器错误。 请联系客服管理员或者稍后
0208 重试。
500 DBS.20 Failed to create 创建数据库失 检查失败原因或联系技术支
0811 the database. 败。 持。
500 DBS.20 Failed to modify 修改数据库用 检查用户权限。
0821 database user 户权限失败。
permissions.
500 DBS.21 Failed to 请求处理失 请联系客服管理员或者稍后
3002 process the 败。 重试。
request.
500 DBS.21 Failed to 请求处理失 请联系客服管理员或者稍后
3004 process the 败。 重试。
request.
500 DBS.28 The DB instance 实例状态异 请联系客户服务，或者稍后
0106 status is 常。 再试。
abnormal.
Please contact
customer
service or try
again later.
500 DBS.29 Failed to 请求处理失 请联系客服管理员或者稍后
0006 process the 败。 重试。
request.
500 DBS.29 Failed to 请求处理失 请联系客服管理员或者稍后
0015 process the 败。 重试。
request.
400 DBS.28 Storage space 卷大小不是10 检查磁盘大小是否是10的倍
0266 must be a 的整数倍。 数。
multiple of 10.
400 DBS.28 Storage space 所选磁盘容量 检查磁盘大小是否符合要
0611 must be a 大小必须为 求。
common 40GB和分片数
multiple of 的公倍数。
40GB and the
number of
shards.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 259
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 Storage space 所选磁盘容量 检查磁盘大小是否符合要
0612 excess max limit 大于当前分片 求。
for current 数支持的最大
shard number. 值。
400 DBS.28 Invalid region. Region非法。 请输入正确的 Region ID。
0243
400 DBS.20 The subnet does 子网不存在， 请输入正确的子网后重试。
0505 not exist or 或不属于该
does not belong vpc。
to the VPC.
404 DBS.20 The security 安全组不存 请输入正确的安全组后重
0502 group does not 在，或不属于 试。
exist or does 该VPC。
not belong to
the VPC.
400 DBS.20 Invalid retention 保留天数非 检查保留天数是否合法。
0065 days. 法。
400 DBS.28 Invalid HA Ha一致性非 检查Ha一致性是否合法。
0602 consistency. 法。
400 DBS.28 Invalid Ha同步模式非 检查Ha模式是否合法。
0262 synchronize 法。
model.
400 DBS.20 Invalid 实例参数组的 请输入正确的实例参数组ID
0057 parameter ID取值非法。 后重试。
template ID.
404 DBS.20 The parameter 参数组不存 检查参数组是否存在。
0058 template does 在。
not exist.
400 DBS.20 Invalid database 数据库端口号 检查数据库端口号是否合
0059 port. 无效。 法。
400 DBS.28 The Ha instance 主备版实例不 主备版实例不支持设置并行
0654 is not supported 支持取消并行 恢复，请按照API文档在请求
to cancel 恢复。 体中取消设置并行恢复。
parallel restore.
400 DBS.28 Please use 请使用数据节 检查数据节点规格是否正
0613 specifications of 点的规格。 确。
data nodes.
404 DBS.20 Resource not 未找到资源。 检查资源后重试。
0355 found.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 260
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.20 Invalid billing 付款模式无 检查付款模式是否合法。
0061 mode. 效。
400 DBS.20 The backup file 不是手动备份 选择手动备份文件进行操
1218 is not manual. 文件。 作。
404 DBS.28 The DB instance 实例不存在或 查租户是否拥有该实例，实
0022 does not exist. 已删除。 例名或实例ID是否正确，实
例是否存在。
400 DBS.28 Invalid project project id 非 检查project id是否合法。
0408 id. 法。
400 DBS.28 Exceeding the 超过单次数据 检查单次数据节点扩容数量
0607 upper limit of 节点扩容数量 是否达到上限。
data nodes 的上限。
number in a
single expand
request.
400 DBS.20 The available IP 所选子网可用 请输入正确可用的子网后重
0082 addresses in the IP不足。 试。
selected subnet
are insufficient.
400 DBS.28 Expanding 暂不支持同时 检查扩容约束后重试。
0606 coordinator 扩容协调节点
nodes and data 和数据节点。
nodes at the
same time is
not supported
currently.
400 DBS.28 Exceeding the 超过单次协调 检查单次协调节点扩容数量
0608 upper limit of 节点扩容数量 是否达到上限。
coordinator 的上限。
nodes number
in a single
expand request.
400 DBS.28 Expand cluster 扩容集群请求 检查扩容规范后重试。
0609 request must 至少要包含一
contains at least 种要扩容的节
one node type 点。
to expand.
400 DBS.30 The backup file 备份文件状态 检查该备份文件的状态。
1024 is not normal. 异常。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 261
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
500 DBS.30 Failed to submit 提交订单失 检查订单提交状态。
1028 the order. 败。联系管理
Contact the 员。
administrator.
400 DBS.28 Failed to create 创建数据库 检查输入schema参数然后重
0651 all DB schemas. SCHEMA全部 试。
失败。
400 DBS.28 Failed to create 创建数据库 检查输入schema参数然后重
0652 some DB SCHEMA部分 试。
schemas. 失败。
400 DBS.20 Incorrect 用户名或密码 检查输入输入用户名与密码
0029 username or 参数错误。 然后重试。
password
parameter.
400 DBS.28 Database name 未输入数据库 请输入数据库名称。
0132 not entered. 名称。
400 DBS.28 Illegal instance 非法的实例规 请根据当前实例检查传入的
0661 specification, 格，该规格不 规格参数。
which does not 存在或与实例
exist or does 不匹配。
not match the
instance
400 DBS.28 DR relationship 容灾主集群和 请检查容主备实例是否已经
0626 established 灾备集群已存 存在灾关系。
between 在容灾关系。
primary and DR
instances.
400 DBS.28 The DR 容灾关系记录 请检查容灾关系是否存在。
0638 relationship 不存在。
does not exist.
400 DBS.28 Submit an 白名单不支持 请检查跨region调用组件是否
0803 application to 容灾跨region 部署，并且特性白名单
call the API for 接口。 gaussdb_feature_supportDis
cross-region DR. asterApiGlobal处于开启状
态。
400 DBS.28 Cross-region DR 跨region操作 请检查目前region的project
0806 operation failed. 失败。 id是否合法。
400 DBS.28 Invalid shard 分片组件id非 请检查组件ID是否合法。
0667 component ID. 法。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 262
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 Component IDs 存在同组DN分 请检查批量DN主备倒换时，
0668 are from the 片异常。 多个组件ID是否来自不同组
same shard. 分片。
400 DBS.28 The component 组件id不属于 请检查DN主备倒换时，组件
0676 ID does not 当前节点id。 ID是否属于对应的节点ID。
belong to the
current node ID.
400 DBS.20 Failed to 修改密码失 请检查传入的密码是否正
0478 change the 败。 确。
password.
400 DBS.20 Invalid database 数据库用户名 请输入正确的数据库用户
0062 username. 非法。 名。
400 DBS.28 Invalid database 数据库模板非 请输入正确的模板名称。
0653 template. Use 法，建议使用
the template0. template0数据
库模板。
400 DBS.28 Invalid cluster 无效集群一致 请检查集群一致性协议。
0640 consensus 性协议，请检
protocol, please 查数据库版本
check database 与一致性协
version and 议。
consistency
protocol.
400 DBS.20 The database 数据库版本不 请检查实例数据库版本是否
0856 version is not 支持。 支持该操作。
supported.
400 DBS.28 Remain 资源校验未通 请检查源是否充足。
0822 resource 过。
verification
failed.
400 DBS.20 Invalid retention 保留天数非 请输入正确的保留天数。
0064 days. 法。
400 DBS.30 An AZ that does 存在不支持 请确认所选择的az是否全部
1009 not support IPv6的可用 支持IPv6。
IPv6 exists. 区。
400 DBS.30 Selected 所选规格不支 请确认当前规格是否支持
1010 specifications 持IPv6。 IPv6。
do not support
IPv6.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 263
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.30 XBSA 缺失XBSA配置 请配置XBSA配置信息。
0111 configuration 信息。
information is
missing.
400 DBS.30 ca_cert_pem is a “ca_cert_pem 请输入正确的ca_cert_pem。
0112 required field. ”字段不能为
空。
400 DBS.30 client_key is a “client_key 请输入正确的client_key。
0113 required field. ”字段不能为
空。
400 DBS.30 client_crt is a “client_crt ” 请输入正确的client_crt。
0114 required field. 字段不能为
空。
400 DBS.30 rand_pass is a “rand_pass 请输入正确的rand_pass。
0115 required field. ”字段不能为
空。
400 DBS.30 Nodes has 所有节点或者 请确定实例或者节点的状态
1132 shutdown. 实例已经处于 正常。
停止状态。
400 DBS.20 The node 备份时实例的 请选择与当前节点拓扑一致
0480 topology of the 节点拓扑结构 的备份。
selected DB 与当前实例不
instance must 一致。
be the same as
that of the
original DB
instance.
400 DBS.06 Instance status 实例状态无 请检查当前的实例状态。
010001 is invalid. 效。
400 DBS.06 The IPv6 status 所选vpc的ipv6 对于多VPC场景，需要选择的
013041 of the selected 开启状态不一 VPC子网IPv6开启状态保持一
VPCs is 致。 致。
inconsistent.
400 DBS.06 An operation 与当前操作冲 请检查当前实例是否正在进
020003 that conflicts 突的操作正在 行其他操作。
with the current 进行中。
operation is in
progress.
400 DBS.06 The instance is 实例状态不满 检查实例状态。
020104 abnormal. 足。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 264
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 The instance is 容灾状态不满 检查当前实例的容灾状态。
020105 abnormal. 足。
400 DBS.06 Agent agent 调用异 请联系客服管理员或者稍后
020108 invocation 常 重试。
exception.
400 DBS.06 Peer-region 跨region 请联系客服管理员或者稍后
020109 verification preCheck校验 重试。
failed. 不通过。
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020110 synchronization 量同步中，请
in progress for 在无容灾状态
the primary 时执行该操
instance. Select 作。
an instance
without a DR
relationship as
primary
instance.
400 DBS.06 Incremental 主实例处于增 检查当前实例的容灾状态。
020111 synchronization 量同步中，请
in progress for 在无容灾状态
the primary 时执行该操
instance. Select 作。
an instance
without a DR
relationship as
primary
instance.
400 DBS.06 Incremental 主实例处于全 检查当前实例的容灾状态。
020112 synchronization 量同步失败，
in progress for 请在无容灾状
the primary 态时执行该操
instance. Select 作。
an instance
without a DR
relationship as
primary
instance.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 265
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 主实例处于增 检查当前实例的容灾状态。
020113 synchronization 量同步失败，
failed for the 请在无容灾状
primary 态时执行该操
instance. Select 作。
an instance
without a DR
relationship as
primary
instance.
400 DBS.06 Switchover in 主备切换中， 检查当前实例的容灾状态。
020114 progress for the 请在无容灾状
primary or DR 态时执行该操
instance. Select 作。
an instance
without a DR
relationship.
400 DBS.06 Switchover 主备切换失 检查当前实例的容灾状态。
020115 failed for the 败，请在无容
primary or DR 灾状态时执行
instance. Select 该操作。
an instance
without a DR
relationship.
400 DBS.06 Incremental 灾备实例处于 检查当前实例的容灾状态。
020116 restoration in 全量恢复中，
progress for the 请在无容灾状
DR instance. 态时执行该操
Select an 作。
instance
without a DR
relationship as
DR instance.
400 DBS.06 Incremental 灾备实例处于 检查当前实例的容灾状态。
020117 restoration 全量恢复失
failed for the 败，请在无容
DR instance. 灾状态时执行
Select an 该操作。
instance
without a DR
relationship as
DR instance.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 266
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 灾备实例处于 检查当前实例的容灾状态。
020118 restoration in 增量恢复中，
progress for the 请在无容灾状
DR instance. 态时执行该操
Select an 作。
instance
without a DR
relationship as
DR instance.
400 DBS.06 Incremental 灾备实例处于 检查当前实例的容灾状态。
020119 restoration 增量恢复失
failed for the 败，请在无容
DR instance. 灾状态时执行
Select an 该操作。
instance
without a DR
relationship as
DR instance.
400 DBS.06 Promotion to 灾备实例处于 检查当前实例的容灾状态。
020120 primary in 升主中，请在
progress for the 无容灾状态时
DR instance. 执行该操作。
Select an
instance
without a DR
relationship as
DR instance.
400 DBS.06 Promotion to 灾备实例处于 检查当前实例的容灾状态。
020121 primary failed 升主失败，请
for the DR 在无容灾状态
instance. Select 时执行该操
an instance 作。
without a DR
relationship as
DR instance.
400 DBS.06 No DR 灾备实例处于 检查当前实例的容灾状态。
020122 relationship 无容灾状态，
established for 请在增量恢复
the DR instance. 中或增量恢复
Perform this 失败时执行该
operation when 操作。
incremental
restoration is in
progress or
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 267
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Switchover in 灾备实例处于 检查当前实例的容灾状态。
020123 progress for the 主备切换中，
DR instance. 请在增量恢复
Perform this 中或增量恢复
operation when 失败时执行该
incremental 操作。
restoration is in
progress or
failed.
400 DBS.06 Switchover 灾备实例处于 检查当前实例的容灾状态。
020124 failed for the 主备切换失
DR instance. 败，请在增量
Perform this 恢复中或增量
operation when 恢复失败时执
incremental 行该操作。
restoration is in
progress or
failed.
400 DBS.06 Full restoration 灾备实例处于 检查当前实例的容灾状
020125 in progress for 全量恢复中， 态。。
the DR instance. 请在增量恢复
Perform this 中或增量恢复
operation when 失败时执行该
incremental 操作。
restoration is in
progress or
failed.
400 DBS.06 Full restoration 灾备实例处于 检查当前实例的容灾状态。
020126 failed for the 全量恢复失
DR instance. 败，请在增量
Perform this 恢复中或增量
operation when 恢复失败时执
incremental 行该操作。
restoration is in
progress or
failed.
400 DBS.06 Promotion to 灾备实例处于 检查当前实例的容灾状态。
020127 primary in 升主中，请在
progress for the 增量恢复中或
DR instance. 增量恢复失败
Perform this 时执行该操
operation when 作。
incremental
restoration is in
progress or
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 268
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Promotion to 灾备实例处于 检查当前实例的容灾状态。
020128 primary failed 升主失败，请
for the DR 在增量恢复中
instance. 或恢复同步失
Perform this 败时执行该操
operation when 作。
incremental
restoration is in
progress or
failed.
400 DBS.06 No DR 无容灾该状态 检查当前实例的容灾状态。
020129 relationship 中，请在增量
established for 同步中执行该
the instance. 操作。
Perform this
operation when
incremental
synchronization
is in progress.
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020130 synchronization 量同步中，请
in progress for 在增量同步中
the primary 执行该操作。
instance.
Perform this
operation when
incremental
synchronization
is in progress.
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020131 synchronization 量复制失败，
failed for the 请在增量同步
primary 中执行该操
instance. 作。
Perform this
operation when
incremental
synchronization
is in progress.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 269
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 主实例增量同 检查当前实例的容灾状态。
020132 synchronization 步失败，请在
failed for the 增量同步中执
primary 行该操作。
instance.
Perform this
operation when
incremental
synchronization
is in progress.
400 DBS.06 Switchover is in 主备切换中， 检查当前实例的容灾状态。
020133 progress. 请在增量同步
Perform this 中执行该操
operation when 作。
incremental
synchronization
is in progress.
400 DBS.06 Switchover 主备切换失 检查当前实例的容灾状态。
020134 failed. Perform 败，请在增量
this operation 同步中执行该
when 操作。
incremental
synchronization
is in progress.
400 DBS.06 Full restoration 灾备实例全量 检查当前实例的容灾状态。
020135 in progress for 恢复中，请在
the DR instance. 增量恢复中执
Perform this 行该操作。
operation when
incremental
restoration is in
progress.
400 DBS.06 Full restoration 灾备实例全量 检查当前实例的容灾状态。
020136 failed for the 恢复失败，请
DR instance. 在增量恢复中
Perform this 执行该操作。
operation when
incremental
restoration is in
progress.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 270
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 灾备实例增量 检查当前实例的容灾状态。
020137 synchronization 同步失败，请
failed for the 在增量恢复中
DR instance. 执行该操作。
Perform this
operation when
incremental
restoration is in
progress.
400 DBS.06 Promotion to 灾备实例升主 检查当前实例的容灾状态。
020138 primary in 中，请在增量
progress for the 恢复中执行该
DR instance. 操作。
Perform this
operation when
incremental
restoration is in
progress.
400 DBS.06 Promotion to 灾备实例升主 检查当前实例的容灾状态。
020139 primary failed 失败，请在增
for the DR 量恢复中执行
instance. 该操作。
Perform this
operation when
incremental
restoration is in
progress.
400 DBS.06 No DR 主实例处于无 检查当前实例的容灾状态。
020140 relationship 容灾状态，请
established for 在增量同步中
the primary 或增量同步失
instance. 败时执行该操
Perform this 作。
operation when
incremental
synchronization
is in progress or
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 271
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020141 synchronization 量同步中，请
in progress for 在增量同步中
the primary 或增量同步失
instance. 败时执行该操
Perform this 作。
operation when
incremental
synchronization
is in progress or
failed.
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020143 synchronization 量同步失败，
failed for the 请在增量同步
primary 中或增量同步
instance. 失败时执行该
Perform this 操作。
operation when
incremental
synchronization
is in progress or
failed.
400 DBS.06 Switchover in 主实例处于主 检查当前实例的容灾状态。
020144 progress for the 备切换中，请
primary 在增量同步中
instance. 或增量同步失
Perform this 败时执行该操
operation when 作。
incremental
synchronization
is in progress or
failed.
400 DBS.06 Switchover 主实例处于主 检查当前实例的容灾状态。
020145 failed for the 备切换失败，
primary 请在增量同步
instance. 中或增量同步
Perform this 失败时执行该
operation when 操作。
incremental
synchronization
is in progress or
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 272
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Full 主实例处于全 检查当前实例的容灾状态。
020146 synchronization 量同步中，请
in progress for 在无容灾状态
the primary 或主实例全量
instance. 复制失败时执
Perform this 行该操作。
operation when
there is no DR
relationship or
full
synchronization
failed.
400 DBS.06 Incremental 主实例处于增 检查当前实例的容灾状态。
020147 synchronization 量同步中，请
in progress for 在无容灾状态
the primary 或主实例全量
instance. 复制失败时执
Perform this 行该操作。
operation when
there is no DR
relationship or
full
synchronization
failed.
400 DBS.06 Incremental 主实例增量同 检查当前实例的容灾状态。
020148 synchronization 步失败，请在
failed for the 无容灾状态或
primary 实例全量复制
instance. 失败执行该操
Perform this 作。
operation when
there is no DR
relationship or
full
synchronization
failed.
400 DBS.06 Switchover in 主备切换中， 检查当前实例的容灾状态。
020149 progress. 请在无容灾状
Perform this 态或实例全量
operation when 复制失败执行
there is no DR 该操作。
relationship or
full
synchronization
failed.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 273
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Switchover 主备切换失 检查当前实例的容灾状态。
020150 failed. Perform 败，请在无容
this operation 灾状态或主实
when there is 例全量复制失
no DR 败时执行该操
relationship or 作。
full
synchronization
failed.
400 DBS.06 Full restoration 灾备实例处于 检查当前实例的容灾状态。
020151 in progress for 全量恢复中，
the DR instance. 请在无容灾状
Select an 态时执行该操
instance 作。
without a DR
relationship as
DR instance.
400 DBS.06 Incremental 灾备实例增量 检查当前实例的容灾状态。
020152 restoration in 恢复中，请在
progress for the 无容灾状态时
primary 执行该操作。
instance.
Perform this
operation when
there is no DR
relationship.
400 DBS.06 Incremental 灾备实例增量 检查当前实例的容灾状态。
020153 restoration 恢复失败，请
failed for the 在无容灾状态
DR instance. 时执行该操
Perform this 作。
operation when
there is no DR
relationship.
400 DBS.06 Promotion to 灾备实例升主 检查当前实例的容灾状态。
020154 primary in 中，请在无容
progress for the 灾状态时执行
DR instance. 该操作。
Perform this
operation when
there is no DR
relationship.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 274
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Promotion to 灾备实例升主 检查当前实例的容灾状态。
020155 primary failed 失败，请在无
for the DR 容灾状态时执
instance. 行该操作。
Perform this
operation when
there is no DR
relationship.
400 DBS.06 This operation 主备切换中， 检查当前实例的容灾状态。
020156 cannot be 不支持当前操
performed 作。
because there is
a switchover in
progress for the
primary
instance.
400 DBS.06 This operation 主备切换失 检查当前实例的容灾状态。
020157 cannot be 败，不支持当
performed 前操作。
because a
switchover
failed.
400 DBS.06 This operation 灾备实例全量 检查当前实例的容灾状态。
020158 cannot be 恢复中，不支
performed 持当前操作。
because there is
a full
restoration for
the DR instance.
400 DBS.06 This operation 灾备实例升主 检查当前实例的容灾状态。
020159 cannot be 中，不支持当
performed 前操作。
because the DR
instance is
being promoted
to primary.
400 DBS.06 This operation 灾备实例升主 检查当前实例的容灾状态。
020160 cannot be 中，不支持当
performed 前操作。
because the DR
instance failed
to be promoted
to primary.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 275
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 Incremental 主实例处于增 主实例处于增量同步失败，
020175 synchronization 量同步失败， 请在增量同步中执行该操
failed for the 请在增量同步 作。
primary 中执行该操
instance. 作。
Perform this
operation when
incremental
synchronization
is in progress.
400 DBS.06 Switchover 灾备实例处于 灾备实例处于主备切换失
020177 failed for the 主备切换失 败，请在增量恢复中执行该
DR instance. 败，请在增量 操作。
Perform this 恢复中执行该
operation when 操作。
incremental
restoration is in
progress.
400 DBS.06 Incremental 灾备实例处于 灾备实例处于增量恢复失
020180 restoration 增量恢复失 败，请在增量恢复中执行该
failed for the 败，请在增量 操作。
DR instance. 恢复中执行该
Perform this 操作。
operation when
incremental
restoration is in
progress.
400 DBS.06 The xlog_keep_radi xlog_keep_radio字段非法
020161 xlog_keep_radio o字段非法
field is invalid.
400 DBS.06 This operation is 不支持此容灾 不支持此容灾操作。
020162 not supported. 操作。
400 DBS.06 This feature is 此功能特性未 此功能特性未启用，请在运
280105 not enabled. 启用。 维管理平台开启相关特性白
名单。
400 DBS.06 This operation is dorado一致性 dorado一致性组id不支持当
010012 not allowed in 组状态不允许 前的操作，请检查一致性态
the current 当前操作。 状态。
status of the
Dorado
consistency
group.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 276
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.28 The database 单副本实例当 请升级实例至数据库最新版
0662 version of 前版本不支持 本。
Single-replica 该操作
instances does
not support this
operation.
400 DBS.06 One or more 创建SCHEMA 请检查SCHEMA是否重复 或
280102 schemas failed 部分失败或者 者 不合规
to be created. 多个全部失败
400 DBS.06 The new 新密码不能与 请输入符合要求的新密码
280006 password must 旧密码相同或
be different 相反
from the old
password or the
old password in
reverse order.
400 DBS.06 One or more 授权数据库账 请检查授权账户及权限是否
280103 database 户失败或者多 正确
accounts failed 个全部失败
to be
authorized.
400 DBS.06 Invalid encoding 创建数据库时 请指定有效的编码格式
280051 format. 指定的编码格
式无效
400 DBS.06 The LC_CTYPE 创建数据库时 请指定有效的LC_CTYPE 或
280052 and 指定的 LC_COLLATE 参数值
LC_COLLATE LC_CTYPE和
values are LC_COLLATE值
invalid. 无效
400 DBS.06 The schema SCHEMA已存 请输入新SCHEMA
280008 already exists. 在
400 DBS.06 Parameter error: 调用接口时填 请重新填写为正确的参数。
010013 $ 写的参数错
{parameterNam 误。
e}/$
{parameterValu
e}
400 DBS.20 Invalid node 实例节点角色 请检查节点角色 或者 节点状
0075 role. 无效。 态是否正常。
400 DBS.06 The schema SCHEMA不存 请输入有效的SCHEMA
280007 does not exist. 在
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 277
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.21 Permission 没有权限。 检查账号是否权限不足。
6003 denied.
400 DBS.06 Table not found. 表不存在。 检查表是否不存在。
280009
400 DBS.06 Table already 表已存在。 检查表是否已存在。
280010 exists.
400 DBS.06 Maximum 库表数量超过 检查库表的数量是否超过最
280013 number of 最大限制。 大限制。
databases or
tables exceeded.
400 DBS.06 Inconsistent 库表信息不一 检查每个库表数据，参数是
280016 database or 致。 否一致。
table
information in
the parameter.
400 DBS.06 Invalid backup 备份类别非 检查备份类别是否正确。
280017 type. 法。
400 DBS.06 The new 新库名非法。 检查新库名是否不合规。
280018 database name
is invalid.
400 DBS.06 The new 新SCHEMA非 检查新SCHEMA是否不合
280019 schema name is 法。 规。
invalid.
400 DBS.06 The new table 新表名非法。 检查新表名是否不合规。
280020 name is invalid.
400 DBS.06 The backup file 备份文件和备 检查备份文件和备份类别是
280023 does not match 份类别不匹 否匹配。
the backup 配。
type.
400 DBS.06 New OS does 备份恢复到新 检查原实例操作系统是否匹
280032 not match 实例，操作系 配。
original 统不匹配。
instance.
400 DBS.06 The selected 资源类型：$ 检查当前资源类型是否支持
280033 deployment {resourceType} 创建该形态的实例。
model of the $ ，暂不支持创
{resourceType} 建该部署形态
type cannot be 的实例。
created.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 278
云数据库 GaussDB
API 参考 6 附录
状 错误码 错误信息 描述 处理措施
态
码
400 DBS.06 This method is 当前单节点实 检查单节点实例升级约束。
280034 not available for 例版本不支持
single-node 该升级操作。
instances
version..
400 DBS.06 The current 当前引擎版本 检查创建实例选择的数据库
013044 engine version 不支持创建 版本是否支持IPv6。
does not IPv6实例。
support IPv6
instance
creation.
400 DBS.06 kms type not 不支持当前 检查当前使用的KMS主密钥
280031 support. KMS密钥加密 是否为SM4/AES。
类型
400 DBS.20 Instance not 当前实例不支 检查当前实例状态。
0960 support kms- 持下发透明加
tde. 密。
400 DBS.21 Invalid engine 当前引擎不支 检查当前实例的引擎版本。
6045 version. 持下发该操
作。
400 DBS.20 The storage 新实例卷大小 请检查原实例和目前实例磁
0073 space of the 不得小于旧实 盘大小 。
new DB 例卷大小。
instance cannot
be less than
that of the
original DB
instance.
400 DBS.06 No nodes 实例不存在正 请检查原实例节点状态。
010015 available for 常的节点。
this instance.
400 DBS.06 Kernel status 内核状态已经 请检查实例状态和任务流状
010016 changed not 变更，不支持 态。
support 清理资源。
resource
cleaning.
400 DBS.06 Failed to obtain 获取实例磁盘 检查获取磁盘信息的远程接
010018 the instance 信息失败。 口是否调用成功或者磁盘信
volume 息处理是否出现异常。
information.
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 279
云数据库 GaussDB
API 参考 6 附录
6.4 获取项目 ID/名称
操作场景
在调用接口的时候，部分URL中需要填入项目编号，所以需要获取到项目编号。获取
方式如下：
步骤1 使用浏览器，以VDC管理员或VDC业务员帐号登录ManageOne。
非B2B场景登录地址：https://ManageOne运营面的访问地址。例如，https://
console.demo.com。
B2B场景登录地址：https://ManageOne租户面的访问地址。例如，https://
tenant.demo.com。
步骤2 在页面右上角单击用户图标，在下拉列表中选择“个人设置”。
步骤3 在资源空间列表中获取对应区域的ID，即项目ID（project_id）。
同时可获取资源空间名称，即项目名称。
----结束
6.5 获取终端节点
获取 GaussDB 服务的终端节点
GaussDB服务的Endpoint信息由服务名、Region ID、外部域名三部分组成，格式为：
{service_name}.{region0_id}.{external_global_domain_name}
其中{service_name}、{region0_id}和{external_global_domain_name}的获取方式
具体如下：
● {service_name}：服务名缩写，不区分大小写，例如gaussdb。
● {region0_id}：请在安装时导出的汇总文件《xxx__export_all_CN.xlsm》的“1.2
基本参数”页签中查找region0_id。
● {external_global_domain_name}：请在安装时导出的汇总文件
《xxx__export_all_CN.xlsm》的“1.2基本参数”页签中查找
external_global_domain_name。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 280
云数据库 GaussDB
API 参考 6 附录
说明
调用GaussDB API前，首先需要在本地计算机上进行如下的hosts配置：
{apigw_float_ip} {service_name}.{region0_id}.{external_global_domain_name}
● {apigw_float_ip} ： 在底座安装安装工程导出汇总文件《xxx__export_all_CN.xlsm》的
“2.1 工具生成的ip参数”页签中查找参数名为AGW-LB-Float-IP对应的IP地址。
● {service_name}：服务名缩写，不区分大小写，例如gaussdb。
● {region0_id}：请在安装时导出的汇总文件《xxx__export_all_CN.xlsm》的“1.2基本参数”
页签中查找region0_id。
● {external_global_domain_name}：请在安装时导出的汇总文件
《xxx__export_all_CN.xlsm》的“1.2基本参数”页签中查找
external_global_domain_name。
示例：
172.202.2.10 gaussdb.sa-fb-1.songshanghu-x86-1.com
获取 IAM 服务的终端节点
IAM服务的终端节点在DBS运维管理平台的“配置管理 > 系统参数管理”页签搜索
“iamEndpoint”获取，截取“https://”后的值。例如：
iam-cache-proxy.sa-fb-1.songshanghu-x86-1.com:26335
说明
调用接口获取Token前，首先需要在本地计算机上进行如下的hosts配置：
{mo_float_ip} {iam_url}
● {mo_float_ip}: 在底座安装安装工程导出汇总文件《xxx__export_all_CN.xlsm》的“2.1 工具
生成的ip参数”页签中查找参数名为ManageOne-Tenant-Float-IP对应的IP地址。在多个
region场景下，请查找当前提供Global服务的主region的底座安装工程。
● {iam_url}: 截取“iamEndpoint”参数值中“https://”与“:26335”之间的值。
样例值：
172.202.0.119 iam-cache-proxy.sa-fb-1.songshanghu-x86-1.com
6.6 ReplicationMode 列表
ReplicationMode列表
同步模式 描述 备注
sync 同步模式 -
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 281
云数据库 GaussDB
API 参考 6 附录
6.7 数据库实例规格
本章介绍GaussDB提供的实例性能规格。
表 6-4 实例性能规格
规格 规格编码 vCPU(个) 内存(GB)
鲲鹏通用 gaussdb.opengauss.ee.ld.2xlarg 8 64
型 e.arm8.ha
gaussdb.opengauss.ee.ld.4xlarg 16 128
e.arm8.ha
gaussdb.opengauss.ee.ld.8xlarg 32 256
e.arm8.ha
gaussdb.opengauss.ee.ld.15xlar 60 480
ge.arm8.ha
gaussdb.opengauss.ee.ld.20xlar 80 640
ge.arm8.ha
gaussdb.opengauss.ee.ld.2xlarg 8 64
e.arm8.co
gaussdb.opengauss.ee.ld.4xlarg 16 128
e.arm8.co
gaussdb.opengauss.ee.ld.8xlarg 32 256
e.arm8.co
gaussdb.opengauss.ee.ld.15xlar 60 480
ge.arm8.co
gaussdb.opengauss.ee.ld.20xlar 80 640
ge.arm8.co
裸金属服 gaussdb.opengauss.ee.bms.4xla 16 64
务器 rge.x864.ha
gaussdb.opengauss.ee.bms.8xla 32 128
rge.x864.ha
gaussdb.opengauss.ee.bms.16xl 64 256
arge.x864.ha
gaussdb.opengauss.ee.bms.24xl 96 256
arge.x863.ha
gaussdb.opengauss.ee.bms.24xl 96 512
arge.x865.ha
gaussdb.opengauss.ee.bms.24xl 96 768
arge.x868.ha
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 282
云数据库 GaussDB
API 参考 6 附录
规格 规格编码 vCPU(个) 内存(GB)
gaussdb.opengauss.ee.bms.24xl 96 1024
arge.x868.ha
gaussdb.opengauss.ee.bms.26xl 104 1024
arge.x868.ha
gaussdb.opengauss.ee.bms.32xl 128 512
arge.x864.ha
gaussdb.opengauss.ee.bms.32xl 128 768
arge.x866.ha
gaussdb.opengauss.ee.bms.64xl 256 1024
arge.x864.ha
gaussdb.opengauss.ee.bms.4xla 16 64
rge.x864.co
gaussdb.opengauss.ee.bms.8xla 32 128
rge.x864.co
gaussdb.opengauss.ee.bms.16xl 64 256
arge.x864.co
裸金属服 gaussdb.opengauss.ee.enh.bms 96 1024
务器（增 .24xlarge.x868.ha
强型网
关） gaussdb.opengauss.ee.enh.bms 104 1024
.26xlarge.x868.ha
通用增强 gaussdb.opengauss.ee.dn.m6.2 8 64
II型 xlarge.8.ha
说明
该规格不能用于生产环境。
gaussdb.opengauss.ee.c3.2xlarg 8 32
e.x864.ha
gaussdb.opengauss.ee.c3.4xlarg 16 64
e.x864.ha
gaussdb.opengauss.ee.dn.m6.4 16 128
xlarge.8.ha
gaussdb.opengauss.ee.c3.8xlarg 32 128
e.x864.ha
gaussdb.opengauss.ee.dn.m6.8 32 256
xlarge.8.ha
gaussdb.opengauss.ee.c3.16xlar 64 256
ge.x864.ha
gaussdb.opengauss.ee.dn.m6.1 64 512
6xlarge.8.ha
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 283
云数据库 GaussDB
API 参考 7 修订记录
7 修订记录
发布日期 更新特性
2023-03-30 第一次正式发布。
文档版本 01 (2023-10-30) 版权所有 © 华为云计算技术有限公司 284
提示：当前浏览效果与源文档相比展示样式存在少许差异，可直接下载文档进行浏览