You can call this operation to query one or more Block Storage devices you created, including cloud disks and local disks.

Description

  • You can specify multiple request parameters such as RegionId, ZoneId, DiskIds, and InstanceId. Specified parameters have logical AND relations.
  • The DiskIdsvalue is a JSON array. If this parameter is not specified, it will not be included in the filtering conditions. If the DiskIds parameter is set to an empty JSON array, it is regarded as an effective filtering condition and an empty result is returned.

When calling an API operation through Alibaba Cloud CLI, specify request parameter values of different data types in required formats. For more information, see CLI parameter formats.

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
RegionId String Yes cn-hangzhou

The region ID of the Block Storage device. You can call the DescribeRegions operation to query the most recent region list.

Action String No DescribeDisks

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

For API requests using the HTTP and HTTPS methods, the Action parameter is required.

AdditionalAttributes.N RepeatList No null

Other attribute values.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure compatibility.
AutoSnapshotPolicyId String No sp-m5e2w2jutw8bv31*****

The ID of the automatic snapshot policy.

Category String No all

The category of the disk. Valid values:

  • all: all disks
  • cloud: basic disk
  • cloud_efficiency: ultra disk
  • cloud_ssd: standard SSD
  • cloud_essd: enhanced SSD
  • local_ssd_pro: I/O-intensive local disk
  • local_hdd_pro: throughput-intensive local disk
  • ephemeral: phased-out local disk
  • ephemeral_ssd: phased-out local SSD

Default value: all

DeleteAutoSnapshot Boolean No false

Specifies whether to delete the automatic snapshots when the disk is released.

Default value: false

DeleteWithInstance Boolean No false

Specifies whether the disk is released together with the instance. Valid values:

  • true: The disk is released together with the instance.
  • false: The disk is not released together with the instance but is retained as a pay-as-you-go data disk.

Default value: false

DiskChargeType String No PostPaid

The billing method of the disk. Valid values:

  • PrePaid: subscription
  • PostPaid: pay-as-you-go
DiskIds String No ["d-bp67acfmxazb4ph***", "d-bp67acfmxazb4pi***", … "d-bp67acfmxazb4pj***"]

The IDs of the disks. It can be a JSON array that consists of disk IDs. Separate multiple disk IDs with commas (,). A maximum of 100 disk IDs can be entered at a time.

DiskName String No JoshuaFinance

The name of the disk.

DiskType String No all

The type of the disk. Valid values:

  • all: system disk and data disk
  • system: system disk
  • data: data disk

Default value: all

DryRun Boolean No false

Specifies whether to check the request only. Valid values:

  • true: The request is checked but resources are not queried. Check items include whether your AccessKey pair is valid, whether RAM users are authorized, and whether the required parameters are specified. If the check fails, the corresponding error message is returned. If the check succeeds, theDryRunOperation error code is returned.
  • false: The request is checked, and a 2XX HTTP status code is returned and resources are queried if the check succeeds.

Default value: false

EnableAutomatedSnapshotPolicy Boolean No false

Specifies whether to query the disks to which automatic snapshot policies are applied.

Default value: false

EnableShared Boolean No false

Specifies whether the disk is a Shared Block Storage device.

Encrypted Boolean No false

Specifies whether to query only encrypted disks.

Default value: false

Filter.1.Key String No CreationStartTime

A filter key used to query resources. Valid value: CreationStartTime.

Filter.1.Value String No 2017-12-05T22:40:00Z

A filter value used to query resources. The parameter value must be the start time when the resource was created (CreationStartTime).

Filter.2.Key String No CreationEndTime

A filter key used to query resources. Valid value: CreationEndTime.

Filter.2.Value String No 2017-12-06T22:40:00Z

A filter value used to query resources. The parameter value must be the end time when the resource was created (CreationEndTime).

InstanceId String No i-bp67acfmxazb4ph***

The ID of the instance to which the disk is attached.

KMSKeyId String No 0e478b7a-4262-4802-b8cb-00d3fb408***

The ID of the KMS key used by the disk.

LockReason String No recycling

The reason why the disk is locked. Valid values:

  • financial: The disk is locked due to overdue payments.
  • security: The disk is locked for security reasons.
  • recycling: The preemptible instance is locked and pending for release.
  • dedicatedhostfinancial: The instance is locked because of overdue payments on the dedicated host.
PageNumber Integer No 1

The number of the page to return.

Pages start from page 1.

Default value: 1

PageSize Integer No 10

The number of entries to return on each page.

Valid values: 1 to 100

Default value: 10

Portable Boolean No false

Specifies whether the disk is removable. Valid values:

  • true: The disk is removable. A removable disk can exist independently and can be attached to or detached from an instance within the same zone.
  • false: The disk is not removable. A disk that is not removable cannot exist independently, and can only be created or released together with its attached instance.

The following disks whose Portable attribute is false have the same lifecycles as their attached instances:

  • Local disks
  • Local SSDs
  • System disks
  • Subscription data disks
ResourceGroupId String No rg-bp67acfmxazb4ph***

The ID of the resource group to which the disk belongs.

SnapshotId String No s-bp67acfmxazb4ph***

The ID of the snapshot used to create the disk.

Status String No All

The status of the disk. For more information, see Basic disk status. Valid values:

  • In_use
  • Available
  • Attaching
  • Detaching
  • Creating
  • ReIniting
  • All

Default value: All

Tag.N.Key String No FinanceJoshua

The key of the Nth tag of the disk. Valid values of N: 1 to 20.

Tag.N.Value String No FinanceDept

The value of the Nth tag of the disk. Valid values of N: 1 to 20.

Tag.N.key String No null

The key of the Nth tag of the disk.

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 null

The value of the Nth tag of the disk.

Note This parameter will be removed in the future. We recommend that you use the Tag.N.Value parameter to ensure compatibility.
ZoneId String No cn-hangzhou-g

The ID of the zone.

Response parameters

Parameter Type Example Description
Disks Array

An array of information about the disks.

Disk

An array of information about the disk.

AttachedTime String 2018-01-01T01:04:22Z

The time when the disk was attached. The time follows the ISO 8601 standard in the yyyy-MM-ddThh:mm:ssZ format. The time is displayed in UTC.

The parameter value is valid only when Status is set to Available.

AutoSnapshotPolicyId String sp-bp67acfmxazb4ph***

The ID of the automatic snapshot policy applied to the disk.

Category String cloud_ssd

The category of the disk. Valid values:

  • cloud: basic disk
  • cloud_efficiency: ultra disk
  • cloud_ssd: standard SSD
  • cloud_essd: enhanced SSD
  • local_ssd_pro: I/O-intensive local disk
  • local_hdd_pro: throughput-intensive local disk
  • ephemeral: phased-out local disk
  • ephemeral_ssd: phased-out local SSD
CreationTime String 2018-01-01T01:01:22Z

The time when the disk was created.

DeleteAutoSnapshot Boolean false

Indicates whether the automatic snapshots are deleted when the disk is released. Valid values:

  • true: The automatic snapshots of the disk are deleted when the disk is released.
  • false: The automatic snapshots of the disk are retained when the disk is released.

Snapshots created through the CreateSnapshot operation or the console are retained permanently and not affected by this parameter setting.

DeleteWithInstance Boolean true

Indicates whether the disk is released together with the instance. Valid values:

  • true: The disk is released together with the instance.
  • false: The disk is retained when the instance is released.
Description String FinanceDept

The description of the disk.

DetachedTime String 2018-01-08T01:01:22Z

The time when the disk was detached.

The parameter value is valid only when Status is set to Available.

Device String /dev/xvdb

The device name of the disk on its attached instance, such as /dev/xvdb.

It is null unless Status is set to In_use.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure compatibility.
DiskChargeType String PostPaid

The billing method of the disk. Valid values:

  • PrePaid: subscription
  • PostPaid: pay-as-you-go
DiskId String d-bp18um4r4f2fve242***

The ID of the disk.

DiskName String FinanceDeptJoshua

The name of the disk.

EnableAutomatedSnapshotPolicy Boolean false

Indicates whether an automatic snapshot policy was applied to the disk.

Encrypted Boolean false

Indicates whether the disk was encrypted.

ExpiredTime String 2018-01-10T01:01:22Z

The time when the subscription disk expires.

IOPS Integer 4000

The number of input/output operations per second (IOPS). Unit: times/s.

IOPSRead Integer 2000

The number of I/O reads per second. Unit: times/s.

IOPSWrite Integer 2000

The number of I/O writes per second. Unit: times/s.

ImageId String m-bp13aqm171qynt3u***

The ID of the image from which the disk was created. It is null unless the disk was created from an image. The value of this parameter will remain unchanged throughout the lifecycle of the disk.

InstanceId String i-bp1j4i2jdf3owlheb***

The ID of the instance to which the disk was attached.

It is null unless Status is set to In_use.

KMSKeyId String 0e478b7a-4262-4802-b8cb-00d3fb408***

The ID of the KMS key used by the disk.

MountInstanceNum Integer 1

The number of instances to which a Shared Block Storage device is attached.

MountInstances Array

An array of information about disks attached to instances.

MountInstance

An array of information about disks attached to the instance.

AttachedTime String 2017-12-05T2340:00Z

The time when the disk was attached. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Device String /dev/xvda

The mount point of the disk.

InstanceId String i-bp1j4i2jdf3owlheb***

The ID of the instance to which the disk was attached.

OperationLocks Array

The reasons why the disk was locked.

OperationLock

The reason why the disk was locked.

LockReason String security

The security reason why the disk was locked.

PerformanceLevel String PL2

The performance level of the enhanced SSD. Valid values:

  • PL1: A single enhanced SSD delivers up to 50,000 random read/write IOPS.
  • PL2: A single enhanced SSD delivers up to 100,000 random read/write IOPS.
  • PL3: A single enhanced SSD delivers up to 1,000,000 random read/write IOPS.
Portable Boolean false

Indicates whether the disk is removable.

ProductCode String jxsc000204

The product code in Alibaba Cloud Marketplace.

RegionId String cn-hangzhou

The region ID of the disk.

ResourceGroupId String rg-bp67acfmxazb4ph***

The ID of the resource group to which the disk belongs.

Size  Integer 2000

The size of the disk. Unit: GiB.

SourceSnapshotId String s-bp67acfmxazb4ph***

The ID of the snapshot used to create data disks.

For disks that are not created from snapshots, the value of this parameter is null. The value of this parameter will remain unchanged throughout the lifecycle of the disk.

Status String Available

The status of the disk. Valid values:

  • In_use
  • Available
  • Attaching
  • Detaching
  • Creating
  • ReIniting
Tags Array

An array of tags of the disk.

Tag

The tag of the disk.

TagKey String FinanceJoshua

The key of the tag.

TagValue String FinanceDept

The value of the tag.

Type String data

The type of the disk. Valid values:

  • system: system disk
  • data: data disk
ZoneId String cn-hangzhou-g

The zone ID of the disk.

PageNumber Integer 1

The page number of the returned page.

PageSize Integer 1

The number of entries returned per page.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

TotalCount Integer 76

The total number of entries returned.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=DescribeDisks
&RegionId=cn-hangzhou
&PageNumber=1
&PageSize=1
&<Common request parameters>

Sample success responses

XML format

<DescribeDisksResponse>
      <PageNumber>1</PageNumber>
      <TotalCount>76</TotalCount>
      <PageSize>1</PageSize>
      <RequestId>C74847CB-9B69-4360-9969-3595F2B6B9C1</RequestId>
      <Disks>
            <Disk>
                  <DiskChargeType>PostPaid</DiskChargeType>
                  <ImageId>centos_7_06_64_20G_alibase_20190711.vhd</ImageId>
                  <Device>/dev/xvda</Device>
                  <DetachedTime></DetachedTime>
                  <Type>system</Type>
                  <InstanceId>i-bp1j4i2jdf3owlheb***</InstanceId>
                  <Encrypted>false</Encrypted>
                  <ZoneId>cn-hangzhou-f</ZoneId>
                  <EnableAutoSnapshot>true</EnableAutoSnapshot>
                  <AttachedTime>2019-11-11T08:35:32Z</AttachedTime>
                  <PerformanceLevel></PerformanceLevel>
                  <SourceSnapshotId></SourceSnapshotId>
                  <DeleteAutoSnapshot>false</DeleteAutoSnapshot>
                  <KMSKeyId></KMSKeyId>
                  <Size>40</Size>
                  <Description></Description>
                  <BdfId></BdfId>
                  <ProductCode></ProductCode>
                  <Portable>false</Portable>
                  <EnableAutomatedSnapshotPolicy>false</EnableAutomatedSnapshotPolicy>
                  <ResourceGroupId></ResourceGroupId>
                  <DiskName></DiskName>
                  <StorageSetId></StorageSetId>
                  <AutoSnapshotPolicyId></AutoSnapshotPolicyId>
                  <CreationTime>2019-11-11T08:35:29Z</CreationTime>
                  <MountInstances>
            </MountInstances>
                  <Status>In_use</Status>
                  <Tags>
                        <Tag>
                              <TagValue>FinanceDept</TagValue>
                              <TagKey>FinanceJoshua</TagKey>
                        </Tag>
                  </Tags>
                  <Category>cloud_efficiency</Category>
                  <RegionId>cn-hangzhou</RegionId>
                  <DeleteWithInstance>true</DeleteWithInstance>
                  <OperationLocks>
            </OperationLocks>
                  <ExpiredTime>2999-09-08T16:00Z</ExpiredTime>
                  <DiskId>d-bp18um4r4f2fve242***</DiskId>
            </Disk>
      </Disks>
</DescribeDisksResponse>

JSON format

{
	"PageNumber":1,
	"TotalCount":76,
	"PageSize":1,
	"RequestId":"C74847CB-9B69-4360-9969-3595F2B6B9C1",
	"Disks":{
		"Disk":[
			{
				"DiskChargeType":"PostPaid",
				"ImageId":"centos_7_06_64_20G_alibase_20190711.vhd",
				"Device":"/dev/xvda",
				"DetachedTime":"",
				"Type":"system",
				"InstanceId":"i-bp1j4i2jdf3owlheb***",
				"Encrypted":false,
				"EnableAutoSnapshot":true,
				"ZoneId":"cn-hangzhou-f",
				"AttachedTime":"2019-11-11T08:35:32Z",
				"PerformanceLevel":"",
				"SourceSnapshotId":"",
				"DeleteAutoSnapshot":false,
				"KMSKeyId":"",
				"Size":40,
				"Description":"",
				"BdfId":"",
				"ProductCode":"",
				"Portable":false,
				"EnableAutomatedSnapshotPolicy":false,
				"ResourceGroupId":"",
				"DiskName":"",
				"StorageSetId":"",
				"AutoSnapshotPolicyId":"",
				"CreationTime":"2019-11-11T08:35:29Z",
				"Tags":{
					"Tag":[
						{
							"TagValue":"FinanceDept",
							"TagKey":"FinanceJoshua"
						}
					]
				},
				"Status":"In_use",
				"MountInstances":{
					"MountInstance":[]
				},
				"Category":"cloud_efficiency",
				"RegionId":"cn-hangzhou",
				"DeleteWithInstance":true,
				"OperationLocks":{
					"OperationLock":[]
				},
				"ExpiredTime":"2999-09-08T16:00Z",
				"DiskId":"d-bp18um4r4f2fve242***"
			}
		]
	}
}

Error codes

HTTP status code Error code Description Description
400 InvalidDiskType.ValueNotSupported The specified disk type is not supported. The error message returned because the specified disk type does not support the operation.
400 InvalidCategory.ValueNotSupported The specified disk category is not supported. The error message returned because the specified disk category does not support this operation.
400 InvalidStatus.ValueNotSupported The specified disk status is not supported. The error message returned because the operation is not supported while the disk is in the current state.
403 InvalidDiskIds.Malformed The amount of specified disk Ids exceeds the limit. The error message returned because the specified value of the DiskIds parameter is invalid.
404 InvalidDiskChargeType.NotFound The DiskChargeType does not exist in our records The error message returned because the specified disk type does not exist.
404 InvalidLockReason.NotFound The specified LockReason is not found The error message returned because the specified LockReason parameter does not exist.
404 InvalidFilterKey.NotFound The error message returned because the specified start time or end time is invalid.
404 InvalidFilterValue The error message returned because the format of the specified time is invalid.
400 InvalidTag.Mismatch The specified Tag.n.Key and Tag.n.Value are not match. The error message returned because the specified Tag.N.Key parameter does not correspond to the specified Tag.N.Value parameter.
400 InvalidTagCount The specified tags are beyond the permitted range. The error message returned because the number of specified tags exceeds the upper limit.
400 InvalidRegion.NotFound The specified parameter RegionId is not valid. The error message returned because the specified value of the RegionId parameter is invalid.
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.
400 InvalidZoneId.NotFound The zoneId provided does not exist in our records. The error message returned because the specified zone ID does not exist.
400 MissingParamter.RegionId The regionId should not be null. The error message returned because the RegionId parameter is not specified.
400 InvalidParameter.DiskIds The specified parameter diskIds is not valid. The error message returned because the specified value of the DiskIds parameter is invalid.
400 IncompleteParamter Some fields can not be null in this request. The error message returned because a required parameter is not specified.
400 InvalidParamter Some parameters are invalid in this request. The error message returned because the request contains invalid parameter values.
400 InvalidSnapshot.NotFound The specified parameter SnapshotId is not valid. The error message returned because the specified value of the SnapshotId parameter is invalid.
403 UserNotInTheWhiteList The user is not in volume white list. The error message returned because you are not in the Shared Block Storage whitelist. Submit a ticket.
404 InvalidDiskIds.ValueNotSupported The specified parameter "DiskIds" is not supported. The error message returned because the specified value of the DiskIds parameter is invalid.

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