文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>云数据库 MySQL>实践教程>使用 API 创建实例>云盘版单节点实例 API 创建指南

云盘版单节点实例 API 创建指南

最近更新时间：2026-06-26 11:49:05

我的收藏

本页目录：

云数据库 MySQL 提供多种创建 MySQL 实例的方法，您可通过控制台或者调用 API 接口进行实例的创建。本文旨在帮助您通过 API 快速购买云数据库 MySQL 云盘版单节点实例。相比于 控制台购买 方式，API 购买更适合需要自动化部署、批量创建的场景。

实例架构说明

本文为创建云盘版单节点实例的 API 操作说明，在控制台显示的实例架构为：单节点（云盘）标准型。

创建前准备

1. 确认账户信息

在开始购买前，请确保您已完成以下准备工作：
已注册腾讯云账号并完成实名认证。
账户余额充足。

2. 确定购买方式

腾讯云 MySQL 提供两种计费模式，购买前您可确认好需要的计费模式，以便后续在调用 API 接口时能对应参考配置：
计费模式
适用场景
API 接口
按量计费
测试环境、短期项目、业务波动较大
包年包月
生产环境、长期稳定业务、成本优先

创建流程指引

1. 了解售卖地域、可用区以及支持的磁盘类型

云盘版单节点实例（DeviceType = CLOUD_NATIVE_CLUSTER）当前支持以下地域和可用区。建议在调用对应接口创建实例前，先通过 DescribeDBZoneConfig 接口获取实时的可用区售卖配置，以确认：
目标可用区是否支持 CLOUD_NATIVE_CLUSTER。
支持的磁盘类型列表。
支持的 Memory/Volume 规格组合。
这样可以避免因配置变更导致的创建失败。
说明：
地域和可用区可能存在更新，且部分可用区可能额外支持 CLOUD_TSSD 磁盘类型。
CLOUD_HSSD：增强型 SSD 云硬盘。
CLOUD_SSD：SSD 云硬盘。
CLOUD_PREMIUM：高性能云硬盘。
CLOUD_TSSD：极速型 SSD 云硬盘。
地域
可用区
支持的磁盘类型
广州
ap-guangzhou-6
ap-guangzhou-7
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM
清远
ap-qingyuan-1
CLOUD_SSD、CLOUD_PREMIUM
上海
ap-shanghai-2
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM
ap-shanghai-5
ap-shanghai-8
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM、CLOUD_TSSD
南京
ap-nanjing-1
ap-nanjing-1
CLOUD_HSSD、CLOUD_SSD
北京
ap-beijing-6
ap-beijing-7
ap-beijing-8
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM
成都
ap-chengdu-1
ap-chengdu-2
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM
中国香港
ap-hongkong-2
ap-hongkong-3
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM
新加坡
ap-singapore-2
ap-singapore-3
ap-singapore-4
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM
雅加达
ap-jakarta-1
ap-jakarta-2
CLOUD_HSSD、CLOUD_SSD
首尔
ap-seoul-1
ap-seoul-2
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM
硅谷
na-siliconvalley-1
na-siliconvalley-2
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM
法兰克福
eu-frankfurt-1
eu-frankfurt-2
CLOUD_HSSD、CLOUD_SSD、CLOUD_PREMIUM、CLOUD_TSSD

2. 创建实例

创建按量计费实例：CreateDBInstanceHour。
创建包年包月实例：CreateDBInstance。
通过了解如下核心参数的配置和说明，可实现快速创建实例。您也可在以上2篇 API 文档中详细了解所有的参数和说明。
参数名
传入的值或说明
备注
DeviceType
CLOUD_NATIVE_CLUSTER
创建云盘版单节点实例，此参数为必传。
InstanceNodes
1
创建云盘版单节点实例，此参数必传入1。
ClusterTopology
见下方结构说明
创建云盘版实例时为必传，表示云盘版节点拓扑配置。
Memory
实例内存（MB）
如4000表示4GB，此参数为必传。
Volume
磁盘容量（GB）
云盘大小，此参数为必传。
EngineVersion
8.0（默认）
支持5.7、8.0；8.4需 提交工单 申请。
Zone
主可用区
如 ap-shanghai-2，此参数为必传。
DiskType
磁盘类型
默认值 CLOUD_SSD，可选值 CLOUD_HSSD、CLOUD_PREMIUM、CLOUD_TSSD。
cpu
实例 cpu 核数
此参数为必传。
InstanceRole
master
此参数为必传。
UniqVpcId
私有网络 ID
此参数为必传。查询私有网络列表请参考 查询私有网络列表。
UniqSubnetId
私有网络下的子网 ID
此参数为必传。查询子网列表请参考 查询子网列表。
ClusterTopology 参数结构说明
{
  "ReadWriteNode": {
    "Zone": "ap-shanghai-2"
  },
  "ReadOnlyNodes": []
}
说明：
ReadWriteNode.Zone：读写节点所在可用区，必须与主可用区 Zone 参数一致。
ReadOnlyNodes：只读节点数组，单节点形态传空数组[]。

创建实例的示例演示

包年包月完整实例

通过 CreateDBInstance 创建包年包月的云盘版单节点实例的参数示例如下，其中值等于 null 的参数，您可根据需要进行选择配置。
POST / HTTP/1.1
Host: cdb.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateDBInstance
<公共请求参数>

{
  "Memory": 4000,
  "Volume": 20,
  "Period": 1,
  "GoodsNum": 1,
  "Zone": "ap-shanghai-2",
  "UniqVpcId": "vpc-b4zgfr3a",
  "UniqSubnetId": "subnet-cp3juq8r",
  "ProjectId": null,
  "Port": null,
  "InstanceRole": "master",
  "MasterInstanceId": null,
  "EngineVersion": "8.0",
  "Password": null,
  "ProtectMode": null,
  "DeployMode": null,
  "SlaveZone": null,
  "ParamList": [
    {
      "Name": null,
      "Value": null
    }
  ],
  "BackupZone": null,
  "AutoRenewFlag": null,
  "MasterRegion": null,
  "SecurityGroup": [
    null
  ],
  "RoGroup": {
    "RoGroupMode": null,
    "RoGroupId": null,
    "RoGroupName": null,
    "RoOfflineDelay": null,
    "RoMaxDelayTime": null,
    "MinRoInGroup": null,
    "WeightMode": null,
    "Weight": null,
    "RoInstances": [
      {
        "MasterInstanceId": null,
        "RoStatus": null,
        "OfflineTime": null,
        "Weight": null,
        "Region": null,
        "Zone": null,
        "InstanceId": null,
        "Status": null,
        "InstanceType": null,
        "InstanceName": null,
        "HourFeeStatus": null,
        "TaskStatus": null,
        "Memory": null,
        "Volume": null,
        "Qps": null,
        "Vip": null,
        "Vport": null,
        "VpcId": null,
        "SubnetId": null,
        "DeviceType": null,
        "EngineVersion": null,
        "DeadlineTime": null,
        "PayType": null,
        "ReplicationStatus": null
      }
    ],
    "Vip": null,
    "Vport": null,
    "UniqVpcId": null,
    "UniqSubnetId": null,
    "RoGroupRegion": null,
    "RoGroupZone": null,
    "DelayReplicationTime": null
  },
  "InstanceName": null,
  "ResourceTags": [
    {
      "TagKey": null,
      "TagValue": [
        null
      ]
    }
  ],
  "DeployGroupId": null,
  "ClientToken": null,
  "DeviceType": "CLOUD_NATIVE_CLUSTER",
  "ParamTemplateId": null,
  "AlarmPolicyList": [
    null
  ],
  "InstanceNodes": 1,
  "Cpu": null,
  "AutoSyncFlag": null,
  "CageId": null,
  "ParamTemplateType": null,
  "AlarmPolicyIdList": [
    null
  ],
  "EngineType": null,
  "Vips": [
    null
  ],
  "DataProtectVolume": null,
  "ClusterTopology": {
    "ReadWriteNode": {
      "Zone": "ap-shanghai-2",
      "NodeId": null
    },
    "ReadOnlyNodes": [
      {
        "IsRandomZone": null,
        "Zone": null,
        "NodeId": null
      }
    ]
  },
  "DiskType": "CLOUD_SSD",
  "DestroyProtect": null,
  "FourthZone": null
}

按量计费完整示例

通过 CreateDBInstanceHour 创建按量计费的云盘版单节点实例的参数示例如下，其中值等于 null 的参数，您可根据需要进行选择配置。
POST / HTTP/1.1
Host: cdb.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateDBInstanceHour
<公共请求参数>

{
  "GoodsNum": 1,
  "Memory": 4000,
  "Volume": 20,
  "EngineVersion": "8.0",
  "UniqVpcId": "vpc-b4***r3a",
  "UniqSubnetId": "subnet-cp3***8r",
  "ProjectId": null,
  "Zone": "ap-shanghai-2",
  "MasterInstanceId": null,
  "InstanceRole": "master",
  "MasterRegion": null,
  "Port": null,
  "Password": null,
  "ParamList": [
    {
      "Name": null,
      "Value": null
    }
  ],
  "ProtectMode": null,
  "DeployMode": null,
  "SlaveZone": null,
  "BackupZone": null,
  "SecurityGroup": [
    null
  ],
  "RoGroup": {
    "RoGroupMode": null,
    "RoGroupId": null,
    "RoGroupName": null,
    "RoOfflineDelay": null,
    "RoMaxDelayTime": null,
    "MinRoInGroup": null,
    "WeightMode": null,
    "Weight": null,
    "RoInstances": [
      {
        "MasterInstanceId": null,
        "RoStatus": null,
        "OfflineTime": null,
        "Weight": null,
        "Region": null,
        "Zone": null,
        "InstanceId": null,
        "Status": null,
        "InstanceType": null,
        "InstanceName": null,
        "HourFeeStatus": null,
        "TaskStatus": null,
        "Memory": null,
        "Volume": null,
        "Qps": null,
        "Vip": null,
        "Vport": null,
        "VpcId": null,
        "SubnetId": null,
        "DeviceType": null,
        "EngineVersion": null,
        "DeadlineTime": null,
        "PayType": null,
        "ReplicationStatus": null
      }
    ],
    "Vip": null,
    "Vport": null,
    "UniqVpcId": null,
    "UniqSubnetId": null,
    "RoGroupRegion": null,
    "RoGroupZone": null,
    "DelayReplicationTime": null
  },
  "AutoRenewFlag": null,
  "InstanceName": null,
  "ResourceTags": [
    {
      "TagKey": null,
      "TagValue": [
        null
      ]
    }
  ],
  "DeployGroupId": null,
  "ClientToken": null,
  "DeviceType": "CLOUD_NATIVE_CLUSTER",
  "ParamTemplateId": null,
  "AlarmPolicyList": [
    null
  ],
  "InstanceNodes": 1,
  "Cpu": 2,
  "AutoSyncFlag": null,
  "CageId": null,
  "ParamTemplateType": null,
  "AlarmPolicyIdList": [
    null
  ],
  "EngineType": null,
  "Vips": [
    null
  ],
  "DataProtectVolume": null,
  "ClusterTopology": {
    "ReadWriteNode": {
      "Zone": "ap-shanghai-2",
      "NodeId": null
    },
    "ReadOnlyNodes": [
      {
        "IsRandomZone": null,
        "Zone": null,
        "NodeId": null
      }
    ]
  },
  "DiskType": "CLOUD_SSD",
  "ClusterType": null,
  "DestroyProtect": null,
  "FourthZone": null
}

特殊注意事项

不需要传 SlaveZone / BackupZone：单节点无备节点，无需指定备节点可用区和备份可用区。
InstanceNodes 不能为空：云盘版强制校验此参数，不传会报错。
ClusterTopology 必传：云盘版强制要求，不传会导致参数校验失败。
DiskType 取值范围：必须是目标可用区支持的磁盘类型，否则报错“集群版实例 diskType 的取值错误”。
Zone 一致性：Zone 参数与 ClusterTopology.ReadWriteNode.Zone 必须一致。
ProtectMode / DeployMode：单节点无需传这些高可用相关参数。

错误码说明

1. 通用错误码

错误码
含义
说明
InvalidParameter
参数校验失败
参数格式或取值不合法。
InvalidParameterValue
参数值无效
如 Zone 不存在、Memory 规格不支持等。

2. 云盘版特有错误信息

错误信息
触发条件
解决方案
instanceNodes cannot be empty
云盘版未传 InstanceNodes 参数
必须传 InstanceNodes=1。
集群版实例 diskType 的取值错误
DiskType 不在允许范围内
传 CLOUD_SSD、CLOUD_HSSD、CLOUD_PREMIUM。
InvalidParameterValue.InvalidParameterValueError
ClusterTopology 格式错误或缺失
按本文中的 ClusterTopology 参数结构说明正确传入。

3. 常见业务错误码

错误码/Code
含义
说明
9544
实例不存在
操作的实例 ID 无效。
1001010
参数校验失败
请求参数不满足约束条件。
1002357
可用区不支持该实例类型
目标可用区未开放云盘版标准型售卖。
1002359
规格不支持
Memory/Volume 组合不在售卖规格列表中。
CdbError.TaskError
后台任务执行失败
发货流程异常，需联系技术支持。
OperationDenied.AccountNotExists
账号不存在或欠费
检查账号状态。
ResourceInsufficient
资源不足
目标可用区资源售罄，尝试其他可用区。
中国站