Queries block storage devices that you created, including cloud disks, local disks, and elastic ephemeral disks.
Operation description
Usage notes
-
You can specify multiple request parameters such as
RegionId
,ZoneId
,DiskIds
, andInstanceId
as filters. The specified 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
DiskIds
is a JSON array. If you do not specify DiskIds, the parameter is not used as a filter condition. If you setDiskIds
to an empty JSON array, the parameter 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 specify the pagination token. Set the value to theNextToken
value that is obtained from the previous query. Then, useMaxResults
to specify the maximum number of entries to return on each page. - Method 2: Use
PageSize
to specify the number of entries to return on each page, and then usePageNumber
to specify the number of the page 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
NextToken
is specified,PageSize
andPageNumber
do not take effect andTotalCount
in the response is invalid. - Method 1: Use
-
You can attach a disk for which the multi-attach feature is enabled to multiple instances. You can query the attachment information of the 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
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action
policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resources
is used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
Operation | Access level | Resource type | Condition key | Associated operation |
---|---|---|---|---|
ecs:DescribeDisks | list |
|
| none |
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
RegionId | string | Yes | The region ID of the disk. 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 cloud disks, local disks, or elastic ephemeral disks. The value is a JSON array that consists of up to 100 disk IDs. Separate the disk IDs with commas (,). | ["d-bp67acfmxazb4p****", "d-bp67acfmxazb4g****", … "d-bp67acfmxazb4d****"] |
InstanceId | string | No | The ID of the Elastic Compute Service (ECS) instance to which the disk is attached. | i-bp67acfmxazb4q**** |
DiskType | string | No | The type of the 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 |
Status | string | No | The status of the disk. For more information, see Disk states. Valid values:
Default value: All. | All |
SnapshotId | string | No | The ID of the snapshot from which you create the cloud disk. | s-bp67acfmxazb4p**** |
Portable | boolean | No | Specifies whether the disk is removable. Valid values:
The
| false |
DeleteWithInstance | boolean | No | Specifies whether the disk is released when the associated instance is released. Valid values:
Default value: false. | false |
DeleteAutoSnapshot | boolean | No | Specifies whether to delete the automatic snapshots of the cloud disk after the disk is released.
Default value: false | false |
PageNumber | integer | No | The page number. Pages start from page 1. Default value: 1. | 1 |
PageSize | integer | No | The number of entries to return per page. Maximum value: 100. Default value: 10. | 10 |
NextToken | string | No | The query token. Set the value to the For more information about how to check the responses returned by this operation, see the preceding "Description" section. | AAAAAdDWBF2**** |
MaxResults | integer | No | The maximum number of entries per page. 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 letters, digits, colons (:), underscores (_), periods (.), and hyphens (-). | testDiskName |
AutoSnapshotPolicyId | string | No | The ID of the automatic snapshot policy that is applied to the cloud disk. | sp-m5e2w2jutw8bv31**** |
EnableAutoSnapshot | boolean | No | Specifies whether to enable the automatic snapshot policy feature for the cloud disk.
Note
By default, the automatic snapshot policy feature is enabled for cloud disks that are already created. Additionally, only the automatic snapshot policy needs to be applied to a cloud disk before you can use the automatic snapshot policy.
| true |
EnableAutomatedSnapshotPolicy | boolean | No | Specifies whether an automatic snapshot policy is applied to the cloud 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:
| recycling |
Filter.1.Key | string | No | The key of filter 1 used to query resources. Set the value to | CreationStartTime |
Filter.2.Key | string | No | The key of filter 2 used to query resources. Set the value to | CreationEndTime |
Filter.1.Value | string | No | The value of filter 1 used to query resources. Set the value to a time. If you specify this parameter, you must also specify the | 2017-12-05T22:40Z |
Filter.2.Value | string | No | The value of filter 2 used to query resources. Set the value to a time. If you specify this parameter, you must also specify the | 2017-12-06T22:40Z |
ResourceGroupId | string | No | The ID of the resource group to which the disk belongs. If this parameter is specified to query resources, up to 1,000 resources that belong to the specified resource group can be displayed in the response. Note
Resources in the default resource group are displayed in the response regardless of the value specified for this parameter.
| 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.
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 that is used by the cloud disk. | 0e478b7a-4262-4802-b8cb-00d3fb40**** |
MultiAttach | string | No | Specifies whether the multi-attach feature is enabled for the disk. Valid values:
The multi-attach feature is available to select users. To use this feature, submit a ticket. | Disabled |
Tag | array<object> | No | The tags of the disk. | |
object | No | The information about the tags. | ||
key | string | No | The key of tag N of the disk. Note
We recommend that you use Tag.N.Key to ensure future compatibility.
| null |
Key | string | No | The key of tag N of the disk. Valid values of N: 1 to 20. If you specify a single tag to query resources, up to 1,000 resources to which the tag is added are returned. If you specify multiple tags to query resources, up to 1,000 resources to which all specified tags are added are returned. To query more than 1,000 resources that have specified tags added, call the ListTagResources operation. | TestKey |
Value | string | No | The value of tag N of the disk. Valid values of N: 1 to 20. | TestValue |
value | string | No | The value of tag N of the disk. Note
We recommend that you use Tag.N.Value to ensure future compatibility.
| null |
AdditionalAttributes | array | No | The attribute value. Set the value to IOPS, which indicates the maximum IOPS of the disk. | |
string | No | The attribute value. Set the value to IOPS, which indicates the maximum IOPS of the disk. | IOPS |
Response parameters
Examples
Sample success responses
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\ncn-hangzhou-j"
}
}
]
}
}
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. |
403 | InvalidDiskIds.Malformed | The amount of specified disk Ids exceeds the limit. | The specified disk ID is invalid. |
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. | 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. | - |
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. |
500 | InternalError | The request processing has failed due to some unknown error. | An internal error has occurred. Try again later. |
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation |
---|---|---|
2024-05-08 | The API operation is not deprecated.. The Error code has changed. The response structure of the API has changed | View Change Details |
2023-11-24 | The Error code has changed. The response structure of the API has changed | View Change Details |