CreateShardingDBInstance-阿里云帮助中心

Creates or clones an ApsaraDB for MongoDB sharded cluster instance.

Operation description

Before calling this operation, make sure that you fully understand the billing methods and pricing of ApsaraDB for MongoDB.
For more information about the specifications of ApsaraDB for MongoDB instances, see Instance specifications.
To create a standalone instance or a replica set instance, call the CreateDBInstance 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:CreateShardingDBInstance

create

*Instance

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

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. You can call the DescribeRegions operation to query the region ID.	cn-hangzhou
ZoneId	string	No	The zone ID. You can call the DescribeRegions operation to query the zone ID.	cn-hangzhou-g
Engine	string	Yes	The database engine. Set the value to MongoDB. Valid values: MongoDB : The MongoDB database engine.	MongoDB
EngineVersion	string	Yes	The database version. Valid values: 8.0 7.0 6.0 5.0 4.4 4.2 4.0 Note For more information about the constraints on storage engines and versions, see Versions and storage engines. When you call this operation to clone an instance, the value of this parameter must be the same as that of the source instance. Valid values: 3.0 : MongoDB 3.0 4.0 : MongoDB 4.0 3.2 : MongoDB 3.2 5.0 : MongoDB 5.0 4.2 : MongoDB 4.2 6.0 : MongoDB 6.0 3.4 : MongoDB 3.4 7.0 : MongoDB 7.0 4.4 : MongoDB 4.4 8.0 : MongoDB 8.0 8.3 : MongoDB 8.3	4.4
DBInstanceDescription	string	No	The instance name. The name must meet the following requirements: It must start with a letter. It can contain digits, letters, underscores (_), periods (.), and hyphens (-). It must be 2 to 256 characters in length.	test
SecurityIPList	string	No	The IP address whitelist of the instance. Separate multiple IP addresses with commas (,). Each IP address must be unique. The following formats are supported: 0.0.0.0/0 IP addresses, such as 10.23.12.24. CIDR blocks, such as 10.23.12.0/24. 24 indicates the length of the prefix in the CIDR block, and the prefix length ranges from 1 to 32. Note You can add up to 1,000 IP addresses or CIDR blocks to the whitelist of an instance. The total number of IP addresses and CIDR blocks in all whitelist groups cannot exceed 1,000. 0.0.0.0/0 indicates that all IP addresses can access the databases of the instance. This is a high-risk setting. Configure this setting with caution.	192.168.xx.xx,192.168.xx.xx
AccountPassword	string	No	The password of 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. Special characters include !@#$%^&()_+-=. It must be 8 to 32 characters in length. Note* For more information about how to troubleshoot connection failures caused by special characters in database connection string, see What do I do if a connection failure occurs because the username or password in database connection string contains special characters?.	123456Aa
ChargeType	string	No	The billing method of the instance. Valid values: PostPaid: pay-as-you-go. This is the default value. PrePaid: subscription. Note If you set this parameter to PrePaid, you must also specify the Period parameter. Valid values: PostPaid : Pay-as-you-go. PrePaid : Subscription.	PrePaid
Period	integer	No	The subscription duration of the instance. Unit: months. Valid values: 1 to 9, 12, 24, 36, and 60. Note This parameter is required and valid only when the ChargeType parameter is set to PrePaid.	1
NetworkType	string	No	The network type of the instance. Valid values: VPC: VPC. Valid values: VPC : VPC. Classic : Classic network.	VPC
VpcId	string	No	The VPC ID.	vpc-bp1n3i15v90el48nx****
VSwitchId	string	No	The vSwitch ID.	vsw-bp1vj604nj5a9zz74****
SrcDBInstanceId	string	No	The ID of the source instance. Note You must specify this parameter only when you call this operation to clone an instance. You must also specify the RestoreTime parameter.	dds-bp11483712c1****
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. Specify the time in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC. Note You must specify this parameter only when you call this operation to clone an instance. You must also specify the SrcDBInstanceId parameter.	2022-03-08T02:30:25Z
ClientToken	string	No	The client token that is used to ensure the idempotence of the request and prevent duplicate submissions. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.	ETnLKlblzczshOTUbOCz****
StorageEngine	string	No	Specifies whether to perform a dry run on the request. Valid values: true: performs a dry run without executing the actual request. The system checks the request parameters, request format, service limits, and available resources. If the request fails the dry run, the system returns an error. If the request passes the dry run, the system returns the DryRunOperation error code. false: sends a normal request and executes the operation after the request passes the dry run. This is the default value. Valid values: RocksDB : The RocksDB storage engine. WiredTiger : The WiredTiger storage engine.	WiredTiger
AutoRenew	string	No	The storage engine of the instance. Set the value to WiredTiger. Note When you call this operation to clone an instance, the value of this parameter must be the same as that of the source instance. For more information about the constraints on storage engines and versions, see Versions and storage engines.	WiredTiger
ProtocolType	string	No	Specifies whether to enable auto-renewal for the instance. Valid values: true: enables auto-renewal. false: disables auto-renewal. In this case, you must manually renew the instance. This is the default value. Note This parameter is valid and optional only when the ChargeType parameter is set to PrePaid. Valid values: mongodb : The MongoDB protocol. dynamodb : The DynamoDB protocol.	true
Mongos	array<object>	Yes	The access protocol type. Valid values: mongodb: MongoDB protocol. dynamodb: DynamoDB protocol.	mongodb
	object	Yes	The information about the mongos nodes.
Class	string	Yes	The specifications of the mongos node. For more information, see Sharded cluster instance types. Note N in the parameter name specifies the sequence number of the mongos node. For example, Mongos.2.Class specifies the specifications of the second mongos node. Valid values of N: 2 to 32.	mdb.shard.2x.xlarge.d
ReplicaSet	array<object>	Yes	The information about the mongos nodes.
	object	No	The information about the mongos nodes.
Class	string	Yes	The specifications of the mongos node. For more information, see Sharded cluster instance types. Note N in the parameter name specifies the Nth mongos node. For example, Mongos.2.Class specifies the specifications of the second mongos node. Valid values of N: 2 to 32.	mdb.shard.2x.xlarge.d
ReadonlyReplicas	integer	No	The number of read-only nodes in the shard node. Valid values: 0 to 5. Default value: 0. Note N in the parameter name specifies the sequence number of the shard node. For example, ReplicaSet.2.ReadonlyReplicas specifies the number of read-only nodes in the second shard node.	0
Storage	integer	Yes	The storage capacity of the shard node. Unit: GB. Note The valid values are subject to the instance specifications. For more information, see Sharded cluster instance types. N in the parameter name specifies the sequence number of the shard node. For example, ReplicaSet.2.Storage specifies the storage capacity of the second shard node.	10
ConfigServer	array<object>	Yes	The information about the shard nodes.
	object	No	The information about the shard nodes.
Class	string	Yes	The specifications of the shard node. For more information, see Sharded cluster instance types. Note N in the parameter name specifies the Nth shard node. For example, ReplicaSet.2.Class specifies the specifications of the second shard node. Valid values of N: 2 to 32.	dds.shard.standard
Storage	integer	Yes	The storage capacity of the shard node. Unit: GB. Note The valid values are subject to the instance specifications. For more information, see Sharded cluster instance types. N in the parameter name specifies the Nth shard node. For example, ReplicaSet.2.Storage specifies the storage capacity of the second shard node.	10
SecondaryZoneId	string	No	The information about the Configserver node.	cn-hangzhou-h
HiddenZoneId	string	No	The resource group ID. For more information, see View the basic information of a resource group.	rg-acfmyiu4ekp****
StorageType	string	No	The secondary zone 1 for multi-zone deployment. Valid values: cn-hangzhou-g: Hangzhou Zone G. cn-hangzhou-h: Hangzhou Zone H. cn-hangzhou-i: Hangzhou Zone I. cn-hongkong-b: Hong Kong (China) Zone B. cn-hongkong-c: Hong Kong (China) Zone C. cn-hongkong-d: Hong Kong (China) Zone D. cn-wulanchabu-a: Ulanqab Zone A. cn-wulanchabu-b: Ulanqab Zone B. cn-wulanchabu-c: Ulanqab Zone C. ap-southeast-1a: Singapore Zone A. ap-southeast-1b: Singapore Zone B. ap-southeast-1c: Singapore Zone C. ap-southeast-5a: Jakarta Zone A. ap-southeast-5b: Jakarta Zone B. ap-southeast-5c: Jakarta Zone C. eu-central-1a: Frankfurt Zone A. eu-central-1b: Frankfurt Zone B. eu-central-1c: Frankfurt Zone C. Note This parameter is valid only when the instance uses cloud disks. The value of this parameter cannot be the same as the value of ZoneId or HiddenZoneId. For more information about the multi-zone deployment policy for sharded cluster instances, see Create a multi-zone sharded cluster instance.	cn-hangzhou-h
GlobalSecurityGroupIds	string	No	The secondary zone 2 for multi-zone deployment. Valid values: cn-hangzhou-g: Hangzhou Zone G. cn-hangzhou-h: Hangzhou Zone H. cn-hangzhou-i: Hangzhou Zone I. cn-hongkong-b: Hong Kong (China) Zone B. cn-hongkong-c: Hong Kong (China) Zone C. cn-hongkong-d: Hong Kong (China) Zone D. cn-wulanchabu-a: Ulanqab Zone A. cn-wulanchabu-b: Ulanqab Zone B. cn-wulanchabu-c: Ulanqab Zone C. ap-southeast-1a: Singapore Zone A. ap-southeast-1b: Singapore Zone B. ap-southeast-1c: Singapore Zone C. ap-southeast-5a: Jakarta Zone A. ap-southeast-5b: Jakarta Zone B. ap-southeast-5c: Jakarta Zone C. eu-central-1a: Frankfurt Zone A. eu-central-1b: Frankfurt Zone B. eu-central-1c: Frankfurt Zone C. Note This parameter is valid only when the instance uses cloud disks. The value of this parameter cannot be the same as the value of ZoneId or SecondaryZoneId. For more information about the multi-zone deployment policy for sharded cluster instances, see Create a multi-zone sharded cluster instance.	cn-hangzhou-i
Tag	array<object>	No	The storage type. Valid values: cloud_essd1: PL1 ESSD. cloud_essd2: PL2 ESSD. cloud_essd3: PL3 ESSD. local_ssd: Local SSD. Note Instances of version 4.4 or later support only cloud disks. If you do not specify this parameter, cloud_essd1 is selected by default. Instances of version 4.2 or earlier support only local disks. If you do not specify this parameter, local_ssd is selected by default.	cloud_essd1
	object	No
Key	string	No	The key of the tag. Note N in the parameter name specifies the sequence number of the 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 value of the tag. Note N in the parameter name specifies the sequence number of the 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
Encrypted	boolean	No	The global IP address whitelist templates of the instance. Separate multiple templates with commas (,). Each template must be unique.	g-qxieqf40xjst1ngpr3jz
EncryptionKey	string	No	The custom tags.	2axxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ProvisionedIops	integer	No	Specifies whether to enable cloud disk encryption.	true
SrcRegion	string	No	The custom key ID.	2axxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
BackupId	string	No	The provisioned IOPS.	1960
RestoreType	string	No	The region of the source instance. Note This parameter is required when the backup restoration type is rebuilding a deleted instance. This parameter is required when the backup restoration type is cloning from a geo-redundant backup. Valid values: 0 1 2 3 4	cn-beijing
DestRegion	string	No	The cluster backup ID. Note This parameter is required only when RestoreType is set to 2 or 3.	cb-xxx

Response elements

Element	Type	Description	Example
	object	The response information.
DBInstanceId	string	The instance ID.	dds-bp114f14849d****
OrderId	string	The order ID.	21010996721****
RequestId	string	The request ID.	D8F1D721-6439-4257-A89C-F1E8E9C9****

Examples

Success response

JSON format

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

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	InvaliadParameter.ShardsCount.LessThanSrc	The specified number of shards is less than that of source instance.
400	ORDER.ACCOUNT_INFORMATION_INCOMPLETE	Your information is incomplete. Complete your information before ordering.
400	InvalidRegion.Format	Specified Region is not valid.
400	Zone.Closed	The specified zone is closed.
400	TokenServiceError	The request token is duplicated.
400	InvalidParam	Param not valid.
400	InvalidEngineVersion.Malformed	Specified engine version is not valid.	The instance version information is empty or invalid.
400	InvalidParameters.Format	Specified parameters is not valid.	The parameter entered is invalid.
400	RestoreTypeNotSupported	The specified restoreType is not supported for the instance, check the input parameters 'RestoreType/BackupID/RestoreTime'.	The specified restoreType is not supported for the instance, check the input parameters 'RestoreType/BackupID/RestoreTime'.
500	VpcServiceError	Invoke vpc service error.	An error occurred when calling the VPC service.
403	InvalidBackupLogStatus	Current backup log enable status does not support this operation.
403	ReduceDiskNotSupport	Reduce disk size is not supported in clone/restore.	Reduce disk size is not supported in clone/restore.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.