Creates a snapshot for a disk.
Operation description
The local snapshot feature has been replaced by the snapshot instant access feature. Metric description is as follows:
If you used local snapshots before December 14, 2020, you can use the
Categoryparameter as Normal.If you did not use local snapshots before December 14, 2020, no additional configuration is required. New snapshots created for ESSD series disks (ESSD, ESSD AutoPL, ESSD Entry, and regional ESSD) are instantly active by default, and both manual snapshots and automatic snapshots are supported. The three snapshot instant access-related parameters
InstantAccess,InstantAccessRetentionDays, andDisableInstantAccessin API operations no longer take effect. TheDescribeSnapshotsandDescribeSnapshotGroupsAPI operations will include a new response parameter named Available to describe the active status of snapshots.
Before you begin:
-
Activate the snapshot feature. For more information, see Activate snapshots.
-
The disk must be in the In Use or Unattached state. Note the following items for different states:
If the disk is in the In Use state, the instance must be in the Running or Stopped state.
If the disk is in the Unattached state, the disk must have been previously attached to an ECS instance. Snapshots cannot be created for disks that have never been attached to an ECS instance.
When a disk is used to create a dynamic extended volume or a RAID array, use a snapshot-consistent group and enable application-consistent snapshots to back up data. Snapshot-consistent groups ensure write order consistency and crash consistency for data written to multiple disks in a business system. For more information, see Create a snapshot-consistent group and Create an application-consistent snapshot.
When you create a snapshot, take note of the following items:
-
Avoid creating snapshots during peak business hours. When a snapshot is being created, the I/O performance of the disk decreases by up to 10%, and read and write performance may be briefly affected.
-
If the snapshot has not been created, it cannot be used to create a custom image (CreateImage).
-
Incremental data generated by disk operations during snapshot creation is not backup to the snapshot.
-
If the disk is attached to an ECS instance, do not change the instance status during snapshot creation, such as stopping or restarting the ECS instance. Otherwise, the snapshot creation is failed.
-
A disk for which a snapshot is being created does not support scale-out. Wait until the snapshot is created before you execute the scale-out operation.
-
You can create snapshots for disks in the Expired (
Expired) state. If the disk reaches its expiration release time during snapshot creation, the disk is released and the snapshot in the Creating (Creating) state is also deleted. -
After a snapshot is created, the system calculates fees based on the snapshot size in each region separately. For more information, see Snapshot billing.
-
In the following scenarios, you cannot create a snapshot for the specified disk:
-
The number of manual snapshots retained for the disk has reached the upper limit. For more information, see Snapshot limits.
-
Snapshot creation has concurrency limits. Exceeding the limits causes creation failures. For more information, see Snapshot limits.
-
When you query ECS instance information, if the returned data contains
{"OperationLocks": {"LockReason" : "security"}}, all operations are prohibited.
-
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ecs:CreateSnapshot |
create |
*Disk
*Snapshot
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| DiskId |
string |
Yes |
The disk ID. |
d-bp1s5fnvk4gn2tws0**** |
| SnapshotName |
string |
No |
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 Note
The name cannot start with |
testSnapshotName |
| Description |
string |
No |
The description of the snapshot. The description must be 2 to 256 characters in length and cannot start with Default value: null. |
testDescription |
| RetentionDays |
integer |
No |
Settings for the retention period of the snapshot. Unit: days. Valid values: 1 to 65536. The snapshot is subject to automatic release when the retention period expires. Default value: null, which indicates that the snapshot is not subject to automatic release. |
30 |
| Category |
string |
No |
The snapshot type. Valid values:
Note
This parameter will be deprecated. Standard snapshots of enterprise SSDs have been upgraded to instant access by default. No additional configuration or fees are required. This applies to enterprise SSDs, ESSD AutoPL disks, ESSD Entry disks, and regional enterprise SSDs. Standard snapshots of standard SSDs are also active by default. |
Standard |
| ClientToken |
string |
No |
The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but make sure that the token 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. |
123e4567-e89b-12d3-a456-426655440000 |
| ResourceGroupId |
string |
No |
The ID of the resource group to which the snapshot belongs. |
rg-bp67acfmxazb4p**** |
| InstantAccess |
boolean |
No |
Specifies whether to enable the snapshot instant access feature. Valid values:
Default value: false. Note
This parameter is deprecated. Standard snapshots of enterprise SSDs have been upgraded to instant access by default. No additional configuration or fees are required. This applies to enterprise SSDs, ESSD AutoPL disks, ESSD Entry disks, and regional enterprise SSDs. Standard snapshots of standard SSDs are also active by default. |
false |
| InstantAccessRetentionDays |
integer |
No |
Settings for the retention period of the snapshot instant access feature. After the retention period expires, the snapshot is subject to automatic release. This parameter takes effect only when Default value: the same as the value of the Note
This parameter is deprecated. Standard snapshots of enterprise SSDs have been upgraded to instant access by default. No additional configuration or fees are required. This applies to enterprise SSDs, ESSD AutoPL disks, ESSD Entry disks, and regional enterprise SSDs. Standard snapshots of standard SSDs are also active by default. |
1 |
| Tag |
array<object> |
No |
The tags. |
|
|
object |
No |
The tags. |
||
| key |
string |
No |
The tag key of the snapshot. Note
For compatibility purposes, use the Tag.N.Key parameter. |
null |
| Key |
string |
No |
The tag key of 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 aliyun or acs:. The tag key cannot contain http:// or https://. |
TestKey |
| Value |
string |
No |
The tag value of the snapshot. Valid values of N: 1 to 20. The tag value can be an empty string. The tag value can be up to 128 characters in length and cannot contain http:// or https://. |
TestValue |
| value |
string |
No |
The tag value of the snapshot. Note
For compatibility purposes, use the Tag.N.Value parameter. |
null |
| StorageLocationArn |
string |
No |
Note
This parameter is not publicly available. |
null |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| SnapshotId |
string |
The snapshot ID. |
s-bp17441ohwka0yuh**** |
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
Examples
Success response
JSON format
{
"SnapshotId": "s-bp17441ohwka0yuh****",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. | |
| 400 | InvalidSnapshotName.Malformed | The specified SnapshotName is malformed. | |
| 400 | IncorrectInstanceStatus | The current status of the resource does not support this operation. | The resource is in a state that does not support the current operation. |
| 400 | DiskCategory.OperationNotSupported | The type of the specified disk does not support creating a snapshot. | The operation is not supported by the current disk category. |
| 400 | Duplicate.TagKey | The Tag.N.Key contain duplicate key. | The specified tag key already exists. Tag keys must be unique. |
| 400 | InvalidTagKey.Malformed | The specified Tag.n.Key is not valid. | The specified Tag.N.Key parameter is invalid. |
| 400 | InvalidTagValue.Malformed | The specified Tag.n.Value is not valid. | The specified tag value is invalid. |
| 400 | InvalidRetentionDays.Malformed | The specified RetentionDays is not valid. | The specified RetentionDays parameter is invalid. |
| 400 | CreateSnapshot.Failed | The process of creating snapshot is failed. | Failed to create the snapshot. |
| 500 | InternalError | The request processing has failed due to some unknown error. | |
| 403 | Throttling | Request was denied due to user flow control. | The request is throttled. Use the NextToken-based pagination method instead of the PageNumber-based pagination method. |
| 403 | IncorrectDiskStatus.CreatingSnapshot | A previous snapshot creation is in process. | |
| 403 | InstanceLockedForSecurity | The disk attached instance is locked due to security. | |
| 403 | IncorrectDiskStatus.NeverAttached | The specified disk has never been attached to any instance. | |
| 403 | QuotaExceed.Snapshot | The snapshot quota exceeds. | |
| 403 | IncorrectDiskStatus.NeverUsed | The specified disk has never been used after creating. | |
| 403 | CreateSnapshot.Failed | The process of creating snapshot is failed. | |
| 403 | DiskInArrears | The specified operation is denied as your disk has expired. | |
| 403 | DiskId.ValueNotSupported | The specified parameter diskid is not supported. | The specified EBS device category does not support the operation. |
| 403 | IncorrectDiskStatus | The current disk status does not support this operation. | |
| 403 | InvalidAccountStatus.NotEnoughBalance | Your account does not have enough balance. | |
| 403 | InvalidAccountStatus.SnapshotServiceUnavailable | Snapshot service has not been opened yet. | The operation is not supported while the snapshot service is not activated. |
| 403 | IncorrectInstanceStatus | The current status of the resource does not support this operation. | |
| 403 | IncorrectVolumeStatus | The current volume status does not support this operation. | The current state of the Shared Block Storage device does not support this operation. |
| 403 | IdempotentParameterMismatch | The specified clientToken is used. | The specified client token is already in use. |
| 403 | IncorrectDiskStatus.Invalid | The specified disk status is invalid. Restart the instance and try again. | |
| 403 | IncorrectDiskType.NotSupport | The specified device type is not supported. | 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. | |
| 403 | InvalidParameter.KMSKeyId.CMKUnauthorized | ECS tags must be added to the CMK. | ECS tags must be added to the CMK. |
| 403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | |
| 403 | InvalidParameter.KMSKeyId.KMSUnauthorized | ECS service does not have permission to access your KMS key. Please verify that the specified KMS key has authorized the ECS service. | |
| 403 | IdempotentProcessing | The previous idempotent request(s) is still processing. | A previous idempotent request is being processed. Try again later. |
| 403 | InvalidSnapshotCategory.Malformed | The specified Category is not valid. | The specified Category parameter is invalid. |
| 403 | InvalidAction.Unauthorized | The specified action is not valid. | The specified operation is invalid. |
| 403 | InvalidRegion.NotSupportSnapshotInstantAccessRegion | The snapshot InstantAccess is not supported for this region. | |
| 403 | InvalidCategoryAndInstantAccess.Malformed | The snapshot Category and InstantAccess can't be used together. | |
| 403 | DISK_HAS_CREATING_SNAPSHOT | The operation cannot be performed while a snapshot is being created for the disk. | |
| 403 | HibernationConfigured.InstanceOperationForbidden | The operation is not permitted due to limit of the hibernation configured instance. | The operation cannot be performed due to the limitations of instances for which the instance hibernation feature is enabled. |
| 403 | QuotaExceed.SnapshotQuota | The quota is insufficient. Please contact your channel partner to increase the quota. | |
| 403 | InvalidInstantAccessRetentionDays.Malformed | The specified InstantAccessRetentionDays is not valid. | The specified InstantAccessRetentionDays parameter has an invalid format. |
| 403 | CloudBoxNotSupportSnapshotWithInstantAccess | The specified disk in CloudBox does not support to create a snapshot with InstantAccess. | Disks in CloudBox do not support creating snapshots with the instant access feature. |
| 403 | InvalidOperation.UnfinishedEncryptedSnapshotCopy | This disk has unfinished encrypted copy snapshots in the target region. | The cloud disk has unfinished encrypted snapshot copy tasks. |
| 403 | QuotaExceed.ConcurrentSnapshotQuota | The number of snapshots being created for the disk %s has exceeded the concurrent quota (%s). Please wait for the previous snapshots to complete before trying again. | The number of snapshots being created for this disk has exceeded the concurrent quota. Please wait for the previous snapshots to complete before trying again. |
| 403 | InvalidClientToken.Malformed | The specified clientToken is improperly formatted. It must contain only ASCII characters and must not exceed 64 characters in length. | The specified clientToken is improperly formatted. It must contain only ASCII characters and must not exceed 64 characters in length. |
| 403 | InvalidParameter.UnauthorizedStorageLocationArn | The operation has failed due to lack of permission for the specified "StorageLocationArn". Please use a resource with appropriate permission for the operation. | The current operation failed because the specified StorageLocationArn has insufficient permissions. Contact the administrator of the resource to obtain the operation permissions. |
| 403 | InvalidStorageLocationArn.Malformed | The specified parameter StorageLocationArn is malformed. | |
| 403 | InvalidStatus.ResourceGroup | You cannot perform an operation on a resource group that is being created or deleted. | Operation not allowed while resource group is being created or deleted. |
| 403 | OperationDenied.QuotaExceed | The quota of tags on resource is beyond permitted range. | The maximum number of tags on resource is exceeded. |
| 404 | InvalidDiskId.NotFound | The specified DiskId does not exist. | The specified disk does not exist. Check whether the disk ID is correct. |
| 404 | InvalidDescription.Malformed | The specified description is malformed. | |
| 404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | The specified instanceId is invalid. |
| 404 | InvalidVolumeId.NotFound | The specified volume does not exist. | |
| 404 | InvalidResourceGroup.NotFound | The ResourceGroup provided does not exist in our records. | The specified resource group does not exist. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.