Create an instance - API Reference| Alibaba Cloud Documentation Center

Before you call this operation, make sure that you understand the billing methods and pricing of ApsaraDB RDS. For more information, see Pricing, billable items, and billing methods.

For more information about ApsaraDB RDS instance types, see Primary ApsaraDB RDS 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 RDS instance. For more information, see Primary ApsaraDB RDS instance types. You can call the DescribeAvailableResource operation to query the available instance types in a region.
DBInstanceNetType	String	Yes	Internet	The type of network that is used to connect 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 ApsaraDB RDS instance types. You can call the DescribeAvailableResource operation to query the storage capacity range that is supported for a specified 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 TX
EngineVersion	String	Yes	5.6	The version of the database engine 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, 2019_std_ha, and 2019_ent PostgreSQL: 9.4, 10.0, 11.0, 12.0, and 13.0 PPAS: 9.3 and 10.0 MariaDB TX: 10.3
PayType	String	Yes	Postpaid	The billing method of the instance. Valid values: Postpaid: pay-as-you-go Prepaid: subscription Note The system automatically generates a purchase order and completes the payment.
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 the entries with commas (,). Each entry must be unique. The IP address whitelist can contain up to 1,000 entries. The entries in the IP address whitelist must be in one of the following formats: IP address. Example: 10.23.12.24. CIDR block. Example: 10.23.12.24/24. In the example provided, 24 specifies that the prefix of each IP address is 24 bits in length. You can replace 24 with a value within the range of 1 to 32.
SystemDBCharset	String	No	gbk	The character set that is used for the instance. This parameter is deprecated.
DBInstanceDescription	String	No	Test database	The name of the instance. The name must be 2 to 255 characters in length and must start with a letter. 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 only contain 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 virtual private cloud (VPC) and a vSwitch, you must specify the ZoneId parameter. If you specify the RDS High-availability Edition, you must also specify the ZoneIdSlave1 parameter, which specifies whether to use the single-zone deployment method or the multi-zone deployment method. If you specify the RDS Enterprise Edition, you must also specify the ZoneIdSlave1 and ZoneIdSlave2 parameters, which specify whether to use the single-zone deployment method or the 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 type of network in which the instance resides. Valid values: VPC: VPC. Classic: classic network. This is the default value. Note If you specify standard SSDs or enhanced SSDs (ESSDs), you can specify only the VPC network type. For example, if you want to create an instance that runs the RDS 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. The system automatically sets the connection mode of 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 the 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. The system automatically assigns a private IP address to the instance based on the values of 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 SSDs (ESSDs) of performance level 1 (PL1). cloud_essd2: ESSDs of PL2. cloud_essd3: ESSDs 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 to encrypt data on standard SSDs or ESSDs 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 automatically 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 by your Alibaba Cloud account for Resource Access Management (RAM) users. RAM users can use the ARN to connect to ApsaraDB RDS to KMS. You can copy the ARN from the RAM console. Note For more information about how to grant permissions to RAM users in 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. If the subscription billing method is specified for the instance, you must specify this parameter. 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 an instance in a dedicated cluster, you must specify this parameter. Note You can call the DescribeDedicatedHostGroups operation to query the details about a dedicated cluster. If no dedicated clusters are created, you can call the CreateDedicatedHostGroup operation to create a dedicated cluster.
TargetDedicatedHostIdForMaster	String	No	i-bpxxxxxxx1	The ID of the host to which the instance belongs in the specified dedicated cluster. If you create a primary instance in a dedicated cluster, you must specify this parameter. If you do not specify this parameter, the system automatically assigns a host to the instance. Note You can call the DescribeDedicatedHostGroups operation to query the details about a dedicated cluster. If no hosts are created, you can call the CreateDedicatedHost operation to create a host.
TargetDedicatedHostIdForSlave	String	No	i-bpxxxxxxx2	The ID of the host to which the instance belongs in the specified dedicated cluster. If you create a secondary instance that runs the RDS High-availability Edition or Enterprise Edition in a dedicated cluster, you must specify this parameter. If you do not specify this parameter, the system assigns a host to the instance. Note You can call the DescribeDedicatedHosts operation to query the details about the hosts in a dedicated cluster. If no hosts are created, you can call the CreateDedicatedHost operation to create a host.
TargetDedicatedHostIdForLog	String	No	i-bpxxxxxxx3	The ID of the host to which the instance belongs in the specified dedicated cluster. If you create a logger instance that runs the RDS Enterprise Edition in a dedicated cluster, you must specify this parameter. If you do not specify this parameter, the system assigns a host to the instance. Note You can call the DescribeDedicatedHosts operation to query the details about the hosts in a dedicated cluster. If no hosts are created, you can call the CreateDedicatedHost operation to create a host.
DBParamGroupId	String	No	rpg-sys-xxxx	The ID of the parameter template that is used for the instance.
DBTimeZone	String	No	+08:00	The time zone of the instance. This parameter takes effect only when you set the Engine parameter to MySQL or PostgreSQL. If you set the Engine parameter to MySQL. This time zone of the instance is in UTC. Valid values: -12:59 to +13:00. You can specify this parameter when the instance is equipped with local SSDs. For example, you can specify the time zone to Asia/Hong_Kong. For more information about time zones, see Time zones. If you set the Engine parameter to PostgreSQL. This time zone of the instance is not in UTC. For more information about time zones, see Time zones. You can specify this parameter only when the instance is equipped with standard SSDs or ESSDs. Note You can specify the time zone when you create a primary instance. You cannot specify the time zone when you create a read-only instance. Read-only instances inherit the time zone of their primary instance. If you do not specify this parameter, the system assigns the default time zone of the region where the instance resides.
DBIsIgnoreCase	String	No	true	Specifies whether the table names on the instance are case-sensitive. Valid values: true: The table names on the instance are not case-sensitive. This is the default value. false: The table names on the instance are case-sensitive.
TargetMinorVersion	String	No	rds_20200229	The minor engine version of the instance. You must specify this parameter only when you specify 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 different MySQL versions and RDS editions: rds: The instance runs the RDS Basic Edition or RDS 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 minor engine versions, see Release notes of minor AliSQL versions.
StorageAutoScale	String	No	Disable	Specifies whether to enable automatic storage expansion for the instance. Valid values: Enable Disable Default value: Disable. Note After the instance is created, you can call the ModifyDasInstanceConfig operation to adjust the settings of automatic storage expansion for the instance. For more information, see Configure automatic storage expansion for an ApsaraDB RDS for MySQL instance.
StorageThreshold	Integer	No	50	The threshold based on which automatic storage expansion is triggered. Unit: percent. 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 expansion. The storage capacity of the instance cannot exceed the maximum storage capacity. 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.
DryRun	Boolean	No	false	Specifies whether to conduct a precheck before the system creates the instance. Valid values: true: The system prechecks the request and does not create the instance. The system prechecks items such as the request parameters, request format, service limits, and available resources. false: The system sends the request without a precheck. After the request passes the precheck, the system creates the instance. Default value: false.
UserBackupId	String	No	67798****	The ID of the backup file that is used to create the instance. You can call the ListUserBackupFiles operation to query backup files. If you want to create an instance by using the data of a backup file, you must specify this parameter. Note This parameter is supported only when the following requirements are met: The PayType parameter is set to Postpaid. The Engine parameter is set to MySQL. The EngineVersion parameter is set to 5.7. The Category parameter is set to Basic.
Tag.N.Key	String	No	testkey1	The key of the tag that you want to create and add to the instance. You can use this parameter to add tags to the instance. The value of the N variable in the Tag.N.Key parameter ranges from 1 to 20. You can specify multiple values for this parameter to create and add multiple tags to the instance. For example, if you want to create and add two tags to the instance, you must specify two values: Tag.1.Key and Tag.2.Key. Note If the specified tag key is an existing key, the system directly adds the tag key to the instance. You can call the ListTagResources operation to query the details about the existing tags. If the specified tag key is not an existing key, the system creates the tag key and adds the tag key to the instance. This parameter cannot be an empty string. This parameter must be used together with the Tag.N.Value parameter.
Tag.N.Value	String	No	testvalue1	The tag value that is associated with the specified tag key. You can specify this parameter to add tags to the instance. The value of the N variable in the Tag.N.Value parameter ranges from 1 to 20. You can specify multiple values for this parameter to create and add multiple tags to the instance. This parameter must be used together with the Tag.N.Key parameter. For example, you specify Tag.1.Key and Tag.2.Key, you must also specify Tag.1.Value and Tag.2.Value. Note If the specified tag value is found in the specified tag key, the system directly adds the tag value to the instance. You can call the ListTagResources operation to query the details about the existing tags. If the specified tag value is not found in the specified tag key, the system creates the tag value and adds the tag value to the instance. This parameter must be used together with the Tag.N.Key parameter.
Amount	Integer	No	2	The number of ApsaraDB RDS for MySQL instances that you want to create. The parameter takes effect only when you create multiple ApsaraDB RDS for MySQL instances by using a single request. Valid values: 1 to 20. Default value: 1. Note If you want to create multiple ApsaraDB RDS for MySQL instances by using a single request, you can add tags to all the instances by using the Tag.N.Key parameter and the Tag.N.Value parameter. After the instances are created, you can manage the instances based on the tags. After you submit a request to create multiple ApsaraDB RDS for MySQL instances, the operation returns only the TaskId parameter, RequestId parameter, and Message parameter. You can call the DescribeDBInstanceAttribute operation to query the details about a specified instance. If the value of the Engine parameter is not MySQL and the value of the Amount parameter is greater than 1, the operation fails and returns an error code `InvalidParam.Engine`.
CreateStrategy	String	No	Atomicity	The policy based on which you want to create multiple instances. The parameter takes effect only when the value of the Amount parameter is greater than 1. Valid values: Atomicity: atomicity. The instances are all created. If one of instances cannot be created, none of the instances is created. Partial: non-atomicity. Each of the instances is independently created. The failure in creating one instance does not affect the creation of the other instances. Default value: Atomicity.

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 an internal endpoint or a public endpoint.
Port	String	3306	The port that is used to connect to the instance. Note The DBInstanceNetType parameter indicates whether the port is an internal port or a public port.
DryRun	Boolean	true	Indicates that the system prechecks the request before the system creates the instance. The return value is fixed to true. Note If the system does not perform a precheck, this parameter is not returned.
DryRunResult	Boolean	true	Indicates whether the request passes the precheck. Valid values: true: The request passes the precheck. false: The request fails the precheck. Note If the system does not perform a precheck, this parameter is not returned. If the request fails the precheck, an error is returned.
Message	String	Batch Create DBInstance Task Is In Process.	The message indicates the creation of multiple instances. The parameter is returned only when the value of the Amount parameter is greater than 1.
RequestId	String	1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC	The ID of the request.
TagResult	Boolean	true	Indicates whether the specified tag is added to the instance. Valid values: true: The specified tag is added to the instance. false: The specified tag cannot be added to the instance. Note If you do not add a tag to the instance, this parameter is not returned.
TaskId	String	s2365879-a9d0-55af-fgae-f2**********	The ID of the task that is run to create multiple instances. The parameter is returned only when the value of the Amount parameter is greater than 1. Note The TaskID parameter cannot be used to query a task.

Note In the new version of SDK, the default timeout period on the client side is different from the default timeout period on the instance. If you use the new version of SDK to call this operation, a timeout error may be reported even if the operation is successfully called. To prevent this issue, you can set the ReadTimeout parameter to 20000 before you call this operation.

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 response

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


HTTP status code	Error code	Error message	Description
400	InvalidZoneId.NotSupported	The Specified vpc Zone not supported.	The error message returned because the zone that you specify does not allow you to create an instance in a VPC. Specify a different 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 no valid payment methods are provided within your Alibaba Cloud account. 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 no valid payment methods are provided within your Alibaba Cloud account. Add a valid payment method and try again.
400	SYSTEM.CONCURRENT_OPERATE	Concurrent operation is detected.	The error message returned because concurrent operations are run in the system.
400	ZoneId.NotMatchWithCategory	The number of ZoneId specified does not match with category.	The error message returned because the number of zone IDs that are specified in the ZoneId parameter is not supported for the deployment method that you specify. Specify a valid value for this parameter.
400	InvalidTagKey.Malformed	The Tag.N.Key parameter is empty.	The error message returned because the Tag.N.Key parameter is empty.
400	InvalidTagValue.Malformed	The Tag.N.Value parameter is empty.	The error message returned because the Tag.N.Value parameter is empty.
400	Duplicate.TagKey	The Tag.N.Key contains duplicate keys.	The error message returned because the Tag.N.Key parameter specifies a duplicate key.
400	NumberExceed.Tags	The maximum number of Tags is exceeded. The maximum is 20.	The error message returned because the number of tags exceeds the maximum number of tags that are allowed. The maximum number is 20.
400	MissingParameter.ResourceIds	The parameter ResourceIds.N must not be null.	The error message returned because the ResourceId parameter is empty.
400	InvalidParameter.TagKey	The Tag.N.Key parameter is invalid.	The error message returned because the value of the Tag.N.Key parameter is invalid.
400	InvalidParam.Amount	Amount is allowed from 1 to 20.	The error message returned because the value of the Amount parameter is not within the range of 1 to 20.
400	InvalidParam.CreateStrategy	Only Atomicity and Partial are allowed.	The valid values of the CreateStrategy parameter are Atomicity and Partial.

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