Creates a snapshot for a disk.

Description

When you call this operation, note that:

  • A maximum of 64 snapshots can be created for a single disk.
  • The instance to which the disk is attached must be in the Stopped (Stopped) or Running (Running) state. Otherwise, the snapshot cannot be created.
  • The disk for which you want to create a snapshot must be attached to an instance.
  • If the instance to which a specified disk is attached has never been started, the snapshot cannot be created.
  • If an ECS instance is locked by security control (the OperationLocks parameter is "LockReason" : "security"), no snapshots can be created for its attached disks.
  • If you have performed the RunInstances, ReplaceSystemDisk, or CreateDisk operation and data has not yet been loaded to the disk, no snapshots can be created. You can create a snapshot about one hour after you create an ECS instance or replace the system disk. The time to wait after you add a data disk before you can create a snapshot depends on the size of the disk data.
  • If snapshot creation is not completed, you cannot create another snapshot for the same disk.
  • If snapshot creation is not completed, this snapshot cannot be used to create a custom image (CreateImage).
  • It is allowed to create snapshots for an expired subscription cloud disk. Note that if you are creating snapshots while the cloud disk happens to being deleted, the snapshots that are in the progressing status are deleted at the same time.

Debugging

You can use API Explorer to perform debugging. API Explorer allows you to perform various operations to simplify API usage. For example, you can retrieve APIs, call APIs, and dynamically generate SDK example code.

Request parameters

Name Type Required Example Description
DiskId String Yes d-diskid1

The ID of the disk.

Action String No CreateSnapshot

The operation that you want to perform. Set the value to CreateSnapshot.

ClientToken String No 123e4567-e89b-12d3-a456-426655440000

A client token. It is used to ensure the idempotency of requests. The value of this parameter is generated by the client and is unique among different requests. The ClientToken parameter must be no more than 64 ASCII characters in length. For more information, see How to ensure idempotency.

Description String No FinanceDepet

The description of the snapshot. The description must be 2 to 256 characters in length and cannot start with http:// or https://.

Default value: null.

SnapshotName String No FinanceJoshua

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 snapshot names starting with auto are recognized as automatic snapshots.

Tag.N.Key String No FinanceDept

The tag key of the snapshot. Valid values of N: 1 to 20. It cannot be a null string. It can be a maximum of 64 characters in length. It cannot start with aliyun, acs:, http://, or https://.

Tag.N.Value String No FinanceDept.Joshua

The tag value of the snapshot. Valid values of N: 1 to 20. It can be a null string. It can be a maximum of 128 characters in length. It cannot start with aliyun, acs:, http://, or https://.

Tag.N.key String No FinanceDept

The tag key of the snapshot.

Note This parameter will be removed in the future. We recommend that you use the Tag.N.Key parameter to ensure compatibility.
Tag.N.value String No FinanceDept.Joshua

The tag value of the snapshot.

Note This parameter will be removed in the future. We recommend that you use the Tag.N.Value parameter to ensure compatibility.

Response parameters

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

The ID of the request.

SnapshotId String s-snapshotid1

The ID of the snapshot.

Examples

Sample requests

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

Successful response examples

XML format

<CreateSnapshotResponse>
  <RequestId>C8B26B44-0189-443E-9816-D951F59623A9</RequestId>
  <SnapshotId>s-923FE2BF0</SnapshotId>
</CreateSnapshotResponse>

JSON format

{
	"RequestId":"C8B26B44-0189-443E-9816-D951F59623A9",
	"SnapshotId":"s-923FE2BF0"
}

Error codes

HTTP status code Error code Error message Description
404 InvalidDescription.Malformed The specified description is wrongly formed. The error message returned when the specified description is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://.
403 QuotaExceed.Snapshot The snapshot quota exceeds. The error message returned when the snapshot quota has been exhausted. To store new snapshots, you can delete existing snapshots without affecting your business.
403 DiskInArrears The specified operation is denied as your disk has expired. The error message returned when the disk has expired due to overdue payments.
403 DiskId.ValueNotSupported The specified parameter diskid is not supported. The error message returned when the specified disk does not support this operation.
403 InvalidAccountStatus.NotEnoughBalance Your account does not have enough balance. The error message returned when your account balance is insufficient. You must top up your account before proceeding.
404 InvalidVolumeId.NotFound The specified volume does not exist. The error message returned when the specified shared block storage does not exist. Check whether the shared block storage is correct.
403 IdempotentParameterMismatch The specified clientToken is used. The error message returned when 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 when 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 when the specified disk type does not support this operation.
403 IncorrectDiskStatus.Transferring The specified device is transferring, you can retry after the process is finished. The error message returned when the specified disk is currently being migrated. Try again after the migration has completed.

View error codes