4.1 实例管理
4.1.1 创建数据库实例
功能介绍
创建GaussDB(for openGauss)实例。GaussDB(for openGauss)支持创建分布式实 例。
● 调用接口前，您需要了解API 认证鉴权。
● 调用接口前，您需要提前获取到地区和终端节点，即下文中的Endpoint值。
调试
您可以在API Explorer中调试该接口。
URI
● URI格式
POST https://{Endpoint}/v3/{project_id}/instances
● URI样例
https://gaussdb-opengauss.cn-north-4.myhuaweicloud.com/
v3/054b61972980d4552f0bc00ac8d3f5cd/instances
● 参数说明
表4-1 参数说明
名称 是否必选 说明
project_id 是 租户在某一region下的
project ID。
获取方法请参见获取项 目ID。
请求消息
表4-2 参数说明
名称 是否必
选
参数类型 说明
name 是 String 实例名称。
用于表示实例的名称，同一租户下，同类型 的实例名可重名。
取值范围：4~64个字符之间，必须以字母 开头，区分大小写，可以包含字母、数字、
中划线或者下划线，不能包含其他的特殊字 符。
datastore 是 Object 数据库信息。
详情请参见表4-3。
ha 是 Object 实例部署形态。详情请参见表4-4。
configuration_i
d 否 String 参数模板ID。当不传该参数时，使用系统默
认的参数模板。
port 否 String 数据库对外开放的端口，不填默认为8000，
可选范围为：1024-39998。限制端口：
2378,2379,2380,4999,5000,5999,6000,600 1,8097,8098,12016,12017,20049,20050,21 731,21732,32122,32123,32124。
password 是 String 数据库密码。
GaussDB(for openGauss)密码取值范围:
非空； 至少包含大写字母（A-Z），小写字 母（a-z），数字（0-9），非字母数字字符
（限定为~!@#%^*-_=+?,）四类字符中的三 类字符；长度8~32个字符。
建议您输入高强度密码，以提高安全性，防 止出现密码被暴力破解等安全风险。
backup_strateg
y 否 Object 备份策略。
详情请参见表4-5。
名称 是否必 选
参数类型 说明
enterprise_proje
ct_id 否 String 企业项目ID。只有企业租户时该参数才生 效。
使用请参考《企业管理 API参考》的“查询 企业项目列表”响应消息表
“enterprise_project字段数据结构说明”的
“id”。
disk_encryption
_id 否 String 用于磁盘加密的密钥ID，默认为空。
flavor_ref 是 String 规格码，取值范围：非空。参考表7-4中 GaussDB(for openGauss)的“规格编码”
列内容获取。
volume 是 Object volume信息。
详情请参见表4-6。
region 是 String 区域ID。
取值范围：非空，请参见地区和终端节点。
availability_zon
e 是 String 可用区ID。
GaussDB(for openGauss)取值范围：非 空，可选部署在同一可用区或三个不同可用 区，可用区之间用逗号隔开。详见示例。
● 部署在同一可用区：需要输入三个相同
的可用区。例如：部署在“cn-north-4a”可用区，则需要在此处输入
"cn-north-4a,cn-north-4a,cn-north-4a"。
● 部署在三个不同可用区：需要分别输入 三个不同的可用区。
取值范围：非空，请参见地区和终端节点。
vpc_id 是 String 虚拟私有云ID，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界 面，在虚拟私有云的详情页面查找VPC ID。
● 方法2：通过虚拟私有云服务的API接口 查询，具体操作可参考查询VPC列表。
subnet_id 是 String 子网的网络ID信息，获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界 面，单击VPC下的子网，进入子网详情页 面，查找网络ID。
● 方法2：通过虚拟私有云服务的API接口 查询，具体操作可参考查询子网列表。
名称 是否必 选
参数类型 说明
security_group_
id 是 String 指定实例所属的安全组。如果不需要指定安
全组，请联系客服申请白名单。
● 方法1：登录虚拟私有云服务的控制台界 面，在安全组的详情页面查找安全组 ID。
● 方法2：通过虚拟私有云服务的API接口 查询，具体操作可参考查询安全组列 表。
charge_info 否 Object 计费类型信息，仅支持按需。
详情请参见表4-7。
time_zone 否 String UTC时区。
● 不选择时，GaussDB(for openGauss)国 内站默认为UTC时间。
● 选择填写时，取值范围为
UTC-12:00~UTC+12:00，且只支持整段 时间，如UTC+08:00，不支持UTC +08:30。
sharding_num 是 Integer 分片数量，取值范围1~9。
coordinator_nu
m 是 Integer 协调节点数量，取值范围1~9。CN数量必须
小于或等于两倍的分片数。
replica_num 否 Integer 实例副本数，支持取值2，3。不填默认为 3。
说明2副本选项仅针对特定用户开放，且仅支持1.3.0
及以上版本的实例。如需配置白名单权限，您可 以在管理控制台右上角，选择“工单 > 新建工 单”，提交开通白名单的申请。
enable_force_s
witch 否 Boolean enable_force_switch表示是否开启备机强升 主功能，仅支持取值true，false。true表示 开启备机强升主功能，false表示关闭，默认 关闭。仅支持1.2.2及以上版本。
说明
备机强升主功能适用场景：在主机发生故障后，
为了保障集群的可用性，强制拉起备机作为新主 机对外提供服务的场景。本功能在集群故障状态 下，以丢失部分数据为代价换取集群尽可能快的 恢复服务。本功能是集群状态为不可用时的一个 逃生方法，如果操作者不清楚备机强升后丢失数 据对业务的影响，请勿使用本功能。
表4-3 datastore 字段数据结构说明
名称 是
否 必 选
参数类型 说明
type 是 String 数据库引擎，取值如下：
GaussDB(for openGauss)。不区分大小 写。
version 否 String 数据库版本。不填时，默认为当前最新版 本。
GaussDB(for openGauss)支持如下版本：
● 1.1
● 1.2
● 1.3
● 1.4
表4-4 ha 字段数据结构说明
名称 是
否 必 选
参数类型 说明
mode 是 String GaussDB(for openGauss)为分布式模式取 值：enterprise(企业版) ，不区分大小写。
consistency 是 String 指定事务一致性类型，取值范围：strong
（强一致性） | eventual(最终一致性)，不 分区大小写。
replication_mode 是 String 备机同步参数。
取值：
GaussDB(for openGauss)为“sync"
说明
● “sync”为同步模式。
表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～732。该参数缺省时，默认 填写为7天。
表4-6 volume 字段数据结构说明
名称 是否
必选
参数类型 说明
type 是 String 磁盘类型。
仅支持ULTRAHIGH，区分大小写，表示 SSD盘及云磁盘。
size 是 Integer 磁盘大小。例如：该参数填写为“40”，
表示为创建的实例分配40GB的磁盘空间。
ECS部署方案：取值范围：（分片数
*40GB）~（分片数*16TB），且大小只能 为分片数*40的整数倍。
取值范围：（分片数*40GB）~（分片数
*16TB），且大小只能为分片数*40的整数 倍。
表4-7 chargeInfo 字段数据结构说明
名称 是
否 必 选
参数类型 说明
charge_mode 是 String 计费模式。支持postPaid，后付费，即按 需付费；perPaid，先付费，即包周期。
● 请求样例
创建GaussDB(for openGauss)企业版实例：
{ "name": "user1-v3-independent", "datastore": {
"type": "GaussDB(for openGauss)", "version": "1.3"
},
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", "volume": {
"type": "ULTRAHIGH", "size": 120
},
"disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab", "region": "cn-north-4",
"availability_zone": "cn-north-4a,cn-north-4a,cn-north-4a", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", "backup_strategy": {
"start_time": "17:00-18:00", "keep_days": 7
},
"charge_info": {
"charge_mode": "postPaid"
},
"password": "Gauss_234",
"configuration_id": "b000d7c91f1749da87315700793a11d4pr14", "enterprise_project_id": "",
"time_zone": "UTC+08:00", "ha":{
"mode":"enterprise", "consistency":"strong", "replication_mode":"sync"
},
"sharding_num": 1, "coordinator_num": 1, "replica_num": 3, "port":8000,
"enable_force_switch":true }
响应消息
● 正常响应要素说明
表4-8 要素说明
名称 参数类型 说明
instance Object 实例信息。
详情请参见表4-9。
job_id String 实例创建的任务id。
仅创建按需实例时会返回该参数。
表4-9 instance 说明
名称 参数类型 说明
id String 实例id。
name String 实例名称。用于表示实例的名称，同一
租户下，同类型的实例名称可相同。
取值范围：4~64个字符之间，必须以 字母开头，不区分大小写，可以包含字 母、数字、中划线或者下划线，不能包 含其他的特殊字符。
status String 实例状态。如BUILD，表示创建中。
仅创建按需实例时会返回该参数。
datastore Object 数据库信息。
详情请参见表4-10。
ha Object 数据库部署形态。
详情请参见表4-11。
replica_num Integer 实例副本数。
port String 数据库端口信息，与请求参数相同。
backup_strategy Object 自动备份策略。
详情请参见表4-12。
enterprise_project
_id String 项目标签。
flavor_ref String 规格码，取值范围：非空。参考表7-4 中GaussDB(for openGauss)的“规格 编码”列内容获取。
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。
表4-10 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎，返回值如下：
GaussDB(for openGauss) version String 数据库版本。
表4-11 ha 字段数据结构说明
名称 参数类型 说明
mode String GaussDB(for openGauss)为分布式模式，
取值：enterprise(企业版) ，不区分大小 写。
replication_
mode String 备机同步参数。
取值：
● GaussDB(for openGauss)为
“sync”。
说明
● “sync”为同步模式。
consistency String GaussDB(for openGauss)的预留参数：指 定事务一致性类型，取值范围：strong
（强一致性） | eventual(最终一致性)。
表4-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”。
表4-13 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
取值如下，区分大小写：
● ULTRAHIGH，表示SSD盘。
size Integer 磁盘大小。
GaussDB(for openGauss)分布式实例创 建时需指定大小：要求必须为（分片数 * 40GB）的倍数，取值范围：（分片数
*40GB）~（分片数*16TB）。
表4-14 chargeInfo 字段数据结构说明
名称 参数类型 说明
charge_mode String 创建类型，支持按需。
● 正常响应样例 }
GaussDB(for openGauss)企业版实例：
{ "instance": {
"id": "ad8cd1440aa94a02ae4580fcbebb3143in14", "name": "user1-v3-independent",
"status": "BUILD", "datastore": {
"type": "GaussDB(for openGauss)", "version": "1.1"
}, "ha": {
"mode": "Enterprise", "replication_mode": "sync", "consistency": "strong"
},
"port": "8000", "volume": {
"type": "ULTRAHIGH", "size": 120
},
"replica_num": 3, "region": "cn-north-4", "backup_strategy": {
"start_time": "17:00-18:00", "keep_days": 7
},
"flavor_ref": "gaussdb.opengauss.ee.dn.m6.2xlarge.8.in", "availability_zone": "cn-north-4a,cn-north-4a,cn-north-4a", "vpc_id": "1f011c32-2de2-4aa8-a161-9498dbcef329", "subnet_id": "54a44bec-e36f-441e-86bb-d749ace9c189", "security_group_id": "c6123999-8532-421c-9db6-e078013ff58f", "charge_info": {
"charge_mode": "postPaid"
} },
"job_id": "30f2790a-a5b6-4a13-a5ab-733c746609af"
}
● 异常响应
请参见异常请求结果。
状态码
请参见状态码。
错误码
请参见错误码。