You can call this operation to create a snapshot for a disk.

Description

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

  • Number of manual snapshots for the disk has reached 256.
  • The previous snapshot is still being created.
  • The 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 message contains {"OperationLocks": {"LockReason" : "security"}} when you query ECS instance information, the instance is locked for security reasons and all operations are prohibited on the instance.

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

  • You can create a snapshot about one hour after you create an ECS instance or replace the system disk. The time to wait for after you add a data disk before you can create a snapshot depends on the size of the disk data.
  • If a snapshot is being created, this snapshot cannot be used to create a custom image (CreateImage).
  • If the disk has been attached to an ECS instance, do not change the instance status during snapshot creation.
  • You can create snapshots for a disk that is in the Expired (Expired) state. If the disk that is in the Expired state reaches its scheduled release time when a snapshot is being created for the disk, the snapshot that is in the Creating (Creating) state will also be 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 No CreateSnapshot

The operation that you want to perform. If you use a custom HTTP URL or HTTPS URL to make an API request, you must specify the Action parameter. Set the value to CreateSnapshot.

DiskId String Yes d-bp1s5fnvk4gn2tws03***

The ID of the disk.

SnapshotName String No Test

The name of the snapshot to be created. The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), and hyphens (-). The name must start with a letter but cannot start with http:// or https://.

It also cannot start with auto because snapshot names starting with auto are recognized as automatic snapshots.

Description String No Test

The description of the snapshot to be created. 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 to be created. Valid values: 1 to 65536. Unit: day. The snapshot will be automatically released when the retention period expires.

This parameter is empty by default, indicating that the snapshot will not be released automatically.

Category String No Standard

The type of the snapshot. Valid values:

  • Standard: normal snapshot
  • Flash: local snapshot
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 ensure that it is unique among different requests. The ClientToken value can only contain ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

Tag.N.value String No null

The value of tag N of the snapshot.

Note We recommend that you use the Tag.N.Value parameter to ensure future compatibility.
Tag.N.key String No null

The key of tag N of 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 Test

The key of tag N of the snapshot. Valid values of N: 1 to 20. It cannot be an empty string. The tag key can be up to 128 characters in length and cannot contain http:// or https://. It cannot start with acs: or aliyun.

Tag.N.Value String No Test

The value of tag N of the snapshot. Valid values of N: 1 to 20. It can be an empty string. The tag value can be up to 128 characters in length and cannot contain http:// or https://. It cannot start with acs:.

Response parameters

Parameter Type Example Description
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

SnapshotId String s-bp17441ohwka0yuhx***

The ID of the snapshot created.

Examples

Sample requests

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

Sample success responses

XML format

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

JSON format

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

Error codes

HTTP status code Error code Error message Description
404 InvalidDiskId.NotFound The specified DiskId does not exist. The error message returned because the specified DiskId parameter does not exist. Check whether the Disk ID is correct.
400 InvalidSnapshotName.Malformed The specified SnapshotName is wrongly formed. The error message returned because the specified SnapshotName parameter is invalid.
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://.
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.
403 IncorrectDiskStatus.CreatingSnapshot A previous snapshot creation is in process. The error message returned because another snapshot is being created. 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 to ensure security.
403 IncorrectDiskStatus.NeverAttached The specified disk has never been attached to any instance. The error message returned because the removable disk has not been attached to an instance and its content 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 unnecessary snapshots without affecting your business.
403 IncorrectDiskStatus.NeverUsed The specified disk has never been used after creating. The error message returned because the disk has not been used after being created and its content remains unchanged.
403 CreateSnapshot.Failed The process of creating snapshot is failed. The error message returned because the snapshot fails to 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 overdue payments.
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 problem persists, submit a ticket.
403 DiskId.ValueNotSupported The specified parameter diskid is not supported. The error message returned because the category of the specified Block Storage device does not support this operation.
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 the 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. Ensure that the disk is available and has no overdue payments.
403 InvalidAccountStatus.NotEnoughBalance Your account does not have enough balance. The error message returned because your account balance is insufficient. You must top up your account before proceeding.
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 enabled.
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified InstanceId parameter does not exist. Check whether the instance ID is correct.
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.
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 is correct.
403 IdempotentParameterMismatch The specified clientToken is used. The error message returned because the specified client token is already in use.
403 IncorrectDiskStatus.Invalid The specified device status invalid, restart instance and try again. The error message returned because the specified disk status is invalid. Restart the instance and try again.
403 IncorrectDiskType.NotSupport The specified device type is not supported. The error message returned because the operation is not supported by the specified disk type.
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.KMSUnauthorized ECS service have no right to access your KMS. The error message returned because ECS is not authorized to access your KMS resources.
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 problem persists, submit a ticket.
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.
403 IdempotentProcessing The previous idempotent request(s) is still processing. The error message returned because the previous idempotence request is being processed. Try again later.
403 QuotaExceed.Tags %s The error message returned because the maximum number of tags has been reached.

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