DescribeDisks
Queries information about one or more created block storage devices, including disks, local disks, and elastic ephemeral disks.
Operation description
-
The request parameters RegionId, ZoneId, DiskIds, and InstanceId are filters. These parameters have a logical AND relationship.
-
The DiskIds request parameter is a JSON format array. If DiskIds is not specified, the filter does not take effect. However, if DiskIds is set to an empty array, the filter is considered valid and an empty result is returned.
-
Token-based paged query is supported. Set the NextToken parameter to the NextToken value returned in the previous call of DescribeDisks, and use MaxResults to specify the maximum number of entries per page.
-
A disk that has the multi-attach feature enabled can be attached to multiple instances. You can check the Attachment list in the response to view all attachment information of the disk.
When you invoke an API operation by using Cloud Assistant CLI, specify request parameters of different data types in the required formats. For more information, see Parameter format overview.
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 DescribeRegions to query the most recent region list. |
cn-hangzhou |
| ZoneId |
string |
No |
The zone ID. |
cn-hangzhou-g |
| DiskIds |
string |
No |
The IDs of disks, local disks, or elastic ephemeral disks. The value is a JSON array that can contain up to 100 IDs. Separate the IDs with commas (,). |
["d-bp67acfmxazb4p****", "d-bp67acfmxazb4g****", … "d-bp67acfmxazb4d****"] |
| InstanceId |
string |
No |
The instance ID of the instance 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:
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 |
| 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 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 lifecycle is the same as that of the associated instance:
|
false |
| DeleteWithInstance |
boolean |
No |
Specifies whether the disk is set to be released together with the instance. Valid values:
Default value: false. |
false |
| DeleteAutoSnapshot |
boolean |
No |
Specifies whether automatic snapshots are released when the disk is released.
Default value: false. |
false |
| PageNumber |
integer |
No |
Note
This parameter is about to be deprecated. Use NextToken and MaxResults to complete paging operations. |
1 |
| PageSize |
integer |
No |
Note
This parameter is about to be deprecated. Use NextToken and MaxResults to complete paging operations. |
10 |
| NextToken |
string |
No |
The pagination token. Set this parameter to the NextToken value returned in the previous API call. For information about how to view the returned data, 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 characters under the letter category (including letters from various languages, digits, and other characters). The name can contain colons (:), underscores (_), periods (.), or hyphens (-). |
testDiskName |
| AutoSnapshotPolicyId |
string |
No |
The ID of the automatic snapshot policy used to query disks. |
sp-m5e2w2jutw8bv31**** |
| EnableAutoSnapshot |
boolean |
No |
Specifies whether the automatic snapshot policy feature is enabled for the disk.
Note
This parameter is deprecated. The automatic snapshot policy feature is enabled by default for disks after creation. You only need to associate an automatic snapshot policy with the disk. |
true |
| EnableAutomatedSnapshotPolicy |
boolean |
No |
Specifies whether an automatic snapshot policy is configured for the disk.
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 |
| Filter.2.Key |
string |
No |
The filter key used to query resources. Set the value to |
CreationEndTime |
| Filter.1.Value |
string |
No |
The filter value used to query resources. When you specify this parameter, you must also specify the Filter.1.Key parameter. Specify the time in the |
2017-12-05T22:40Z |
| Filter.2.Value |
string |
No |
The filter value used to query resources. When you specify this parameter, you must also specify the Filter.2.Key parameter. Specify the time in the |
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 disks.
Default value: false. |
false |
| DryRun |
boolean |
No |
Specifies whether to perform only a dry run, without performing the actual request. Valid values:
Default value: false. |
false |
| KMSKeyId |
string |
No |
The ID of the Key Management Service (KMS) key used by the 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. If you use a single tag to filter resources, the resource count with the specified tag cannot exceed 1,000. If you use multiple tags to filter resources, the resource count of resources that are attached to all specified tags cannot exceed 1,000. If the resource count exceeds 1,000, call the ListTagResources operation. |
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 attribute values. The only valid value is Note
Only regional disks have a data storage location. |
IOPS |
|
string |
No |
The additional attribute value. The only valid value is Placement, which queries the data storage location of the disk. |
Placement |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| NextToken |
string |
The query token returned in this call. |
AAAAAdDWBF2**** |
| PageSize |
integer |
Note
This parameter will be offline soon. Use |
1 |
| PageNumber |
integer |
Note
This parameter will be offline soon. Use |
1 |
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
| TotalCount |
integer |
The total number of entries returned. Note
When you use |
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 follows the ISO 8601 standard in UTC. |
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 (PL) of the enterprise SSD (ESSD). Valid values:
|
PL0 |
| BdfId |
string |
This parameter is in invitational preview and is not publicly available. |
null |
| EnableAutoSnapshot |
boolean |
Indicates whether the automatic snapshot policy feature is enabled for the disk. Note
This parameter is deprecated. After a disk is created, the automatic snapshot policy feature is enabled by default. You only need to associate an automatic snapshot policy with 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 CreateSnapshot or by using the ECS 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 belongs to a public block storage cluster, this value is empty. |
dbsc-j5e1sf2vaf5he8m2**** |
| Encrypted |
boolean |
Indicates whether the disk is encrypted. |
false |
| IOPSRead |
integer |
The maximum number of read operations per second. Unit: operations/s. |
2000 |
| MountInstanceNum |
integer |
The number of instances to which the Shared Block Storage device is attached. |
1 |
| Description |
string |
The disk description. |
testDescription |
| Device |
string |
The device name of the disk on the instance to which the disk is attached, such as /dev/xvdb. Take note of the following items:
Note
This parameter is being deprecated. For better code compatibility, do not use this parameter. |
/dev/xvdb |
| DiskName |
string |
The disk name. |
testDiskName |
| Portable |
boolean |
Indicates whether the disk is removable. |
false |
| ImageId |
string |
The ID of the image that was used to create the ECS instance. This parameter has a value only for disks created from an image. Otherwise, this value is empty. If the image used to create the disk is deleted, this value is also empty. |
m-bp13aqm171qynt3u*** |
| KMSKeyId |
string |
The ID of the Key Management Service (KMS) key used by the disk. |
0e478b7a-4262-4802-b8cb-00d3fb408*** |
| DeleteWithInstance |
boolean |
Indicates whether the disk is released when the instance is released. Valid values:
|
true |
| DetachedTime |
string |
The time when the disk was last detached. The time follows the ISO 8601 standard in UTC. |
2021-06-07T21:01:22Z |
| SourceSnapshotId |
string |
The ID of the snapshot that was used to create the disk. If no snapshot was specified when the disk was created, this value is empty. If the snapshot used to create the disk is deleted, this value is also empty. |
s-bp67acfmxazb4p**** |
| AutoSnapshotPolicyId |
string |
The ID of the automatic snapshot policy applied to the disk. Note
This parameter is being deprecated. If multiple automatic snapshot policies are applied to the disk, only one of them is returned. Use DescribeAutoSnapshotPolicyAssociations 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. Unit: operations/s. |
2000 |
| InstanceId |
string |
The instance 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/write (I/O) operations per second. Unit: operations/s. |
4000 |
| RegionId |
string |
The region ID of the disk. |
cn-hangzhou |
| ExpiredTime |
string |
The expiration time of the subscription disk. The time follows the ISO 8601 standard in UTC. |
2021-07-07T16:00Z |
| Size |
integer |
The size of the disk. 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 time when the disk was last attached. The time follows the ISO 8601 standard in UTC+0. Format: yyyy-MM-ddThh:mmZ. |
2021-06-07T06:08:56Z |
| Category |
string |
The category of the disk. Valid values:
|
cloud_ssd |
| ProductCode |
string |
The product code of the Alibaba Cloud Marketplace image. |
jxsc000204 |
| MultiAttach |
string |
Indicates 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 by security. |
security |
| MountInstances |
object |
||
| MountInstance |
array<object> |
The collection of information about the instances to which the Shared Block Storage device is attached. |
|
|
object |
The information about the instance to which the Shared Block Storage device is attached. |
||
| AttachedTime |
string |
The time when the disk was attached. The time follows the ISO 8601 standard in UTC+0. Format: yyyy-MM-ddTHH:mm:ssZ. |
2017-12-05T2340:00Z |
| InstanceId |
string |
The instance 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 collection of 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 is a list of |
|
|
object |
The attachment information of the disk. |
||
| InstanceId |
string |
The instance 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, in UTC+0. |
2021-06-07T06:08:56Z |
| ProvisionedIops |
integer |
The provisioned read/write IOPS of the ESSD AutoPL disk. Valid values: 0 to min{50000, 1000 × Capacity - Baseline performance}. Baseline performance = min{1,800 + 50 × Capacity, 50,000}. This parameter is supported only when |
40000 |
| BurstingEnabled |
boolean |
Indicates whether the performance burst (Burst) feature is enabled. Valid values:
This parameter is supported only when |
false |
| Throughput |
integer |
The amount of data that can be transferred per unit of time. Unit: MB/s. |
100 |
| ThroughputRead |
integer |
The amount of data that the system can read per unit of time. Unit: MB/s. |
100 |
| ThroughputWrite |
integer |
The amount of data that the system can write per unit of time. Unit: MB/s. |
100 |
| Placement |
object |
The data placement information. This field is returned only when AdditionalAttributes.N = Placement is specified in the request. Note
Currently, only regional ESSDs (cloud_regional_disk_auto) have valid values. |
|
| ZoneIds |
string |
The list of zones where the data is stored. |
"["cn-hangzhou-b", "cn-hangzhou-j"]" |
| SourceDiskId |
string |
The source disk ID. |
d-123********* |
| DataSource |
object |
||
| Id |
string |
||
| Type |
string |
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": "",
"Type": ""
}
}
]
}
}
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 disk category is not supported. | The specified disk category is not supported. |
| 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. |
| 500 | InternalError | The request processing has failed due to some unknown error. | |
| 403 | InvalidDiskIds.Malformed | The amount of specified disk Ids exceeds the limit. | |
| 403 | InvalidCategory.ValueNotSupported | The specified disk category is not supported. | |
| 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 param MultiAttach is not valid. | The specified MultiAttach parameter is invalid. |
| 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.