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

Description

  • Request parameters such as RegionId, ZoneId, DiskIds, and InstanceId act as filtering conditions and have an AND logical relationship with each other.
  • The DiskIds value is a JSON array. If the parameter is not specified, the filtering condition is not applied. If the DiskIds parameter is an empty array, the filtering condition is applied and an empty result is returned.

When you call an API operation by using Alibaba Cloud Command Line Interface (CLI), specify request parameter values of different data types in required formats. For more information, see CLI parameter format.

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 DescribeDisks

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

If you use a custom HTTP URL or HTTPS URL to make an API request, you must specify the Action parameter.

RegionId String Yes cn-hangzhou

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

ZoneId String No cn-hangzhou-g

The zone ID of the disk.

DiskIds String No ["d-bp67acfmxazb4p****", "d-bp67acfmxazb4g****"... "d-bp67acfmxazb4d****"]

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

InstanceId String No i-bp67acfmxazb4q****

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

DiskType String No all

The type of the disk to be queried. Valid values:

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

Default value: all.

Category String No all

The category of the disk. Valid values:

  • all: all disk categories
  • cloud: basic disk
  • cloud_efficiency: ultra disk
  • cloud_ssd: standard SSD
  • cloud_essd: enhanced SSD (ESSD)
  • 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.

Status String No All

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

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

Default value: All.

SnapshotId String No s-bp67acfmxazb4p****

The ID of the snapshot used to create the disk.

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 be attached to or detached from an instance within the same zone.

If the disk is of one of the following categories or types, the Portable parameter is set to false and the lifecycle of the disk is the same as that of the instance to which the disk is attached:

  • Local disk
  • Local SSD
  • System disk
  • Subscription data disk
DeleteWithInstance Boolean No false

Specifies whether to release the disk with the instance. Valid values:

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

Default value: false.

DeleteAutoSnapshot Boolean No false

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

Default value: false.

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.

Maximum value: 100.

Default value: 10.

DiskName String No DiskTestName

The name of the disk.

AutoSnapshotPolicyId String No sp-m5e2w2jutw8bv31****

The ID of the automatic snapshot policy.

EnableAutomatedSnapshotPolicy Boolean No false

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

Default value: false.

DiskChargeType String No PostPaid

The billing method of the disk. Valid values:

  • PrePaid: subscription
  • PostPaid: pay-as-you-go
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 due to overdue payments of the dedicated host.
Filter.1.Key String No CreationStartTime

The key of filter 1 used to query resources. Set the value to CreationStartTime.

Filter.2.Key String No CreationEndTime

The key of filter 2 used to query resources. Set the value to CreationEndTime.

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

The value of filter 1 used to query resources. The parameter value must be the start time of the resource creation.

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

The value of filter 2 used to query resources. The parameter value must be the end time of the resource creation.

Tag.N.value String No null

The value of tag N of the disk.

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

The key of tag N of the disk.

Note We recommend that you use the Tag.N.Key parameter to ensure compatibility.
Tag.N.Key String No TestKey

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

Tag.N.Value String No TestValue

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

ResourceGroupId String No rg-bp67acfmxazb4p****

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

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.

AdditionalAttributes.N RepeatList No null

The attribute N of the disk.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
DryRun Boolean No false

Specifies whether to check the validity of the request without actually making the request. Valid values:

  • true: The validity of 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 you do not have the required permissions to make this request, the corresponding error message is returned. If the check succeeds, the DryRunOperation error code is returned.
  • false: The request is made, and a 2XX HTTP status code is returned and resources are queried after the request is determined as valid.

Default value: false.

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

The ID of the KMS key used by the disk.

Response parameters

Parameter Type Example Description
Disks Array

An array consisting of Disk data.

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

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

This parameter is valid only when Status is set to Available.

AutoSnapshotPolicyId String sp-bp67acfmxazb4ph***

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

BdfId String hide
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 were deleted when the disk was released. Valid values:

  • true: The automatic snapshots of the disk were deleted when the disk was released.
  • false: The automatic snapshots of the disk were retained when the disk was released.

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

DeleteWithInstance Boolean true

Indicates whether the disk was released with the instance. Valid values:

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

The description of the disk.

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

The time when the disk was detached.

This parameter 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.

This parameter is valid only when Status is set to In_use. Otherwise, the parameter is empty.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future 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.

EnableAutoSnapshot Boolean false

Indicates whether a created automatic snapshot policy was applied to 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 expired.

IOPS Integer 4000

The number of input/output operations per second (IOPS).

IOPSRead Integer 2000

The number of I/O reads per second.

IOPSWrite Integer 2000

The number of I/O writes per second.

ImageId String m-bp13aqm171qynt3u***

The ID of the image used to create the instance. This parameter is empty 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.

This parameter is valid only when Status is set to In_use. Otherwise, the parameter is empty.

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 the Shared Block Storage device was attached.

MountInstances Array

An array consisting of MountInstance data.

MountInstance
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

An array consisting of OperationLock data.

OperationLock
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 ESSD 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 enterprise resource group to which the disk belongs.

SerialNumber String bp18um4r4f2fve2****

The serial number of the disk.

Size Integer 2000

The size of the disk. Unit: GiB.

SourceSnapshotId String s-bp67acfmxazb4ph***

The ID of the snapshot used to create the disk.

This parameter is empty unless the disk was created from a snapshot. 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
StorageSetId String ss-i-bp1j4i2jdf3owlheb***

The ID of the storage set.

StorageSetPartitionNumber Integer 11

The maximum number of partitions in a storage set.

Tags Array

An array consisting of Tag data.

Tag
TagKey String TestKey

The tag key of the disk.

TagValue String TestValue

The tag value of the disk.

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>PL2</PerformanceLevel>
                  <SerialNumber>bp18um4r4f2fve2****</SerialNumber>
                  <SourceSnapshotId>s-bp67acfmxazb4ph***</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,
                "ZoneId": "cn-hangzhou-f",
                "EnableAutoSnapshot": true,
                "AttachedTime": "2019-11-11T08:35:32Z",
                "PerformanceLevel": "PL2",
                "SerialNumber": "bp18um4r4f2fve2****",
                "SourceSnapshotId": "s-bp67acfmxazb4ph***",
                "DeleteAutoSnapshot": false,
                "KMSKeyId": "",
                "Size": 40,
                "Description": "",
                "BdfId": "",
                "ProductCode": "",
                "Portable": false,
                "EnableAutomatedSnapshotPolicy": false,
                "ResourceGroupId": "",
                "DiskName": "",
                "StorageSetId": "",
                "AutoSnapshotPolicyId": "",
                "CreationTime": "2019-11-11T08:35:29Z",
                "MountInstances": {
                    "MountInstance": []
                },
                "Status": "In_use",
                "Tags": {
                    "Tag": [
                        {
                            "TagValue": "FinanceDept",
                            "TagKey": "FinanceJoshua"
                        }
                    ]
                },
                "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 Error message Description
400 InvalidDiskType.ValueNotSupported The specified disk type is not supported. The error message returned because the specified DiskType parameter is not supported.
400 InvalidCategory.ValueNotSupported The specified disk category is not supported. The error message returned because the specified Category parameter is not supported.
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 maximum number of specified disks has been reached.
404 InvalidDiskChargeType.NotFound The DiskChargeType does not exist in our records The error message returned because the specified DiskChargeType parameter 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.
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 and Tag.N.Value parameters do not match.
400 InvalidTagCount The specified tags are beyond the permitted range. The error message returned because the maximum number of the specified tags has been reached.
400 InvalidRegion.NotFound The specified parameter RegionId is not valid. The error message returned because the specified 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 ZoneId parameter does not exist.
400 MissingParamter.RegionId The regionId should not be null. The error message returned because the required RegionId parameter is not specified.
400 InvalidParameter.DiskIds The specified parameter diskIds is not valid. The error message returned because the specified DiskIds parameter is invalid.
400 IncompleteParamter Some fields can not be null in this request. The error message returned because some required parameters are not specified.
400 InvalidParamter Some parameters are invalid in this request. The error message returned because the request parameters contain invalid parameters.
400 InvalidSnapshot.NotFound The specified parameter SnapshotId is not valid. The error message returned because the specified 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 DiskIds parameter is invalid.

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