CreateSnapshot - API Reference| Alibaba Cloud Documentation Center

Creates a snapshot for a disk.

Description

The local snapshot feature is replaced by the instant access feature.

If you have used the local snapshot feature before December 14, 2020, you can use the Category or InstantAccess parameter normally. Take note of the following items:
- The Category and InstantAccess parameters cannot be specified at the same time.
- If neither of the Category and InstantAccess parameters is specified, normal snapshots are created.
If you have not used the local snapshot feature before December 14, 2020, you can use the InstantAccess parameter and cannot use the Category parameter.

In the following scenarios, you cannot create snapshots for a disk:

The number of manual snapshots of the disk has reached 256.
A snapshot is being created for the disk.
The Elastic Compute Service (ECS) instance to which the disk is attached has never been started.
The instance to which the disk is attached is not in the Stopped (Stopped) or Running (Running) state.
If the response contains {"OperationLocks": {"LockReason" : "security"}} when you query the information of the instance, the instance is locked for security reasons and all operations are prohibited on it.

When you create a snapshot, take note of the following items:

If a snapshot is being created, you cannot use this snapshot to create a custom image by calling the CreateImage operation.
When a snapshot is being created for a disk that is attached to an instance, do not change the instance state.
You can create snapshots for a disk that is in the Expired (Expired) state. If the release time scheduled for a disk arrives when a snapshot is being created for the disk, the snapshot is in the Creating (Creating) state and is deleted when the disk is released.

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	CreateSnapshot	The operation that you want to perform. Set the value to CreateSnapshot.
DiskId	String	Yes	d-bp1s5fnvk4gn2tws0****	The ID of the disk.
SnapshotName	String	No	testSnapshotName	The name of the snapshot. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with `http://` or `https://`. It can contain letters, digits, colons (:), underscores (_), and hyphens (-). It cannot start with `auto` because snapshots whose names start with auto are recognized as automatic snapshots.
Description	String	No	testDescription	The description of the snapshot. The description must be 2 to 256 characters in length and cannot start with `http://` or `https://`. This parameter is empty by default.
RetentionDays	Integer	No	30	The retention period of the snapshot. Valid values: 1 to 65536. Unit: days. The snapshot is automatically released when the retention period expires. This parameter is empty by default, which indicates that the snapshot is not automatically released.
Category	String	No	Standard	The type of the snapshot. Valid values: Standard: normal snapshot Flash: local snapshot Note This parameter will be removed in the future. We recommend that you use the `InstantAccess` parameter to ensure future compatibility. This parameter and the `InstantAccess` parameter cannot be specified at the same time. For more information, see the "Description" section in this topic.
ClientToken	String	No	123e4567-e89b-12d3-a456-426655440000	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 make sure that it is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.
ResourceGroupId	String	No	rg-bp67acfmxazb4p****	The ID of the resource group to which to assign the snapshot.
InstantAccess	Boolean	No	false	Specifies whether to enable the instant access feature. Valid values: true: enables the instant access feature. This feature can be enabled only for enhanced SSDs (ESSDs). Note After the instant access feature is enabled, the snapshot can be used to roll back disks or create disks across zones even when the snapshot is being created. This feature ensures instant access to a new snapshot for an ESSD regardless of the ESSD size. false: does not enable the instant access feature. If InstantAccess is set to false, a normal snapshot is created. Default value: false. Note This parameter and the `Category` parameter cannot be specified at the same time. For more information, see the "Description" section in this topic.
InstantAccessRetentionDays	Integer	No	1	The validity period of the instant access feature. When the validity period ends, the feature is disabled and the instant access (IA) snapshot is automatically released. This parameter takes effect only when `InstantAccess` is set to true. Unit: days. Valid values: 1 to 65535. By default, the value of this parameter is the same as that of `RetentionDays`.
Tag.N.key	String	No	null	The key of tag N to add to the snapshot. Note This parameter will be removed in the future. We recommend that you use the Tag.N.Key parameter to ensure future compatibility.
Tag.N.Key	String	No	TestKey	The key of tag N to add to the snapshot. Valid values of N: 1 to 20. The tag key cannot be an empty string. The tag key can be up to 128 characters in length and cannot start with acs: or aliyun. It cannot contain http:// or https://.
Tag.N.Value	String	No	TestValue	The value of tag N to add to the snapshot. Valid values of N: 1 to 20. The tag value can be an empty string. It can be up to 128 characters in length and cannot start with acs: or contain http:// or https://.
Tag.N.value	String	No	null	The value of tag N to add to the snapshot. Note This parameter will be removed in the future. We recommend that you use the Tag.N.Value parameter to ensure future compatibility.

Response parameters


Parameter	Type	Example	Description
SnapshotId	String	s-bp17441ohwka0yuh****	The ID of the snapshot.
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E	The ID of the request.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=CreateSnapshot
&DiskId=d-bp1s5fnvk4gn2tws0****
&SnapshotName=testSnapshotName
&Description=testDescription
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&Tag.1.Key=TestKey
&Tag.1.Value=TestValue
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateSnapshotResponse>
        <RequestId>C8B26B44-0189-443E-9816-D951F59623A9</RequestId>
        <SnapshotId>s-bp17441ohwka0yuh****</SnapshotId>
</CreateSnapshotResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "C8B26B44-0189-443E-9816-D951F59623A9",
  "SnapshotId" : "s-bp17441ohwka0yuh****"
}

Error codes


HTTP status code	Error code	Error message	Description
400	InvalidParameter.KMSKeyId.NotFound	The specified KMSKeyId does not exist.	The error message returned because the specified KMSKeyId parameter does not exist.
400	InvalidSnapshotName.Malformed	The specified SnapshotName is wrongly formed.	The error message returned because the specified SnapshotName parameter is invalid.
400	IncorrectInstanceStatus	The current status of the resource does not support this operation.	The error message returned because the operation is not supported while the resource is in the current state.
400	DiskCategory.OperationNotSupported	The operation is not supported to the specified disk due to its disk category	The error message returned because the specified disk category does not support this operation.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	The error message returned because the specified tag key already exists. Tag keys must be unique.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	The error message returned because the specified Tag.N.Key parameter is invalid.
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.	The error message returned because the specified Tag.N.Value parameter is invalid.
400	InvalidRetentionDays.Malformed	The specified RetentionDays is not valid.	The error message returned because the specified RetentionDays parameter is invalid.
403	Throttling	Request was denied due to user flow control.	The error message returned because your request is throttled. Try again later.
403	IncorrectDiskStatus.CreatingSnapshot	A previous snapshot creation is in process.	The error message returned because another snapshot is being created for the disk. Wait until the snapshot is created and try again.
403	InstanceLockedForSecurity	The disk attached instance is locked due to security.	The error message returned because the instance to which the disk is attached is locked for security reasons.
403	IncorrectDiskStatus.NeverAttached	The specified disk has never been attached to any instance.	The error message returned because the removable disk has never been attached to instances and its data remains unchanged.
403	QuotaExceed.Snapshot	The snapshot quota exceeds.	The error message returned because the maximum number of snapshots has been reached. To create new snapshots, delete snapshots that are no longer needed.
403	IncorrectDiskStatus.NeverUsed	The specified disk has never been used after creating.	The error message returned because the specified disk has never been used and its data remains unchanged.
403	CreateSnapshot.Failed	The process of creating snapshot is failed.	The error message returned because the snapshot cannot be created.
403	DiskInArrears	The specified operation is denied as your disk has expired.	The error message returned because the disk has expired due to an overdue payment.
403	DiskId.ValueNotSupported	The specified parameter diskid is not supported.	The error message returned because the category of the specified Elastic Block Storage (EBS) device does not support this operation.
403	IncorrectDiskStatus	The current disk status does not support this operation.	The error message returned because the operation is not supported while the disk is in the current state. Make sure that the disk is usable and you have no overdue payments for it.
403	InvalidAccountStatus.NotEnoughBalance	Your account does not have enough balance.	The error message returned because your account balance is insufficient. Add funds to your account and try again.
403	InvalidAccountStatus.SnapshotServiceUnavailable	Snapshot service has not been opened yet.	The error message returned because the operation is not supported while the snapshot service is not activated.
403	IncorrectVolumeStatus	The current volume status does not support this operation.	The error message returned because the operation is not supported while the Shared Block Storage device is in the current state.
403	IdempotentParameterMismatch	The specified clientToken is used.	The error message returned because the specified client token is already in use.
403	IncorrectDiskType.NotSupport	The specified device type is not supported.	The error message returned because the specified disk type does not support the operation.
403	IncorrectDiskStatus.Transferring	The specified device is transferring, you can retry after the process is finished.	The error message returned because the specified disk is being migrated. Wait until the disk is migrated and try again.
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK needs to be enabled.	The error message returned because the customer master key (CMK) is not enabled when a Key Management Service (KMS) key ID is specified for a disk. You can call the DescribeKey operation of KMS to query the information of the specified CMK.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	ECS service have no right to access your KMS.	The error message returned because ECS is not authorized to access KMS resources.
403	IdempotentProcessing	The previous idempotent request(s) is still processing.	The error message returned because a previous idempotent request is being processed. Try again later.
403	QuotaExceed.Tags	%s	The error message returned because the number of specified tags exceeds the upper limit. %s is a variable. An error message is dynamically returned based on call conditions.
403	InvalidSnapshotCategory.Malformed	The specified Category is not valid.	The error message returned because the specified Category parameter is invalid.
403	IncorrectDiskStatus.Invalid	The specified disk status invalid, restart instance and try again.	The error message returned because the state of the specified disk is invalid. Restart the instance and try again.
404	InvalidDiskId.NotFound	The specified DiskId does not exist.	The error message returned because the specified disk does not exist. Check whether the disk ID is correct.
404	InvalidDescription.Malformed	The specified description is wrongly formed.	The error message returned because the specified Description parameter is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://.
404	InvalidInstanceId.NotFound	The specified InstanceId does not exist.	The error message returned because the specified instance ID does not exist. Check whether the instance ID is correct.
404	InvalidVolumeId.NotFound	The specified volume does not exist.	The error message returned because the specified Shared Block Storage device does not exist. Check whether the Shared Block Storage device ID is correct.
500	InternalError	The request processing has failed due to some unknown error.	The error message returned because an internal error has occurred. Try again later. If the error persists, submit a ticket.
500	InternalError	The request processing has failed due to some unknown error, exception or failure.	The error message returned because an internal error has occurred. Try again later. If the error persists, submit a ticket.

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