CreateDBInstance - ApsaraDB for MongoDB

Creates or clones an ApsaraDB for MongoDB replica set instance.

Operation description

Before you call this operation, make sure that you understand the billing methods and pricing of ApsaraDB for MongoDB.

For more information about the instance types of ApsaraDB for MongoDB, see Instance types.

To create a sharded cluster instance, call the CreateShardingDBInstance operation.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

dds:CreateDBInstance

create

*Instance

acs:dds:{#regionId}:{#accountId}:dbinstance/*

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. To query the region ID, call the DescribeRegions operation. Note When you clone an instance or restore an instance from the recycle bin, this parameter must be the same as the region ID of the source instance.	cn-hangzhou
ClientToken	string	No	A client token that is used to ensure the idempotence of the request. You can use the client to generate the token. Make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot be more than 64 characters long.	ETnLKlblzczshOTUbOCz****
ZoneId	string	No	The zone ID. To query the zone ID, call the DescribeRegions operation.	cn-hangzhou-g
EngineVersion	string	Yes	The database engine version. Valid values: 8.0 7.0 6.0 5.0 4.4 4.2 4.0 Note When you clone an instance or restore an instance from the recycle bin, this parameter must be the same as the engine version of the source instance. Warning Versions 3.4 and earlier are discontinued.	4.4
DBInstanceClass	string	Yes	The instance type. To query instance types, call the DescribeAvailableResource operation.	dds.mongo.standard
DBInstanceStorage	integer	Yes	The storage space of the instance in GB. The value of this parameter varies based on the instance type. For more information, see Replica set instance types.	10
DBInstanceDescription	string	No	The instance name. The name must meet the following requirements: It must start with a letter or a Chinese character. It can contain letters, Chinese characters, digits, underscores (_), periods (.), and hyphens (-). It must be 2 to 256 characters long.	test
SecurityIPList	string	No	The IP address whitelist of the instance. Separate multiple IP addresses with commas (,). Each IP address in the whitelist must be unique. The whitelist can be in one of the following formats: 0.0.0.0/0 An IP address, for example, 10.23.12.24. A CIDR block, for example, 10.23.12.0/24. The /24 indicates that the prefix of the CIDR block is 24 bits in length. You can set the prefix to a value from 1 to 32. Note You can add a maximum of 1,000 IP addresses or CIDR blocks to all IP address whitelists. If you set the whitelist to 0.0.0.0/0, all IP addresses can access the instance. This is a high-risk setting. Use this with caution.	192.168.xx.xx,192.168.xx.xx
AccountPassword	string	No	The password for the root account. The password must meet the following requirements: It must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. The special characters are !@#$%^&()_+-= It must be 8 to 32 characters long. Note* For more information about connection failures caused by special characters in passwords, see How do I fix a connection failure that is caused by special characters in a password?.	123456Aa
Period	integer	No	The subscription duration of the instance in months. Valid values: 1 to 9 (integers), 12, 24, 36, and 60. Note This parameter is required and takes effect only when you set the ChargeType parameter to PrePaid.	1
ChargeType	string	No	The billing method of the instance. Valid values: PostPaid: The default value. Pay-as-you-go. PrePaid: Subscription. Note If you set this parameter to PrePaid, you must also specify the Period parameter.	PrePaid
NetworkType	string	No	The network type of the instance. Valid values: VPC: virtual private cloud (VPC).	VPC
VpcId	string	No	The VPC ID.	vpc-bp175iuvg8nxqraf2****
VSwitchId	string	No	The vSwitch ID.	vsw-bp1gzt31twhlo0sa5****
SrcDBInstanceId	string	No	The source instance ID. Note When you clone an instance, you must specify this parameter and the BackupId or RestoreTime parameter. When you restore an instance from the recycle bin, you only need to specify this parameter. You do not need to specify the BackupId or RestoreTime parameter.	dds-bp1ee12ad351****
BackupId	string	No	The backup point ID. To query the backup point ID, call the DescribeBackups operation. Note You must specify this parameter and the SrcDBInstanceId parameter only when you clone an instance based on a backup point.	32994****
RestoreTime	string	No	The point in time to which you want to restore the instance. You can specify any point in time within the last seven days. The time must be in the yyyy-MM-ddTHH:mm:ssZ format and in UTC. Note You must specify this parameter and the SrcDBInstanceId parameter only when you clone an instance based on a point in time.	2022-03-13T12:11:14Z
BusinessInfo	string	No	The business information. This is an optional parameter.	{“ActivityId":"000000000"}
AutoRenew	string	No	Specifies whether to enable auto-renewal for the instance. Valid values: true: Enables auto-renewal. false: The default value. Disables auto-renewal. You must manually renew the instance. Note This parameter is optional and takes effect only when you set the ChargeType parameter to PrePaid.	true
DatabaseNames	string	No	The database name. Note When you clone an instance, you can specify this parameter to clone specific databases. If you do not specify this parameter, all databases of the instance are cloned.	mongodbtest
CouponNo	string	No	Specifies whether to use a coupon. Valid values: default or null (default): Uses a coupon. youhuiquan_promotion_option_id_for_blank: Does not use a coupon.	default
StorageEngine	string	No	The storage engine of the instance. The value is fixed as WiredTiger. Note When you clone an instance or restore an instance from the recycle bin, this parameter must be the same as the storage engine of the source instance. For more information about the constraints on storage engines and database versions, see Versions and storage engines.	WiredTiger
ReplicationFactor	string	No	The number of primary and secondary nodes in the replica set instance. Valid values: 3 (default) 5 7 Important You do not need to specify this parameter for standalone instances.	3
ReadonlyReplicas	string	No	The number of read-only nodes in the replica set instance. Valid values are integers from 0 to 5. The default value is 0.	0
ResourceGroupId	string	No	The resource group ID.	rg-acfmyiu4ekp****
ClusterId	string	No	The dedicated cluster ID.	dhg-2x78****
Engine	string	No	The database engine. The value is fixed as MongoDB.	MongoDB
StorageType	string	No	The storage class. Valid values: cloud_essd1: ESSD PL1 disk. cloud_essd2: ESSD PL2 disk. cloud_essd3: ESSD PL3 disk. cloud_auto: ESSD AutoPL disk. local_ssd: Local SSD. Note For standalone instances, if you pass the value cloud_essd1, an ESSD disk is used. ESSD AutoPL disks are available only on the China site (aliyun.com). For instances of version 4.4 or later, the default value is cloud_essd1. For instances of version 4.2 or earlier, the default value is local_ssd.	cloud_essd1
SecondaryZoneId	string	No	The zone where the secondary node is deployed. This parameter is used for multi-zone deployment. Valid values: cn-hangzhou-g: Zone G in Hangzhou. cn-hangzhou-h: Zone H in Hangzhou. cn-hangzhou-i: Zone I in Hangzhou. cn-hongkong-b: Zone B in Hong Kong (China). cn-hongkong-c: Zone C in Hong Kong (China). cn-hongkong-d: Zone D in Hong Kong (China). cn-wulanchabu-a: Zone A in Ulanqab. cn-wulanchabu-b: Zone B in Ulanqab. cn-wulanchabu-c: Zone C in Ulanqab. ap-southeast-1a: Zone A in Singapore. ap-southeast-1b: Zone B in Singapore. ap-southeast-1c: Zone C in Singapore. ap-southeast-5a: Zone A in Jakarta. ap-southeast-5b: Zone B in Jakarta. ap-southeast-5c: Zone C in Jakarta. eu-central-1a: Zone A in Frankfurt. eu-central-1b: Zone B in Frankfurt. eu-central-1c: Zone C in Frankfurt. Note This parameter is available when the instance uses disks. The value of this parameter cannot be the same as the value of the ZoneId or HiddenZoneId parameter.	cn-hangzhou-h
HiddenZoneId	string	No	The zone where the hidden node is deployed. This parameter is used for multi-zone deployment. Valid values: cn-hangzhou-g: Zone G in Hangzhou. cn-hangzhou-h: Zone H in Hangzhou. cn-hangzhou-i: Zone I in Hangzhou. cn-hongkong-b: Zone B in Hong Kong (China). cn-hongkong-c: Zone C in Hong Kong (China). cn-hongkong-d: Zone D in Hong Kong (China). cn-wulanchabu-a: Zone A in Ulanqab. cn-wulanchabu-b: Zone B in Ulanqab. cn-wulanchabu-c: Zone C in Ulanqab. ap-southeast-1a: Zone A in Singapore. ap-southeast-1b: Zone B in Singapore. ap-southeast-1c: Zone C in Singapore. ap-southeast-5a: Zone A in Jakarta. ap-southeast-5b: Zone B in Jakarta. ap-southeast-5c: Zone C in Jakarta. eu-central-1a: Zone A in Frankfurt. eu-central-1b: Zone B in Frankfurt. eu-central-1c: Zone C in Frankfurt. Note This parameter is available when the instance uses disks. The value of this parameter cannot be the same as the value of the ZoneId or SecondaryZoneId parameter.	cn-hangzhou-i
Tag	array<object>	No	The custom tags.
	object	No
Key	string	No	The tag key. Note N specifies the Nth tag. For example, Tag.1.Key specifies the key of the first tag, and Tag.2.Key specifies the key of the second tag.	testdatabase
Value	string	No	The tag value. Note N specifies the Nth tag. For example, Tag.1.Value specifies the value of the first tag, and Tag.2.Value specifies the value of the second tag.	apitest
GlobalSecurityGroupIds	string	No	The global IP address whitelist templates for the instance. Separate multiple templates with commas (,). The templates cannot be repeated. This feature is in canary release.	g-qxieqf40xjst1ngpr3jz
Encrypted	boolean	No	Specifies whether to enable disk encryption.	true
EncryptionKey	string	No	The custom key ID.	2axxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ProvisionedIops	integer	No	The provisioned IOPS (input/output operations per second). Valid values: 0 to 50000.	1960
RestoreType	string	No	The method to restore an instance from a backup. 0: Restores the instance to a specified backup set. 1: Restores the instance to a specified point in time. 2: Restores a released instance to a specified backup set. 3: Restores the instance to a specified geo-redundant backup set.	0
SrcRegion	string	No	The region where the source instance is located. Note This parameter is required when RestoreType is set to 2 or 3.	2

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	D8F1D721-6439-4257-A89C-F1E8E9C9****
DBInstanceId	string	The instance ID.	dds-bp144a7f2db8****
OrderId	string	The order ID.	21077576248****

Examples

Success response

JSON format

{
  "RequestId": "D8F1D721-6439-4257-A89C-F1E8E9C9****",
  "DBInstanceId": "dds-bp144a7f2db8****",
  "OrderId": "21077576248****"
}

Error codes

HTTP status code	Error code	Error message	Description
400	SecurityRisk.AuthVerification	we have detected a risk with your default payment method. An email and notification has been sent to you. Please re-submit your order before after verificaiton.
400	MissingParameter	Period is mandatory for this action.
400	ORDER.ACCOUNT_INFORMATION_INCOMPLETE	Your information is incomplete. Complete your information before ordering.
400	InvalidClientToken.Malformed	Specified parameter ClientToken is not valid.
400	InvalidDBInstanceDescription.Malformed	Specified parameter DBInstanceDescription is not valid.	Invalid node name.
400	InvalidSecurityIPListLength.Malformed	The quota of security ip exceeds.
400	InsufficientBalance	Your account does not have enough balance.
400	QuotaExceed.AfterpayInstance	Living afterpay instances quota exceeded.
400	InvalidCapacity.NotFound	The Capacity provided does not exist in our records.
400	ResourceNotAvailable	Resource you requested is not available for finance user.
400	IdempotentParameterMismatch	Request uses a client token in a previous request but is not identical to that request.
400	InvalidSecurityIPList.Malformed	The specified parameter "SecurityIPList" is not valid.
400	InvalidSecurityIPList.Duplicate	The Security IP address is not in the available range or occupied.
400	InvalidDBInstanceStorage.ValueNotSupported	The specified parameter DBInstanceStorage is not valid.
400	InvalidAccountPassword.Malformed	Specified parameter AccountPassword is not valid.
400	TokenServiceError	Duplicate ClientToken request.
400	Zone.Closed	The specified zone is closed.
400	PRICE.ORIGIN_PRICE_ERROR	The origin price error.
400	NO_AVAILABLE_PAYMENT_METHOD	No payment method is specified for your account. We recommend that you add a payment method.
400	InvalidEcsImage.NotFound	Specified ecs image does not exist.
400	SaleValidateNoSpecificCodeFailed	Specified Storage or Version or InstanceClass is invalid.	Storage or Version or InstanceClass is empty.
400	Trade_Not_Support_Async_Pay	Trade not support async pay.
400	InvalidZoneld	The specified primary zone, secondary zone and hidden zone cannot be the same.	The parameters of the primary zone, secondary zone and hidden zone cannot be the same.
400	SameZoneId	The specified primary zone, secondary zone require two different zones.	The specified primary zone, secondary zone require two different zones.
403	RealNameAuthenticationError	Your account has not passed the real-name authentication yet.
403	RegionUnauthorized	There is no authority to create instance in the specified region.
403	OperationDenied	The resource is out of usage.
403	InvalidEngineVersionInRegion.NotAvailable	The EngineVersion in the Region is not available.
403	InvalidBackupLogStatus	Current backup log enable status does not support this operation.
403	IncorrectBackupSetState	Current backup set state does not support operations.
404	InvalidBackup.NotFound	The available backup does not exist in recovery time.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.