Queries block storage devices that you created, including cloud disks and local disks.
Usage notes
You can configure multiple request parameters such as
RegionId
,ZoneId
,DiskIds
, andInstanceId
as filters. Configured parameters are evaluated by using the "AND" operator. If you specify more than one filter, the records that match all filters are returned.The value of the
DiskIds
parameter is a JSON array. If the DiskIds parameter is not configured, it is not used as a filter. If theDiskIds
parameter is set to an empty JSON array, it is regarded as a valid filter, and an empty result is returned.You can use one of the following methods to check the responses:
Method 1: Use
NextToken
to configure the query token. Set the value to theNextToken
value that was returned in the last call made to the DescribeDisks operation. Then, useMaxResults
to specify the maximum number of entries to return per page.Method 2: Configure the
PageSize
parameter to specify the number of entries to return per page, and configure thePageNumber
parameter to specify the page number to return.You can use only one of the preceding methods. If a large number of entries are to be returned, we recommend that you use Method 1. If the
NextToken
parameter is configured, thePageSize
andPageNumber
parameters do not take effect and theTotalCount
parameter in the response is invalid.
A cloud disk that has the multi-attach feature enabled can be attached to multiple instances. You can query the attachment information of the cloud disk based on the
Attachment
values in the response.
When you call an API operation by using Alibaba Cloud CLI, you must specify request parameter values of different data types in the required formats. For more information, see Parameter format overview.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
Action | String | Yes | DescribeDisks | The operation that you want to perform. Set the value to DescribeDisks. |
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. |
ZoneId | String | No | cn-hangzhou-g | The zone ID. |
DiskIds | String | No | ["d-bp67acfmxazb4p****", "d-bp67acfmxazb4g****", … "d-bp67acfmxazb4d****"] | The disk IDs. The value is a JSON array that consists of up to 100 disk IDs. Separate the 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. Valid values:
Default value: all. |
Category | String | No | all | The category of the disk. Valid values:
Default value: all. |
Status | String | No | All | The status of the cloud disk. For more information, see Disk states. Valid values:
Default value: All. |
SnapshotId | String | No | s-bp67acfmxazb4p**** | The ID of the snapshot used to create the cloud disk. |
Portable | Boolean | No | false | Specifies whether the disk is removable. Valid values:
The
|
DeleteWithInstance | Boolean | No | false | Specifies whether to release the cloud disk when its associated instance is released. Valid values:
Default value: false. |
DeleteAutoSnapshot | Boolean | No | false | Specifies whether to delete the auto snapshots of the cloud disk when the cloud disk is released.
Default value: false. |
PageNumber | Integer | No | 1 | The page number. Pages start from page 1. Default value: 1. |
PageSize | Integer | No | 10 | The number of entries per page. Maximum value: 100. Default value: 10. |
NextToken | String | No | AAAAAdDWBF2**** | The pagination token that is used in the next request to retrieve a new page of results. You must specify the token that is obtained from the previous query as the value of For information about how to check the responses returned by this operation, see the "Usage notes" section in this topic. |
MaxResults | Integer | No | 50 | The number of entries per page. Valid values: 10 to 500. Take note of the following items:
|
DiskName | String | No | testDiskName | The name of the disk. |
AutoSnapshotPolicyId | String | No | sp-m5e2w2jutw8bv31**** | The ID of the automatic snapshot policy that is applied to the cloud disk. |
EnableAutoSnapshot | Boolean | No | true | Specifies whether to enable the automatic snapshot policy feature for the cloud disk. Valid values:
Note By default, the automatic snapshot policy feature is enabled for created cloud disks. You need to only apply an automatic snapshot policy to a cloud disk before you can use the automatic snapshot policy. |
EnableAutomatedSnapshotPolicy | Boolean | No | false | Specifies whether an automatic snapshot policy is applied to the cloud disk. Valid values:
Default value: false. |
DiskChargeType | String | No | PostPaid | The billing method of the disk. Valid values:
|
LockReason | String | No | recycling | The reason why the disk is locked. Valid values:
|
Filter.1.Key | String | No | CreationStartTime | The key of filter 1 that is used to query resources. Set the value to |
Filter.2.Key | String | No | CreationEndTime | The key of filter 2 that is used to query resources. Set the value to |
Filter.1.Value | String | No | 2017-12-05T22:40Z | The value of filter 1 that is used to query resources. If you configure this parameter, you must also configure the |
Filter.2.Value | String | No | 2017-12-06T22:40Z | The value of filter 2 that is used to query resources. If you configure this parameter, you must also configure the |
ResourceGroupId | String | No | rg-bp67acfmxazb4p**** | The ID of the resource group to which the disk belongs. If you use this parameter to filter resources, the number of resources in a specified resource group cannot exceed 1,000. Note Resources in the default resource group cannot be filtered. |
EnableShared | Boolean | No | false | Specifies whether the disk is a Shared Block Storage device. |
Encrypted | Boolean | No | false | Specifies whether to query only encrypted cloud disks. Valid values:
Default value: false. |
DryRun | Boolean | No | false | Specifies whether to perform only a dry run, without performing the actual request. Valid values:
Default value: false. |
KMSKeyId | String | No | 0e478b7a-4262-4802-b8cb-00d3fb40**** | The ID of the Key Management Service (KMS) key used by the cloud disk. |
MultiAttach | String | No | Disabled | Specifies whether the multi-attach feature is enabled. Valid values:
The multi-attach feature is in invitational preview. To use this feature, submit a ticket. |
Tag.N.key | String | No | null | The key of tag N of the disk. Note We recommend that you use the other 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. If a single tag is specified to query resources, up to 1,000 resources that have this tag added are returned. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags added are returned. To query more than 1,000 resources with the specified tags, call the ListTagResources operation. |
Tag.N.Value | String | No | TestValue | The value of tag N of the disk. Valid values of N: 1 to 20. |
Tag.N.value | String | No | null | The value of tag N of the disk. Note We recommend that you use the other Tag.N.Value parameter to ensure compatibility. |
AdditionalAttributes.N | String | No | IOPS | The value of attribute N. Set the value to IOPS, which indicates the maximum input/output operations per second (IOPS) of the disk. |
Response parameters
Parameter | Type | Example | Description |
NextToken | String | AAAAAdDWBF2**** | The query token returned in this call. |
PageSize | Integer | 1 | The number of entries per page. |
PageNumber | Integer | 1 | The page number. |
RequestId | String | 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E | The request ID. |
TotalCount | Integer | 15 | The total number of entries returned. |
Disks | Array of Disk | Details about the disks. | |
Disk | |||
SerialNumber | String | bp18um4r4f2fve2**** | The serial number of the disk. |
CreationTime | String | 2021-06-07T06:08:54Z | The time when the disk was created. |
Status | String | In_use | The status of the cloud disk. Valid values:
|
Type | String | system | The type of the disk. Valid values:
|
PerformanceLevel | String | PL0 | The performance level of the ESSD. Valid values:
|
BdfId | String | null | This parameter is in invitational preview and is not publicly available. |
EnableAutoSnapshot | Boolean | false | Indicates whether the automatic snapshot policy feature is enabled for the cloud disk. |
StorageSetId | String | ss-i-bp1j4i2jdf3owlhe**** | The storage set ID. |
StorageSetPartitionNumber | Integer | 11 | The maximum number of partitions in the storage set. |
DiskId | String | d-bp18um4r4f2fve24**** | The disk ID. |
DeleteAutoSnapshot | Boolean | false | Indicates whether the auto snapshots of the cloud disk are deleted when the cloud disk is released. Valid values:
Snapshots that are created in the ECS console or by calling the CreateSnapshot operation are retained and not affected by this parameter. |
StorageClusterId | String | dbsc-j5e1sf2vaf5he8m2**** | The ID of the dedicated block storage cluster to which the cloud disk belongs. If your cloud disk belongs to the public block storage cluster, an empty value is returned. |
Encrypted | Boolean | false | Indicates whether the cloud disk is encrypted. |
IOPSRead | Integer | 2000 | The maximum number of I/O read operations per second. |
MountInstanceNum | Integer | 1 | The number of instances to which the Shared Block Storage device is attached. |
Description | String | testDescription | The description of the disk. |
Device | String | /dev/xvdb | The device name of the disk on its associated instance. Example: /dev/xvdb. Take note of the following items:
Note This parameter will be deprecated. We recommend that you use other parameters to ensure compatibility. |
DiskName | String | testDiskName | The name of the disk. |
Portable | Boolean | false | Indicates whether the disk is removable. |
ImageId | String | m-bp13aqm171qynt3u*** | The ID of the image used to create the instance. This parameter is empty unless the cloud disk is created from an image. The value of this parameter remains unchanged throughout the lifecycle of the cloud disk. |
KMSKeyId | String | 0e478b7a-4262-4802-b8cb-00d3fb408*** | The ID of the KMS key that is used by the cloud disk. |
DeleteWithInstance | Boolean | true | Indicates whether the cloud disk is released when its associated instance is released. Valid values:
|
DetachedTime | String | 2021-06-07T21:01:22Z | The time when the cloud disk was last detached. |
SourceSnapshotId | String | s-bp67acfmxazb4p**** | The ID of the snapshot that is used to create the cloud disk. This parameter is left empty unless the cloud disk is created from a snapshot. The value of this parameter remains unchanged throughout the lifecycle of the cloud disk. |
AutoSnapshotPolicyId | String | sp-bp67acfmxazb4p**** | The ID of the automatic snapshot policy that is applied to the cloud disk. |
EnableAutomatedSnapshotPolicy | Boolean | false | Indicates whether an automatic snapshot policy is applied to the cloud disk. |
IOPSWrite | Integer | 2000 | The maximum number of write operations per second. |
InstanceId | String | i-bp67acfmxazb4q**** | The ID of the instance to which the disk is attached. Take note of the following items:
|
IOPS | Integer | 4000 | The maximum number of IOPS. |
RegionId | String | cn-hangzhou | The region ID of the disk. |
ExpiredTime | String | 2021-07-07T16:00Z | The time when the subscription cloud disk expires. |
Size | Integer | 60 | The size of the disk. Unit: GiB. |
ResourceGroupId | String | rg-bp67acfmxazb4p**** | The ID of the resource group to which the disk belongs. |
DiskChargeType | String | PrePaid | The billing method of the disk. Valid values:
|
ZoneId | String | cn-hangzhou-i | The zone ID of the disk. |
AttachedTime | String | 2021-06-07T06:08:56Z | The time when the cloud disk was last attached. The time follows the ISO 8601 standard in the yyyy-MM-ddThh:mmZ format. The time is displayed in UTC. |
Category | String | cloud_ssd | The category of the disk. Valid values:
|
ProductCode | String | jxsc000204 | The product code in Alibaba Cloud Marketplace. |
MultiAttach | String | Disabled | Indicates whether the multi-attach feature is enabled for the cloud disk. |
OperationLocks | Array of OperationLock | The reasons why the disk is locked. | |
OperationLock | |||
LockReason | String | security | The security reason why the disk is locked. |
MountInstances | Array of MountInstance | The attachment information of the Shared Block Storage device. | |
MountInstance | |||
AttachedTime | String | 2017-12-05T2340:00Z | The attachment time. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC. |
InstanceId | String | i-bp1j4i2jdf3owlhe**** | The ID of the instance to which the disk is attached. |
Device | String | /dev/xvda | The mount point of the disk. |
Tags | Array of Tag | The tags of the disk. | |
Tag | |||
TagValue | String | TestValue | The tag value of the disk. |
TagKey | String | TestKey | The tag key of the disk. |
Attachments | Array of Attachment | The attachment information about the cloud disk. The value is an array that consists of the | |
Attachment | |||
InstanceId | String | i-bp67acfmxazb4q**** | The ID of the instance to which the disk is attached. |
Device | String | /dev/xvda | The device name of the disk. |
AttachedTime | String | 2021-06-07T06:08:56Z | The attachment time. The time is displayed in UTC. |
ProvisionedIops | Long | 40000 | The provisioned read/write IOPS of the ESSD AutoPL disk. Valid values: 0 to min{50,000, 1,000 × Capacity - Baseline IOPS}. Baseline performance = min{1,800 + 50 × Capacity, 50,000} This parameter is supported only if the |
BurstingEnabled | Boolean | false | Indicates whether the performance burst feature is enabled. Valid values:
This parameter is supported only if the |
Throughput | Integer | 100 | The amount of data transferred per second. Unit: MB/s. |
ThroughputRead | Integer | 100 | The amount of data that is read by the system per second. Unit: MB/s. |
ThroughputWrite | Integer | 100 | The amount of data that is written by the system per second. Unit: MB/s. |
Examples
Sample requests
https://ecs.aliyuncs.com/?Action=DescribeDisks
&RegionId=cn-hangzhou
&PageNumber=1
&PageSize=1
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<DescribeDisksResponse>
<TotalCount>15</TotalCount>
<NextToken>AAAAAdDWBF2****</NextToken>
<PageSize>1</PageSize>
<RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
<PageNumber>1</PageNumber>
<Disks>
<Disk>
<DetachedTime/>
<Category>cloud_ssd</Category>
<Description>testDescription</Description>
<KMSKeyId/>
<ResourceGroupId/>
<DedicatedBlockStorageClusterId/>
<Encrypted>false</Encrypted>
<Size>40</Size>
<DeleteAutoSnapshot>false</DeleteAutoSnapshot>
<DiskChargeType>PrePaid</DiskChargeType>
<MultiAttach>Disabled</MultiAttach>
<Attachments>
<Attachment>
<AttachedTime>2021-06-07T06:08:56Z</AttachedTime>
<InstanceId>i-bp67acfmxazb4q****</InstanceId>
<Device>/dev/xvda</Device>
</Attachment>
</Attachments>
<ExpiredTime>2021-07-07T16:00Z</ExpiredTime>
<ImageId>m-bp13aqm171qynt3u***</ImageId>
<StorageSetId/>
<Tags>
</Tags>
<Status>In_use</Status>
<AttachedTime>2021-06-07T06:08:56Z</AttachedTime>
<StorageClusterId>dbsc-j5e1sf2vaf5he8m2****</StorageClusterId>
<ZoneId>cn-hangzhou-i</ZoneId>
<InstanceId>i-bp67acfmxazb4q****</InstanceId>
<SourceSnapshotId/>
<ProductCode/>
<PerformanceLevel>PL0</PerformanceLevel>
<Device>/dev/xvdb</Device>
<DeleteWithInstance>true</DeleteWithInstance>
<EnableAutomatedSnapshotPolicy>false</EnableAutomatedSnapshotPolicy>
<EnableAutoSnapshot>false</EnableAutoSnapshot>
<AutoSnapshotPolicyId>sp-bp67acfmxazb4p****</AutoSnapshotPolicyId>
<DiskName>testDiskName</DiskName>
<OperationLocks>
</OperationLocks>
<BdfId/>
<Portable>false</Portable>
<Type>system</Type>
<SerialNumber>bp18um4r4f2fve2****</SerialNumber>
<CreationTime>2021-06-07T06:08:54Z</CreationTime>
<RegionId>cn-hangzhou</RegionId>
<DiskId>d-bp18um4r4f2fve24****</DiskId>
</Disk>
</Disks>
</DescribeDisksResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"TotalCount" : 15,
"NextToken" : "AAAAAdDWBF2****",
"PageSize" : 1,
"RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
"PageNumber" : 1,
"Disks" : {
"Disk" : [ {
"DetachedTime" : "",
"Category" : "cloud_ssd",
"Description" : "testDescription",
"KMSKeyId" : "",
"ResourceGroupId" : "",
"DedicatedBlockStorageClusterId" : "",
"Encrypted" : false,
"Size" : 40,
"DeleteAutoSnapshot" : false,
"DiskChargeType" : "PrePaid",
"MultiAttach" : "Disabled",
"Attachments" : {
"Attachment" : [ {
"AttachedTime" : "2021-06-07T06:08:56Z",
"InstanceId" : "i-bp67acfmxazb4q****",
"Device" : "/dev/xvda"
} ]
},
"ExpiredTime" : "2021-07-07T16:00Z",
"ImageId" : "m-bp13aqm171qynt3u***",
"StorageSetId" : "",
"Tags" : {
"Tag" : [ ]
},
"Status" : "In_use",
"AttachedTime" : "2021-06-07T06:08:56Z",
"StorageClusterId" : "dbsc-j5e1sf2vaf5he8m2****",
"ZoneId" : "cn-hangzhou-i",
"InstanceId" : "i-bp67acfmxazb4q****",
"SourceSnapshotId" : "",
"ProductCode" : "",
"PerformanceLevel" : "PL0",
"Device" : "/dev/xvdb",
"DeleteWithInstance" : true,
"EnableAutomatedSnapshotPolicy" : false,
"EnableAutoSnapshot" : false,
"AutoSnapshotPolicyId" : "sp-bp67acfmxazb4p****",
"DiskName" : "testDiskName",
"OperationLocks" : {
"OperationLock" : [ ]
},
"BdfId" : "",
"Portable" : false,
"Type" : "system",
"SerialNumber" : "bp18um4r4f2fve2****",
"CreationTime" : "2021-06-07T06:08:54Z",
"RegionId" : "cn-hangzhou",
"DiskId" : "d-bp18um4r4f2fve24****"
} ]
}
}
Error codes
HTTP status code | Error code | Error message | Description |
400 | InvalidDiskType.ValueNotSupported | The specified disk type is not supported. | Invalid disk type. |
400 | InvalidCategory.ValueNotSupported | The specified disk category is not supported. | Invalid disk category. |
400 | InvalidStatus.ValueNotSupported | The specified disk status is not supported. | This operation cannot be performed on the disk in the current state. |
400 | InvalidTag.Mismatch | The specified Tag.n.Key and Tag.n.Value are not match. | The specified Tag.N.Key and Tag.N.Value parameters do not correspond to each other. |
400 | InvalidTagCount | The specified tags are beyond the permitted range. | The maximum number of tags is exceeded. |
400 | InvalidRegion.NotFound | The specified parameter RegionId is not valid. | Invalid RegionId value. |
400 | InvalidZoneId.NotFound | The zoneId provided does not exist in our records. | The specified zone ID is not found. |
400 | MissingParamter.RegionId | The regionId should not be null. | RegionId is required. |
400 | InvalidParameter.DiskIds | The specified parameter diskIds is not valid. | Invalid DiskIds value. |
400 | IncompleteParamter | Some fields can not be null in this request. | A required parameter is not specified. |
400 | InvalidParamter | Some parameters are invalid in this request. | The request contains invalid parameters. |
400 | InvalidSnapshot.NotFound | The specified parameter SnapshotId is not valid. | Invalid SnapshotId value. |
403 | InvalidDiskIds.Malformed | The amount of specified disk Ids exceeds the limit. | Invalid DiskIds value. |
403 | UserNotInTheWhiteList | The user is not in volume white list. | You are not authorized to manage the Shared Block Storage device. Submit a ticket to apply for the permissions. |
403 | InvalidParameter.MultiAttachAndEnableSharedNotMatch | The parameter MultiAttach and EnableShared are not match. | The specified MultiAttach and EnableShared parameters do not match. |
403 | InvalidParameter.MultiAttach | The specified param MultiAttach is not valid. | Invalid MultiAttach value. |
404 | InvalidDiskChargeType.NotFound | The DiskChargeType does not exist in our records | The DiskChargeType is not found. |
404 | InvalidLockReason.NotFound | The specified LockReason is not found | The LockReason is not found. |
500 | InternalError | The request processing has failed due to some unknown error. | An internal error occurred. Try again later. |
For a list of error codes, see Service error codes.