Queries the details of one or more block storage devices, including disks, local disks, and elastic ephemeral disks.
Operation description
-
Request parameters such as RegionId, ZoneId, DiskIds, and InstanceId act as filters and are connected by the logical AND operator.
-
The DiskIds parameter is an array in JSON format. If the parameter is left empty, the filter does not take effect. However, if DiskIds is an empty array, the filter is considered valid and an empty result is returned.
-
Token-based paging query is supported. You can use NextToken to configure the Settings for the query token, which is the NextToken value returned from the previous time you invoke the DescribeDisks operation. You can also use MaxResults to configure the Settings for the maximum number of entries to return on each page.
-
A disk with the multi-attach feature enabled can be attached to multiple instances. You can view all attachment information of the disk in the Attachment list of the response.
When you invoke API operations by using Cloud Assistant CLI, you must format the values of request parameters of different data types. For more information, see CLI parameter formats.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ecs:DescribeDisks |
list |
Disk
Disk
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| RegionId |
string |
Yes |
The region ID of the block storage device. You can call the DescribeRegions operation to query the most recent region list. |
cn-hangzhou |
| ZoneId |
string |
No |
The zone ID. |
cn-hangzhou-g |
| DiskIds |
string |
No |
The IDs of the disks, local disks, or elastic ephemeral disks. The value is a JSON array that supports up to 100 IDs, separated by commas (,). |
["d-bp67acfmxazb4p****", "d-bp67acfmxazb4g****", … "d-bp67acfmxazb4d****"] |
| InstanceId |
string |
No |
The instance ID to which the disk, local disk, or elastic ephemeral disk is attached. |
i-bp67acfmxazb4q**** |
| DiskType |
string |
No |
The type of the disk, local disk, or elastic ephemeral disk to query. Valid values:
Note
Elastic ephemeral disks cannot be used as system disks. |
all |
| Category |
string |
No |
The category of the disk. Valid values:
|
all |
| Status |
string |
No |
The performance level of the enterprise SSD. Valid values: PL0, PL1, PL2, and PL3. |
PL0 |
| SnapshotId |
string |
No |
The disk status. For more information, see Disk status. Valid values:
|
All |
| Portable |
boolean |
No |
The ID of the snapshot used to create the disk. |
s-bp67acfmxazb4p**** |
| DeleteWithInstance |
boolean |
No |
Specifies whether the disk can be detached. Valid values:
|
false |
| DeleteAutoSnapshot |
boolean |
No |
Specifies whether the disk is released together with the instance. Valid values:
|
false |
| PageNumber |
integer |
No |
Specifies whether automatic snapshots are released together with the disk. Valid values:
|
false |
| PageSize |
integer |
No |
[Deprecated] This parameter is going offline. We recommend that you use the NextToken and MaxResults parameters to complete paging query operations. |
1 |
| NextToken |
string |
No |
[Deprecated] This parameter is going offline. We recommend that you use the NextToken and MaxResults parameters to complete paging query operations. |
10 |
| MaxResults |
integer |
No |
The query token. The value is the NextToken value returned from the previous API call. For more information about how to configure the returned data for this operation, see the operation description section above. |
AAAAAdDWBF2**** |
| DiskName |
string |
No |
The maximum number of entries to return. Valid values: 10 to 500. Default value:
|
50 |
| AutoSnapshotPolicyId |
string |
No |
The name of the disk. The name must be 2 to 128 characters in length and can contain letters and digits in the Unicode letter category. It can also contain colons (:), underscores (_), periods (.), and hyphens (-). |
testDiskName |
| EnableAutoSnapshot |
boolean |
No |
The ID of the automatic snapshot policy used to query disks. |
sp-m5e2w2jutw8bv31**** |
| EnableAutomatedSnapshotPolicy |
boolean |
No |
Specifies whether the automatic snapshot policy feature is enabled for the disk. Valid values:
|
true |
| DiskChargeType |
string |
No |
Specifies whether an automatic snapshot policy is applied to the disk. Valid values:
|
false |
| LockReason |
string |
No |
The billing method of the disk. Valid values:
|
PostPaid |
| Filter.1.Key |
string |
No |
The reason why the disk is locked. Valid values:
|
security |
| Filter.2.Key |
string |
No |
The filter key used to query resources. Set the value to CreationStartTime. If you specify both Filter.1.Key and Filter.1.Value, you can query resources created after the specified time. |
CreationStartTime |
| Filter.1.Value |
string |
No |
The filter key used to query resources. Set the value to CreationEndTime. If you specify both Filter.2.Key and Filter.2.Value, you can query resources created before the specified time. |
CreationEndTime |
| Filter.2.Value |
string |
No |
The filter value used to query resources. If you specify this parameter, you must also specify Filter.1.Key. The value must be in the yyyy-MM-ddTHH:mmZ format and use the UTC+0 time zone. |
2017-12-05T22:40Z |
| ResourceGroupId |
string |
No |
The filter value used to query resources. If you specify this parameter, you must also specify Filter.2.Key. The value must be in the yyyy-MM-ddTHH:mmZ format and use the UTC+0 time zone. |
2017-12-06T22:40Z |
| EnableShared |
boolean |
No |
The ID of the resource group to which the disk belongs. When you use this parameter to filter resources, the resource count cannot exceed 1,000. Note
Filtering by the default resource group is not supported. |
rg-bp67acfmxazb4p**** |
| Encrypted |
boolean |
No |
Specifies whether it is Shared Block Storage. |
false |
| DryRun |
boolean |
No |
Specifies whether to filter only encrypted disks. Valid values:
|
false |
| KMSKeyId |
string |
No |
Specifies whether to only perform a dry run for this request. Valid values:
|
false |
| MultiAttach |
string |
No |
The ID of the Key Management Service (KMS) key used by the disk. |
0e478b7a-4262-4802-b8cb-00d3fb40**** |
| Tag |
array<object> |
No |
Specifies whether the multi-attach feature is enabled. Valid values:
|
Disabled |
|
object |
No |
The disk tag. |
||
| Key |
string |
No |
The tag key of the disk. Valid values of N: 1 to 20. If you use a single tag to filter resources, the resource count returned cannot exceed 1,000. If you use multiple tags to filter resources, the resource count of resources that attach multiple tags cannot exceed 1,000. If the resource count exceeds 1,000, use the ListTagResources operation to query the resources. |
TestKey |
| Value |
string |
No |
The tag value of the disk. Valid values of N: 1 to 20. |
TestValue |
| key |
string |
No |
The tag key of the disk. Note
To improve code compatibility, we recommend that you use the Tag.N.Key parameter. |
null |
| value |
string |
No |
The tag value of the disk. Note
To improve code compatibility, we recommend that you use the Tag.N.Value parameter. |
null |
| AdditionalAttributes |
array |
No |
The list of disk tags. |
IOPS |
|
string |
No |
The disk tag. |
Placement |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| Disks |
object |
||
| Disk |
array<object> |
The collection of disk information. |
|
|
array<object> |
The disk information. |
||
| AttachedTime |
string |
The time when the disk was last attached. The time is displayed in UTC and follows the ISO 8601 standard in the yyyy-MM-ddThh:mmZ format. |
2021-06-07T06:08:56Z |
| Attachments |
object |
||
| Attachment |
array<object> |
The attachment information of the disk. This is a list of Attachment objects. This list is not returned when you query Shared Block Storage. |
|
|
object |
The attachment information of the disk. |
||
| AttachedTime |
string |
The time when the disk was attached. The time is displayed in UTC. |
2021-06-07T06:08:56Z |
| Device |
string |
The device name. |
/dev/xvda |
| InstanceId |
string |
The instance ID to which the disk is attached. |
i-bp67acfmxazb4q**** |
| AutoSnapshotPolicyId |
string |
The ID of the automatic snapshot policy applied to the disk. Note
[Deprecated] This parameter will be deprecated. If multiple automatic snapshot policies are applied to the disk, only one policy ID is returned. We recommend that you use DescribeAutoSnapshotPolicyAssociations to query all automatic snapshot policies applied to the disk. |
sp-bp67acfmxazb4p**** |
| BdfId |
string |
This parameter is in invitational preview and is not available. |
null |
| BurstingEnabled |
boolean |
Specifies whether performance burst is enabled. Valid values:
Settings for this parameter are supported only when DiskCategory is set to cloud_auto. For more information, see ESSD AutoPL disks. |
false |
| Category |
string |
The disk category. Valid values:
|
cloud_ssd |
| CreationTime |
string |
The time when the disk was created. The time is displayed in UTC and follows the ISO 8601 standard. |
2021-06-07T06:08:54Z |
| DataSource |
object |
The data source information of the disk. |
|
| Id |
string |
The ID of the data source. |
s-bp67acfmxazb4p**** |
| Type |
string |
The type of the data source. |
snapshot |
| DeleteAutoSnapshot |
boolean |
Specifies whether to delete automatic snapshots when the disk is released. Valid values:
Snapshots created by calling the CreateSnapshot operation or in the console are not affected by this parameter and are always retained. |
false |
| DeleteWithInstance |
boolean |
Specifies whether to release the disk when the instance is released. Valid values:
|
true |
| Description |
string |
The description of the disk. |
testDescription |
| DetachedTime |
string |
The time when the disk was last detached. The time is displayed in UTC and follows the ISO 8601 standard. |
2021-06-07T21:01:22Z |
| Device |
string |
The device name of the instance to which the disk is attached, such as /dev/xvdb. Take note of the following items:
Note
[Deprecated] This parameter will be deprecated. To improve code compatibility, we recommend that you do not use this parameter. |
/dev/xvdb |
| DiskChargeType |
string |
The billing method of the disk. Valid values:
|
PrePaid |
| DiskId |
string |
The ID of the disk. |
d-bp18um4r4f2fve24**** |
| DiskName |
string |
The name of the disk. |
testDiskName |
| EnableAutoSnapshot |
boolean |
Specifies whether the automatic snapshot policy feature is enabled for the disk. Note
[Deprecated] This parameter is deprecated. The automatic snapshot policy feature is enabled by default for newly created disks. You only need to apply an automatic snapshot policy to the disk. |
false |
| EnableAutomatedSnapshotPolicy |
boolean |
Specifies whether an automatic snapshot policy is applied to the disk. |
false |
| Encrypted |
boolean |
Specifies whether the disk is encrypted. |
false |
| ExpiredTime |
string |
The expiration time of the subscription disk. The time is displayed in UTC and follows the ISO 8601 standard. |
2021-07-07T16:00Z |
| IOPS |
integer |
The maximum number of I/O operations per second (IOPS). |
4000 |
| IOPSRead |
integer |
The maximum number of read operations per second. Unit: operations per second. |
2000 |
| IOPSWrite |
integer |
The maximum number of write operations per second. Unit: operations per second. |
2000 |
| ImageId |
string |
The ID of the image used to create the ECS instance. This parameter has a value only when the disk is created from an image. If the image used to create the disk is deleted, this parameter is empty. |
m-bp13aqm171qynt3u*** |
| InstanceId |
string |
The instance ID to which the disk is attached. Take note of the following items:
|
i-bp67acfmxazb4q**** |
| KMSKeyId |
string |
The ID of the Key Management Service (KMS) key used by the disk. |
0e478b7a-4262-4802-b8cb-00d3fb408*** |
| MountInstanceNum |
integer |
The number of instances to which the shared storage is attached. |
1 |
| MountInstances |
object |
||
| MountInstance |
array<object> |
The collection of information about the instances to which the shared storage is attached. |
|
|
object |
The information about the instance to which the shared storage is attached. |
||
| AttachedTime |
string |
The time when the shared storage was attached. The time is displayed in UTC and follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. |
2017-12-05T2340:00Z |
| Device |
string |
The mount point of the disk. |
/dev/xvda |
| InstanceId |
string |
The instance ID to which the disk is attached. |
i-bp1j4i2jdf3owlhe**** |
| MultiAttach |
string |
Specifies whether the multi-attach feature is enabled for the disk. |
Disabled |
| OperationLocks |
object |
||
| OperationLock |
array<object> |
The list of reasons why the disk is locked. |
|
|
object |
The reason why the disk is locked. |
||
| LockReason |
string |
The reason why the disk is locked for security reasons. |
security |
| PerformanceLevel |
string |
The ESSD performance level. Valid values:
|
PL0 |
| Placement |
object |
The collection of data storage locations. This parameter is returned only when AdditionalAttributes.N is set to Placement in the request. Note
Currently, only regional ESSDs (cloud_regional_disk_auto) have valid values for this parameter. |
|
| ZoneIds |
string |
The list of zones where the data is actually stored. |
"["cn-hangzhou-b", "cn-hangzhou-j"]" |
| Portable |
boolean |
Specifies whether the disk is removable. |
false |
| ProductCode |
string |
The product code in Alibaba Cloud Marketplace. |
jxsc000204 |
| ProvisionedIops |
integer |
The provisioned read and write IOPS of the ESSD AutoPL disk. Valid values: 0 to min{50,000, 1,000 × Capacity - Baseline performance}. Baseline performance = min{1,800 + 50 × Capacity, 50,000}. This parameter is supported only when DiskCategory is set to cloud_auto. For more information, see ESSD AutoPL disks. |
40000 |
| RegionId |
string |
The region ID of the disk. |
cn-hangzhou |
| ResourceGroupId |
string |
The ID of the resource group to which the disk belongs. |
rg-bp67acfmxazb4p**** |
| SerialNumber |
string |
The serial number of the disk. |
bp18um4r4f2fve2**** |
| Size |
integer |
The size of the disk. Unit: GiB. |
60 |
| SourceDiskId |
string |
The ID of the source disk. |
d-123********* |
| SourceSnapshotId |
string |
The ID of the snapshot used to create the disk. If no snapshot is specified when the disk is created, this parameter is empty. If the snapshot used to create the disk is deleted, this parameter is empty. |
s-bp67acfmxazb4p**** |
| Status |
string |
The status of the disk. Valid values:
|
In_use |
| StorageClusterId |
string |
The ID of the dedicated block storage cluster to which the disk belongs. If the disk is in a public cloud block storage cluster, this parameter is empty. |
dbsc-j5e1sf2vaf5he8m2**** |
| StorageSetId |
string |
The ID of the storage set. |
ss-i-bp1j4i2jdf3owlhe**** |
| StorageSetPartitionNumber |
integer |
The maximum number of partitions in the storage set. |
11 |
| Tags |
object |
||
| Tag |
array<object> |
The collection of tags of the disk. |
|
|
object |
The tag of the disk. |
||
| TagKey |
string |
The tag key. |
TestKey |
| TagValue |
string |
The tag value. |
TestValue |
| Throughput |
integer |
The throughput of the disk. Unit: MB/s. |
100 |
| ThroughputRead |
integer |
The read throughput of the disk. Unit: MB/s. |
100 |
| ThroughputWrite |
integer |
The write throughput of the disk. Unit: MB/s. |
100 |
| Type |
string |
The type of the disk. Valid values:
|
system |
| ZoneId |
string |
The zone ID of the disk. |
cn-hangzhou-i |
| NextToken |
string |
The pagination token returned by the current request. |
AAAAAdDWBF2**** |
| PageNumber |
integer |
Note
[Deprecated] This parameter will be taken offline. Use the NextToken and MaxResults parameters to perform paged queries. |
1 |
| PageSize |
integer |
Note
[Deprecated] This parameter will be taken offline. Use the NextToken and MaxResults parameters to perform paged queries. |
1 |
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
| TotalCount |
integer |
The total number of queried entries. Note
When you use the MaxResults and NextToken parameters to perform paged queries, the returned value of the TotalCount parameter is invalid. |
15 |
Examples
Success response
JSON format
{
"Disks": {
"Disk": [
{
"AttachedTime": "2021-06-07T06:08:56Z",
"Attachments": {
"Attachment": [
{
"AttachedTime": "2021-06-07T06:08:56Z",
"Device": "/dev/xvda",
"InstanceId": "i-bp67acfmxazb4q****"
}
]
},
"AutoSnapshotPolicyId": "sp-bp67acfmxazb4p****",
"BdfId": "null",
"BurstingEnabled": false,
"Category": "cloud_ssd",
"CreationTime": "2021-06-07T06:08:54Z",
"DataSource": {
"Id": "s-bp67acfmxazb4p****",
"Type": "snapshot"
},
"DeleteAutoSnapshot": false,
"DeleteWithInstance": true,
"Description": "testDescription",
"DetachedTime": "2021-06-07T21:01:22Z",
"Device": "/dev/xvdb",
"DiskChargeType": "PrePaid",
"DiskId": "d-bp18um4r4f2fve24****",
"DiskName": "testDiskName",
"EnableAutoSnapshot": false,
"EnableAutomatedSnapshotPolicy": false,
"Encrypted": false,
"ExpiredTime": "2021-07-07T16:00Z",
"IOPS": 4000,
"IOPSRead": 2000,
"IOPSWrite": 2000,
"ImageId": "m-bp13aqm171qynt3u***",
"InstanceId": "i-bp67acfmxazb4q****",
"KMSKeyId": "0e478b7a-4262-4802-b8cb-00d3fb408***",
"MountInstanceNum": 1,
"MountInstances": {
"MountInstance": [
{
"AttachedTime": "2017-12-05T2340:00Z",
"Device": "/dev/xvda",
"InstanceId": "i-bp1j4i2jdf3owlhe****"
}
]
},
"MultiAttach": "Disabled",
"OperationLocks": {
"OperationLock": [
{
"LockReason": "security"
}
]
},
"PerformanceLevel": "PL0",
"Placement": {
"ZoneIds": "\"[\"cn-hangzhou-b\",\n\"cn-hangzhou-j\"]\""
},
"Portable": false,
"ProductCode": "jxsc000204",
"ProvisionedIops": 40000,
"RegionId": "cn-hangzhou",
"ResourceGroupId": "rg-bp67acfmxazb4p****",
"SerialNumber": "bp18um4r4f2fve2****",
"Size": 60,
"SourceDiskId": "d-123*********",
"SourceSnapshotId": "s-bp67acfmxazb4p****",
"Status": "In_use",
"StorageClusterId": "dbsc-j5e1sf2vaf5he8m2****",
"StorageSetId": "ss-i-bp1j4i2jdf3owlhe****",
"StorageSetPartitionNumber": 11,
"Tags": {
"Tag": [
{
"TagKey": "TestKey",
"TagValue": "TestValue"
}
]
},
"Throughput": 100,
"ThroughputRead": 100,
"ThroughputWrite": 100,
"Type": "system",
"ZoneId": "cn-hangzhou-i"
}
]
},
"NextToken": "AAAAAdDWBF2****",
"PageNumber": 1,
"PageSize": 1,
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
"TotalCount": 15
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidDiskType.ValueNotSupported | The specified disk type is not supported. | The specified disk type is not supported. |
| 400 | InvalidCategory.ValueNotSupported | The specified value of parameter Category is not supported. Please set Category to a supported value such as cloud_essd and try again. | |
| 400 | InvalidStatus.ValueNotSupported | The specified disk status is not supported. | The disk is in a state that does not support the current operation. |
| 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 number of specified tags exceeds the upper limit. |
| 400 | InvalidRegion.NotFound | The specified parameter RegionId is not valid. | The specified RegionId parameter is invalid. |
| 400 | InvalidZoneId.NotFound | The zoneId provided does not exist in our records. | The specified zone ID does not exist. |
| 400 | MissingParamter.RegionId | The regionId should not be null. | The RegionId parameter is required. |
| 400 | InvalidParameter.DiskIds | The specified parameter diskIds is not valid. | The specified DiskIds parameter is invalid. |
| 400 | IncompleteParamter | Some fields can not be null in this request. | Some required parameters are 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. | The specified SnapshotId parameter is invalid. |
| 400 | InvalidPerformanceLevel.Malformed | The specified parameter PerformanceLevel is not valid. Valid values are PL0/PL1/PL2/PL3. | |
| 500 | InternalError | The request processing has failed due to an internal error and you may retry later or contact support with the request ID. | |
| 403 | InvalidDiskIds.Malformed | The amount of specified disk Ids exceeds the limit. | |
| 403 | InvalidCategory.ValueNotSupported | The specified value of parameter Category is not supported. Please set Category to a supported value such as cloud_essd and try again. | |
| 403 | UserNotInTheWhiteList | The user is not in volume white list. | |
| 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 parameter MultiAttach is not valid. Please set it to Disabled or Enabled and try again. | |
| 404 | InvalidFilterKey.NotFound | The filter key is not found. | |
| 404 | InvalidFilterValue | The filter value is not valid. | |
| 404 | InvalidDiskIds.ValueNotSupported | The specified parameter "DiskIds" is not supported. | The specified DiskIds parameter is invalid. |
| 404 | InvalidDiskChargeType.NotFound | The DiskChargeType does not exist in our records. | The DiskChargeType does not exist in our records. |
| 404 | InvalidLockReason.NotFound | The specified LockReason is not found. | The specified lockout reason does not exist. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.