DescribeDisks
Queries the details of one or more block storage devices, including cloud 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 this 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 is supported. You can use NextToken to set the query token. The value of NextToken is the NextToken value returned when you last call DescribeDisks. You can also use MaxResults to configure the Settings for the maximum number of entries to return on each page.
-
A cloud disk with the multi-attach feature enabled can be attached to multiple instances. You can view all attachment information of the cloud disk in the Attachment list of the response.
When you call API operations by using Cloud Assistant CLI, the values of request parameters of different data types must follow the format requirements. For more information, see CLI parameter format description.
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 cloud 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 cloud disk, local disk, or elastic ephemeral disk. Valid values:
Default value: all. Note
Elastic ephemeral disks cannot be used as system disks. |
all |
| Category |
string |
No |
The category of the disk. Valid values:
Default value: all. |
all |
| PerformanceLevel |
string |
No |
The performance level of the enterprise SSD. Valid values: PL0, PL1, PL2, and PL3. |
PL0 |
| Status |
string |
No |
The status of the disk. For more information, see Disk status. Valid values:
Default value: All. |
All |
| SnapshotId |
string |
No |
The ID of the snapshot used to create the cloud disk. |
s-bp67acfmxazb4p**** |
| Portable |
boolean |
No |
Specifies whether the disk is removable. Valid values:
The Portable attribute of the following types of block storage devices is false, and their lifecycles are the same as those of the instances:
|
false |
| DeleteWithInstance |
boolean |
No |
Specifies whether the disk is released together with the instance. Valid values:
Default value: false. |
false |
| DeleteAutoSnapshot |
boolean |
No |
Specifies whether automatic snapshots are released when the cloud disk is released. Valid values:
Default value: false. |
false |
| PageNumber |
integer |
No |
Note
This parameter will soon be deprecated. We recommend that you use the NextToken and MaxResults parameters to complete the paging operation. |
1 |
| PageSize |
integer |
No |
Note
This parameter will soon be deprecated. We recommend that you use the NextToken and MaxResults parameters to complete the paging operation. |
10 |
| NextToken |
string |
No |
The query token. The value is the NextToken value returned from the previous API call. For more information about how to configure the return data for this operation, see the operation description section above. |
AAAAAdDWBF2**** |
| MaxResults |
integer |
No |
The maximum number of entries to return. Valid values: 10 to 500. Default value:
|
50 |
| DiskName |
string |
No |
The name of the disk. The name must be 2 to 128 characters in length and can contain Unicode letters (including English letters, Chinese characters, and digits). It can also contain colons (:), underscores (_), periods (.), and hyphens (-). |
testDiskName |
| AutoSnapshotPolicyId |
string |
No |
The ID of the automatic snapshot policy used to query the cloud disk. |
sp-m5e2w2jutw8bv31**** |
| EnableAutoSnapshot |
boolean |
No |
Specifies whether the automatic snapshot policy feature is enabled for the cloud disk. Valid values:
Note
This parameter is deprecated. The automatic snapshot policy feature is enabled by default for newly created cloud disks. You only need to apply an automatic snapshot policy to the cloud disk to use the feature. |
true |
| EnableAutomatedSnapshotPolicy |
boolean |
No |
Specifies whether an automatic snapshot policy is applied to the cloud disk. Valid values:
Default value: false. |
false |
| DiskChargeType |
string |
No |
The billing method of the disk. Valid values:
|
PostPaid |
| LockReason |
string |
No |
The reason why the disk is locked. Valid values:
|
security |
| Filter.1.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.2.Key |
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.1.Value |
string |
No |
The filter value used to query resources. If you specify this parameter, you must also specify the Filter.1.Key parameter. Specify the time in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC. |
2017-12-05T22:40Z |
| Filter.2.Value |
string |
No |
The filter value used to query resources. If you specify this parameter, you must also specify the Filter.2.Key parameter. Specify the time in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC. |
2017-12-06T22:40Z |
| ResourceGroupId |
string |
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**** |
| EnableShared |
boolean |
No |
Specifies whether the disk is a Shared Block Storage device. |
false |
| Encrypted |
boolean |
No |
Specifies whether to query only encrypted cloud disks. Valid values:
Default value: false. |
false |
| DryRun |
boolean |
No |
Specifies whether to only perform a dry run for this request. Valid values:
Default value: false. |
false |
| KMSKeyId |
string |
No |
The ID of the Key Management Service (KMS) key used by the cloud disk. |
0e478b7a-4262-4802-b8cb-00d3fb40**** |
| MultiAttach |
string |
No |
Specifies whether the multi-attach feature is enabled. Valid values:
|
Disabled |
| Tag |
array<object> |
No |
The tags of the disk. |
|
|
object |
No |
The tag of the disk. |
||
| key |
string |
No |
The tag key of the disk. Note
To improve code compatibility, use the Tag.N.Key parameter. |
null |
| Key |
string |
No |
The tag key of the disk. Valid values of N: 1 to 20. When you use a single tag to filter resources, the resource count under this tag cannot exceed 1,000. When 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 |
| value |
string |
No |
The tag value of the disk. Note
To improve code compatibility, use the Tag.N.Value parameter. |
null |
| AdditionalAttributes |
array |
No |
The list of additional attributes. Set the value to Placement to query the data storage location of the disk. Note
Only regional disks have data storage locations. |
IOPS |
|
string |
No |
The additional attribute value. Set the value to Placement to query the data storage location of the disk. |
Placement |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| NextToken |
string |
The pagination token returned by the current call. |
AAAAAdDWBF2**** |
| PageSize |
integer |
Note
This parameter will be deprecated soon. We recommend that you use the |
1 |
| PageNumber |
integer |
Note
This parameter will be deprecated soon. We recommend that you use the |
1 |
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
| TotalCount |
integer |
The total number of entries returned. Note
When you use the |
15 |
| Disks |
object |
||
| Disk |
array<object> |
The collection of disk information. |
|
|
array<object> |
The disk information. |
||
| SerialNumber |
string |
The serial number of the disk. |
bp18um4r4f2fve2**** |
| CreationTime |
string |
The creation time. The time is displayed in the ISO 8601 standard in the UTC time zone. |
2021-06-07T06:08:54Z |
| Status |
string |
The disk status. Valid values:
|
In_use |
| Type |
string |
The disk type. Valid values:
|
system |
| PerformanceLevel |
string |
The performance level of the ESSD. Valid values:
|
PL0 |
| BdfId |
string |
This parameter is in invitational preview and is not available for public use. |
null |
| EnableAutoSnapshot |
boolean |
Indicates whether the automatic snapshot policy feature is enabled for the disk. Note
[Deprecated] After a disk is created, the automatic snapshot policy feature is enabled by default. You only need to apply an automatic snapshot policy to the disk. |
false |
| StorageSetId |
string |
The ID of the storage set. |
ss-i-bp1j4i2jdf3owlhe**** |
| StorageSetPartitionNumber |
integer |
The maximum number of partitions in the storage set. |
11 |
| DiskId |
string |
The disk ID. |
d-bp18um4r4f2fve24**** |
| DeleteAutoSnapshot |
boolean |
Indicates whether automatic snapshots are deleted 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 |
| StorageClusterId |
string |
The ID of the dedicated block storage cluster to which the disk belongs. If the disk resides in a public cloud block storage cluster, an empty string is returned. |
dbsc-j5e1sf2vaf5he8m2**** |
| Encrypted |
boolean |
Indicates whether the disk is encrypted. |
false |
| IOPSRead |
integer |
The maximum number of read operations per second. |
2000 |
| MountInstanceNum |
integer |
The number of instances to which the shared storage is attached. |
1 |
| Description |
string |
The disk description. |
testDescription |
| 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
This parameter will be deprecated soon. To improve code compatibility, do not use this parameter. |
/dev/xvdb |
| DiskName |
string |
The disk name. |
testDiskName |
| Portable |
boolean |
Indicates whether the disk is detachable. |
false |
| ImageId |
string |
The ID of the image used to create the ECS instance. This parameter has a value only for disks created from images. Otherwise, this parameter is empty. If the image used to create the disk is deleted, this parameter is empty. |
m-bp13aqm171qynt3u*** |
| KMSKeyId |
string |
The ID of the Key Management Service (KMS) key used by the cloud disk. |
0e478b7a-4262-4802-b8cb-00d3fb408*** |
| DeleteWithInstance |
boolean |
Indicates whether the disk is released when its associated instance is released. Valid values:
|
true |
| DetachedTime |
string |
The last time the disk was detached. The time is displayed in the ISO 8601 standard in the UTC time zone. |
2021-06-07T21:01:22Z |
| 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**** |
| AutoSnapshotPolicyId |
string |
The ID of the automatic snapshot policy applied to the disk. Note
This parameter will be deprecated. If multiple automatic snapshot policies are applied to the disk, only one of them is returned. Use the DescribeAutoSnapshotPolicyAssociations operation to query all automatic snapshot policies applied to the disk. |
sp-bp67acfmxazb4p**** |
| EnableAutomatedSnapshotPolicy |
boolean |
Indicates whether an automatic snapshot policy is applied to the disk. |
false |
| IOPSWrite |
integer |
The maximum number of write operations per second. |
2000 |
| InstanceId |
string |
The ID of the instance to which the disk is attached. Take note of the following items:
|
i-bp67acfmxazb4q**** |
| IOPS |
integer |
The maximum number of read and write (I/O) operations per second. |
4000 |
| RegionId |
string |
The region ID of the disk. |
cn-hangzhou |
| ExpiredTime |
string |
The expiration time of the subscription disk. The time is displayed in the ISO 8601 standard in the UTC time zone. |
2021-07-07T16:00Z |
| Size |
integer |
The disk size. Unit: GiB. |
60 |
| ResourceGroupId |
string |
The ID of the resource group to which the disk belongs. |
rg-bp67acfmxazb4p**** |
| DiskChargeType |
string |
The billing method of the disk. Valid values:
|
PrePaid |
| ZoneId |
string |
The zone ID of the disk. |
cn-hangzhou-i |
| AttachedTime |
string |
The last time the disk was attached. The time is displayed in the ISO 8601 standard in the UTC time zone. Format: yyyy-MM-ddThh:mmZ. |
2021-06-07T06:08:56Z |
| Category |
string |
The disk category. Valid values:
|
cloud_ssd |
| ProductCode |
string |
The product code in Alibaba Cloud Marketplace. |
jxsc000204 |
| MultiAttach |
string |
Indicates whether the multi-attach feature is enabled for the disk. |
Disabled |
| OperationLocks |
object |
||
| OperationLock |
array<object> |
The 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 |
| 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 the ISO 8601 standard in the UTC time zone. Format: yyyy-MM-ddTHH:mm:ssZ. |
2017-12-05T2340:00Z |
| InstanceId |
string |
The ID of the instance to which the disk is attached. |
i-bp1j4i2jdf3owlhe**** |
| Device |
string |
The mount point of the disk. |
/dev/xvda |
| Tags |
object |
||
| Tag |
array<object> |
The tags of the disk. |
|
|
object |
The tag of the disk. |
||
| TagValue |
string |
The tag value. |
TestValue |
| TagKey |
string |
The tag key. |
TestKey |
| Attachments |
object |
||
| Attachment |
array<object> |
The attachment information of the disk. This parameter is a list of |
|
|
object |
The attachment information of the disk. |
||
| InstanceId |
string |
The ID of the instance to which the disk is attached. |
i-bp67acfmxazb4q**** |
| Device |
string |
The device name. |
/dev/xvda |
| AttachedTime |
string |
The time when the disk was attached. The time is in the UTC time zone. |
2021-06-07T06:08:56Z |
| 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 the |
40000 |
| BurstingEnabled |
boolean |
Indicates whether the performance burst feature is enabled. Valid values:
This parameter is supported only when the |
false |
| Throughput |
integer |
The throughput. Unit: MB/s. |
100 |
| ThroughputRead |
integer |
The read throughput. Unit: MB/s. |
100 |
| ThroughputWrite |
integer |
The write throughput. Unit: MB/s. |
100 |
| Placement |
object |
The collection of data placement information. This parameter is returned only when the 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"]" |
| SourceDiskId |
string |
The source disk ID. |
d-123********* |
| DataSource |
object |
The data source information of the disk. |
|
| Id |
string |
The data source ID. |
s-bp67acfmxazb4p**** |
| Type |
string |
The data source type. |
snapshot |
Examples
Success response
JSON format
{
"NextToken": "AAAAAdDWBF2****",
"PageSize": 1,
"PageNumber": 1,
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
"TotalCount": 15,
"Disks": {
"Disk": [
{
"SerialNumber": "bp18um4r4f2fve2****",
"CreationTime": "2021-06-07T06:08:54Z",
"Status": "In_use",
"Type": "system",
"PerformanceLevel": "PL0",
"BdfId": "null",
"EnableAutoSnapshot": false,
"StorageSetId": "ss-i-bp1j4i2jdf3owlhe****",
"StorageSetPartitionNumber": 11,
"DiskId": "d-bp18um4r4f2fve24****",
"DeleteAutoSnapshot": false,
"StorageClusterId": "dbsc-j5e1sf2vaf5he8m2****",
"Encrypted": false,
"IOPSRead": 2000,
"MountInstanceNum": 1,
"Description": "testDescription",
"Device": "/dev/xvdb",
"DiskName": "testDiskName",
"Portable": false,
"ImageId": "m-bp13aqm171qynt3u***",
"KMSKeyId": "0e478b7a-4262-4802-b8cb-00d3fb408***",
"DeleteWithInstance": true,
"DetachedTime": "2021-06-07T21:01:22Z",
"SourceSnapshotId": "s-bp67acfmxazb4p****",
"AutoSnapshotPolicyId": "sp-bp67acfmxazb4p****",
"EnableAutomatedSnapshotPolicy": false,
"IOPSWrite": 2000,
"InstanceId": "i-bp67acfmxazb4q****",
"IOPS": 4000,
"RegionId": "cn-hangzhou",
"ExpiredTime": "2021-07-07T16:00Z",
"Size": 60,
"ResourceGroupId": "rg-bp67acfmxazb4p****",
"DiskChargeType": "PrePaid",
"ZoneId": "cn-hangzhou-i",
"AttachedTime": "2021-06-07T06:08:56Z",
"Category": "cloud_ssd",
"ProductCode": "jxsc000204",
"MultiAttach": "Disabled",
"OperationLocks": {
"OperationLock": [
{
"LockReason": "security"
}
]
},
"MountInstances": {
"MountInstance": [
{
"AttachedTime": "2017-12-05T2340:00Z",
"InstanceId": "i-bp1j4i2jdf3owlhe****",
"Device": "/dev/xvda"
}
]
},
"Tags": {
"Tag": [
{
"TagValue": "TestValue",
"TagKey": "TestKey"
}
]
},
"Attachments": {
"Attachment": [
{
"InstanceId": "i-bp67acfmxazb4q****",
"Device": "/dev/xvda",
"AttachedTime": "2021-06-07T06:08:56Z"
}
]
},
"ProvisionedIops": 40000,
"BurstingEnabled": false,
"Throughput": 100,
"ThroughputRead": 100,
"ThroughputWrite": 100,
"Placement": {
"ZoneIds": "\"[\"cn-hangzhou-b\",\n\"cn-hangzhou-j\"]\""
},
"SourceDiskId": "d-123*********",
"DataSource": {
"Id": "s-bp67acfmxazb4p****",
"Type": "snapshot"
}
}
]
}
}
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 parameter Status is not valid. Please set it to a supported disk status and try again. | |
| 400 | InvalidTag.Mismatch | The specified Tag.N.Key and Tag.N.Value do not match. Please check the tag key and value pair and try again. | |
| 400 | InvalidTagCount | The specified tags are beyond the permitted range. | The number of specified tags exceeds the upper limit. |
| 400 | InvalidRegion.NotFound | The specified RegionId does not exist. Please call DescribeRegions to query the supported regions and try again. | |
| 400 | InvalidZoneId.NotFound | The specified ZoneId does not exist. Please verify the ZoneId and the current region and try again. | |
| 400 | MissingParamter.RegionId | The specified parameter RegionId is missing. Please specify RegionId and try again. | |
| 400 | InvalidParameter.DiskIds | The specified parameter diskIds is not valid. | The specified DiskIds parameter is invalid. |
| 400 | IncompleteParamter | Some required parameters are missing in this request. Please check the required parameters and try again. | |
| 400 | InvalidParamter | Some parameters are invalid in this request. | The request contains invalid parameters. |
| 400 | InvalidSnapshot.NotFound | The specified SnapshotId does not exist. Please verify the SnapshotId and the current region and try again. | |
| 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 current account is not in the allowlist for this operation. Please submit a ticket to apply for access. | |
| 403 | InvalidParameter.MultiAttachAndEnableSharedNotMatch | The parameters MultiAttach and EnableShared do not match. Please check the values of both parameters and try again. | |
| 403 | InvalidParameter.MultiAttach | The specified parameter MultiAttach is not valid. Please set it to Disabled or Enabled and try again. | |
| 404 | InvalidFilterKey.NotFound | The specified Filter.N.Key does not exist. Please verify the Filter.N.Key and try again. | |
| 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 specified DiskChargeType does not exist. Please verify the DiskChargeType and try again. | |
| 404 | InvalidLockReason.NotFound | The specified LockReason does not exist. Please verify the LockReason and try again. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.