Create instance - API Reference| Alibaba Cloud Documentation Center

Before you call this operation, make sure that you understand the billing methods and prices of ApsaraDB RDS. For more information, visit the ApsaraDB RDS product homepage.

For more information about ApsaraDB RDS instance types, see Primary instance types.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	CreateDBInstance	The operation that you want to perform. Set the value to CreateDBInstance.
DBInstanceClass	String	Yes	rds.mysql.s1.small	The instance type of the instance. For more information, see Primary instance types. You can call the DescribeAvailableResource operation to query the instance types that are available to a region.
DBInstanceNetType	String	Yes	Internet	The type of network connection to the instance. Valid values: Internet: The instance is connected over the Internet. Intranet: The instance is connected over an internal network.
DBInstanceStorage	Integer	Yes	20	The storage capacity of the instance. Unit: GB. The storage capacity increases in increments of 5 GB. For more information, see Primary instance types. You can call the DescribeAvailableResource operation to query the storage capacity range that is supported for an instance type in a region.
Engine	String	Yes	MySQL	The database engine that is run on the instance. Valid values: MySQL SQLServer PostgreSQL PPAS MariaDB
EngineVersion	String	Yes	5.6	The database engine version that is run on the instance. Valid values: MySQL: 5.5, 5.6, 5.7, and 8.0 SQL Server: 2008r2, 08r2_ent_ha, 2012, 2012_ent_ha, 2012_std_ha, 2012_web, 2014_std_ha, 2016_ent_ha, 2016_std_ha, 2016_web, 2017_std_ha, 2017_ent, and 2019_ent PostgreSQL: 9.4, 10.0, 11.0, and 12.0 PPAS: 9.3 and 10.0 MariaDB: 10.3
PayType	String	Yes	Postpaid	The billing method of the instance. Valid values: Postpaid: pay-as-you-go Prepaid: subscription
RegionId	String	Yes	cn-hangzhou	The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.
SecurityIPList	String	Yes	10.23.12.27/24	The IP address whitelist of the instance. For more information, see Configure an IP address whitelist for an ApsaraDB RDS for MySQL instance. If the IP address whitelist contains more than one entry, separate these entries with commas (,). The IP address whitelist can contain up to 1,000 unique entries. The IP address whitelist supports the following two formats: IP address, for example, 10.23.12.24. Classless Inter-Domain Routing (CIDR) block, for example, 10.23.12.24/24. In the provided example, 24 indicates that the prefix of the CIDR block is 24 bits in length. You can replace 24 with a value that ranges from 1 to 32.
SystemDBCharset	String	No	gbk	The character set that is used for the instance. This parameter has been deprecated.
DBInstanceDescription	String	No	testdatabase	The name of the instance. The name must be 2 to 255 characters in length. The name can contain letters, digits, underscores (_), and hyphens (-). Note The name cannot start with http:// or https://.
ClientToken	String	No	ETnLKlblzczshOTUbOCzxxxxxxxxxx	The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.
ZoneId	String	No	cn-hangzhou-b	The zone ID of the primary instance. Note If you specify a VPC and a vSwitch, you must also specify the ZoneId parameter. If you select the High-availability Edition, you must also specify the ZoneIdSlave1 parameter. This parameter specifies whether to use the single-zone or multi-zone deployment method. If you select the Enterprise Edition, you must also specify the ZoneIdSlave1 and ZoneIdSlave2 parameters. These parameters specify whether to use the single-zone or multi-zone deployment method.
ZoneIdSlave1	String	No	cn-hangzhou-c	The zone ID of the secondary instance. If you set the ZoneIdSlave1 parameter to the same value as the ZoneId parameter, the single-zone deployment method is used. If you set the ZoneIdSlave1 parameter to a different value than the ZoneId parameter, the multi-zone deployment method is used.
ZoneIdSlave2	String	No	cn-hangzhou-d	The zone ID of the logger instance. If you set the ZoneIdSlave2 parameter to the same value as the ZoneId parameter, the single-zone deployment method is used. If you set the ZoneIdSlave2 parameter to a different value than the ZoneId parameter, the multi-zone deployment method is used.
InstanceNetworkType	String	No	Classic	The network type of the instance. Valid values: VPC: VPC network type. Classic: classic network type. This is the default network type. Note If you select standard or enhanced SSDs, you can select only the VPC network type. For example, if you want to create an instance that runs the Basic Edition, you must set the InstanceNetworkType parameter to VPC. If you set the Engine parameter to MariaDB, you must specify the InstanceNetworkType parameter.
ConnectionMode	String	No	Standard	The mode that is used to connect to the instance. Valid values: Standard: The instance is connected in standard mode. Safe: The instance is connected in database proxy mode. By default, the system assigns a connection mode to the instance. Note SQL Server 2012, SQL Server 2016, and SQL Server 2017 support only the standard mode.
VPCId	String	No	vpc-xxxxxxxxxxxx	The ID of the VPC to which the instance belongs. Note If you set the InstanceNetworkType parameter to VPC, you must specify the VPCId parameter.
VSwitchId	String	No	vsw-xxxxxxxxxxx	The ID of the vSwitch associated with the specified VPC. If you specify more than one vSwitch ID, separate these vSwitch IDs with commas (,). Note If you set the InstanceNetworkType parameter to VPC, you must specify the VSwitchId parameter.
PrivateIpAddress	String	No	172.16.201.69	The private IP address of the instance. The private IP address must be within the CIDR block that is supported by the specified vSwitch. By default, the system assigns a private IP address to the instance based on the VPCId and VSwitchId parameters.
UsedTime	String	No	2	The subscription period of the instance. Valid values: If you set the Period parameter to Year, the value of the UsedTime parameter ranges from 1 to 5. If you set the Period parameter to Month, the value of the UsedTime parameter ranges from 1 to 11. Note If you set the PayType parameter to Prepaid, you must specify the UsedTime parameter.
Period	String	No	Year	The renewal cycle of the instance. Valid values: Year Month Note If you set the PayType parameter to Prepaid, you must specify the Period parameter.
ResourceGroupId	String	No	rg-acfmyxxxxxxxxxx	The ID of the resource group to which the instance belongs.
DBInstanceStorageType	String	No	cloud_ssd	The type of storage media that is used for the instance. Valid values: local_ssd: local SSD. This is the recommended storage type cloud_ssd: standard SSD. cloud_essd: enhanced SSD of PL1. cloud_essd2: enhanced SSD of PL2. cloud_essd3: enhanced SSD of PL3.
BusinessInfo	String	No	121436975448952	The extended business information of the instance.
EncryptionKey	String	No	0d24xxxx-da7b-4786-b981-9a164dxxxxxx	The ID of the key that is used for disk encryption in the region of the instance. You can obtain the ID of the key from the Key Management Service (KMS) console. You can also create a key. For more information, see Manage CMKs. Note If you specify the EncryptionKey parameter, disk encryption is enabled. In this case, you must also specify the RoleARN parameter. Disk encryption cannot be disabled after it is enabled.
RoleARN	String	No	acs:ram::1406xxxxxx:role/aliyunrdsinstanceencryptiondefaultrole	The Alibaba Cloud Resource Name (ARN) that is provided to the service account of the instance by your Alibaba Cloud account. The ARN is used to connect to KMS. You can copy the ARN from the RAM console. Note For more information about how to grant permissions by using the RAM console, see Authorize an ApsaraDB RDS for MySQL instance to access KMS.
AutoRenew	String	No	true	Specifies whether to enable auto-renewal for the instance. You need to specify this parameter only when the instance uses the subscription billing method. Valid values: true and false. Note If you set the Period parameter to Month, the auto-renewal cycle is one month. If you set the Period parameter to Year, the auto-renewal cycle is one year.
Category	String	No	HighAvailability	The RDS edition of the instance. Valid values: Basic: Basic Edition HighAvailability: High-availability Edition AlwaysOn: Cluster Edition Finance: Enterprise Edition
DedicatedHostGroupId	String	No	dhg-4nxxxxxxx	The ID of the dedicated cluster to which the instance belongs. If you create the instance in a dedicated cluster, you must specify the DedicatedHostGroupId parameter.
TargetDedicatedHostIdForMaster	String	No	i-bpxxxxxxx1	The ID of the host to which the primary instance belongs. If you create the instance in a dedicated cluster, you must specify this parameter. If you do not specify this parameter, the system assigns a host to the instance.
TargetDedicatedHostIdForSlave	String	No	i-bpxxxxxxx2	The ID of the host to which the secondary instance belongs. If you create the instance in a dedicated cluster and select the High-availability or Enterprise Edition, you must specify this parameter. If you do not specify this parameter, the system assigns a host to the instance.
TargetDedicatedHostIdForLog	String	No	i-bpxxxxxxx3	The ID of the host to which the logger instance belongs. If you create the instance in a dedicated cluster and select the Enterprise Edition, you must specify this parameter. If you do not specify this parameter, the system assigns a host to the instance.
DBParamGroupId	String	No	rpg-sys-xxxx	The ID of the parameter template that is used for the instance.
DBTimeZone	String	No	+08:00	The UTC time zone of the instance. Valid values: -12:59 to +13:00. Note If you do not specify this parameter, the system assigns a time zone to the instance. The assigned time zone is the default time zone of the region to which the instance belongs. If the instance uses local SSDs, you can name the time zone. For example, you can name the time zone as Asia/Hong_Kong. For more information, see the official documentation of the database engine in use.
DBIsIgnoreCase	String	No	1	Specifies whether table names are case-sensitive. Valid values: 1: Table names are not case-sensitive. This is the default value. 0: Table names are case-sensitive.
TargetMinorVersion	String	No	rds_20200229	The minor engine version that is run on the instance. You need to specify this parameter only when you select the MySQL database engine. Format: RDS edition_Minor engine version. Examples: rds_20200229, xcluster_20200229, and xcluster80_20200229. The following codes are used to represent RDS editions: rds: The instance runs the RDS Basic or High-availability Edition. xcluster: The instance runs MySQL 5.7 on RDS Enterprise Edition. xcluster80: The instance runs MySQL 8.0 on RDS Enterprise Edition. Note For more information about the minor engine versions, see Release notes of minor AliSQL versions.
StorageAutoScale	String	No	Disable	Specifies whether to enable the automatic storage capacity expansion feature. Valid values: Enable: The feature is enabled. Disable: The feature is disabled. Default value: Disable.
StorageThreshold	Integer	No	50	The threshold based on which automatic storage capacity expansion is triggered. Unit: %. Valid values: 10 20 30 40 50 Note If you set the StorageAutoScale parameter to Enable, you must specify the StorageThreshold parameter.
StorageUpperBound	Integer	No	2000	The maximum storage capacity that is allowed for automatic storage capacity expansion. The specified storage capacity cannot exceed the maximum value. Unit: GB. Valid values: an integer greater than or equal to 0. Note If you set the StorageAutoScale parameter to Enable, you must specify the StorageUpperBound parameter.

Response parameters


Parameter	Type	Example	Description
DBInstanceId	String	rm-uf6wjk5xxxxxxxxxx	The ID of the instance.
OrderId	String	1007893702xxxxx	The ID of the order.
ConnectionString	String	rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com	The endpoint that is used to connect to the instance. Note The DBInstanceNetType parameter indicates whether the endpoint is internal or public.
Port	String	3306	The port number that is used to connect to the instance. Note The DBInstanceNetType parameter indicates whether the port number is internal or public.
RequestId	String	1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC	The ID of the request.

Examples

Sample requests

http(s)://rds.aliyuncs.com/? Action=CreateDBInstance
&RegionId=cn-hangzhou
&Engine=MySQL
&EngineVersion=5.6
&DBInstanceClass=rds.mysql.s1.small
&DBInstanceStorage=20
&DBInstanceNetType=Internet
&PayType=Postpaid
&SecurityIPList=10.23.12.27/24
&<Common request parameters>

Sample success responses

XML format

<CreateDBInstanceResponse>
      <OrderId>1007893702xxxxx</OrderId>
      <ConnectionString>rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com</ConnectionString>
      <DBInstanceId>rm-uf6wjk5xxxxxxx</DBInstanceId>
      <Port>3306</Port>
      <RequestId>1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC</RequestId>
</CreateDBInstanceResponse>

JSON format

{
    "OrderId": "1007893702xxxxx",
    "ConnectionString": "rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com",
    "DBInstanceId": "rm-uf6wjk5xxxxxxx",
    "Port": "3306",
    "RequestId": "1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC"
}

Error codes


HttpCode	Error code	Error message	Description
400	InvalidZoneId.NotSupported	The Specified vpc Zone not supported.	The error message returned because the specified zone does not allow you to create the instance in a VPC. Change the zone and try again.
400	InvalidPaymentMethod.Incomplete	No payment method is specified for your account. We recommend that you add a payment method.	The error message returned because your Alibaba Cloud account does not provide a valid payment method. Add a valid payment method and try again.
400	InvalidPaymentMethod.Missing	No payment method is specified for your account. We recommend that you add a payment method.	The error message returned because your Alibaba Cloud account does not provide a valid payment method. Add a valid payment method and try again.
400	SYSTEM.CONCURRENT_OPERATE	Concurrent operation is detected.	The error message returned because the system runs threads in parallel.
400	ZoneId.NotMatchWithCategory	The number of ZoneId specified does not match with category.	The error message returned because the number of zone IDs specified in the ZoneId parameter is not supported for the specified deployment method.

For a list of error codes, visit the API Error Center.