All Products
Search
Document Center

Elastic Compute Service:DescribeDisks

Last Updated:Mar 19, 2024

Queries one or more block storage devices that you created, including cloud disks and local disks.

Operation description

Usage notes

  • You can specify multiple request parameters such as RegionId, ZoneId, DiskIds, and InstanceId 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 set DiskIds 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 the NextToken value that is obtained from the previous query. Then, use MaxResults 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 use PageNumber 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 and PageNumber do not take effect and TotalCount in the response is invalid.

  • 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

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID of the disk. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
ZoneIdstringNo

The zone ID.

cn-hangzhou-g
DiskIdsstringNo

The of disk IDs. 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****"]
InstanceIdstringNo

The ID of the instance to which the cloud disk or local disk is attached.

i-bp67acfmxazb4q****
DiskTypestringNo

The disk type. Valid values:

  • all: system disk and data disk
  • system: system disk
  • data: data disk

Default value: all.

all
CategorystringNo

The category of the disk. Valid values:

  • all: all disk categories
  • cloud: basic disk
  • cloud_efficiency: ultra disk
  • cloud_ssd: standard SSD
  • cloud_essd: enhanced SSD (ESSD)
  • cloud_auto: ESSD AutoPL disk
  • local_ssd_pro: I/O-intensive local disk
  • local_hdd_pro: throughput-intensive local disk
  • cloud_essd_entry: ESSD Entry disk
  • ephemeral: retired local disk
  • ephemeral_ssd: retired local SSD

Default value: all.

all
StatusstringNo

The state of the cloud disk. For more information, see Disk states. Valid values:

  • In_use
  • Available
  • Attaching
  • Detaching
  • Creating
  • ReIniting
  • All

Default value: All.

All
SnapshotIdstringNo

The ID of the snapshot from which you create the cloud disk.

s-bp67acfmxazb4p****
PortablebooleanNo

Specifies whether the disk is removable. Valid values:

  • true: The disk is removable. A removable disk can independently exist and can be attached to or detached from an instance within the same zone.
  • false: The disk is not removable. A disk that is not removable cannot independently exist nor can it be attached to or detached from an instance within the same zone.

The Portable attribute of the following disks is false, and these disks share the same lifecycle with their associated instances:

  • Local disks
  • Local SSDs
  • Subscription data disks
false
DeleteWithInstancebooleanNo

Specifies whether to release the cloud disk when its associated instance is released. Valid values:

  • true: The cloud disk is released when its associated instance is released.
  • false: The cloud disk is not released but is retained as a pay-as-you-go data disk after its associated instance is released.

Default value: false

false
DeleteAutoSnapshotbooleanNo

Specifies whether to delete the automatic snapshots of the cloud disk after the disk is released.

  • true
  • false

Default value: false

false
PageNumberintegerNo

The page number to return.

Pages start from page 1.

Default value: 1.

1
PageSizeintegerNo

The number of entries to return per page.

Maximum value: 100.

Default value: 10.

10
NextTokenstringNo

The query token. Set the value to the NextToken value that was returned in the last call to this operation.

For more information about how to check the responses returned by this operation, see the preceding "Description" section.

AAAAAdDWBF2****
MaxResultsintegerNo

The maximum number of entries per page. Valid values: 10 to 500.

Default value:

  • If you do not specify this parameter or you set this parameter to a value less than 10, the default value is 10.
  • If you set this parameter to a value greater than 500, the default value is 500.
50
DiskNamestringNo

The cloud disk or local disk name.

testDiskName
AutoSnapshotPolicyIdstringNo

The ID of the automatic snapshot policy that is applied to the cloud disk.

sp-m5e2w2jutw8bv31****
EnableAutoSnapshotbooleanNo

Specifies whether to enable the automatic snapshot policy feature for the cloud disk.

  • true
  • false
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
EnableAutomatedSnapshotPolicybooleanNo

Specifies whether an automatic snapshot policy is applied to the cloud disk.

  • true: An automatic snapshot policy is applied to the cloud disk.
  • false: No automatic snapshot policy is applied to the cloud disk.

Default value: false

false
DiskChargeTypestringNo

The disk billing method. Valid values:

  • PrePaid: subscription
  • PostPaid: pay-as-you-go
PostPaid
LockReasonstringNo

The reason why the disk is locked. Valid values:

  • financial: The disk is locked due to overdue payments.
  • security: The disk is locked due to security reasons.
  • recycling: The preemptible instance is locked and pending release.
  • dedicatedhostfinancial: The ECS instance is locked due to overdue payments of the dedicated host.
recycling
Filter.1.KeystringNo

The key of filter 1 used to query resources. Set the value to CreationStartTime. You can specify a time by setting both Filter.1.Key and Filter.1.Value to query resources that were created after the specified time.

CreationStartTime
Filter.2.KeystringNo

The key of filter 2 used to query resources. Set the value to CreationEndTime. You can specify a time by setting both Filter.2.Key and Filter.2.Value to query resources that were created before the specified time.

CreationEndTime
Filter.1.ValuestringNo

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 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.ValuestringNo

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 Filter.2.Key parameter. Specify the time in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.

2017-12-06T22:40Z
ResourceGroupIdstringNo

The ID of the resource group to which the disk belongs. If you specify this parameter to query resources, up to 1,000 resources that belong to the specified resource group can be returned.

Note Resources in the default resource group are displayed in the response regardless of whether you specify this parameter.
rg-bp67acfmxazb4p****
EnableSharedbooleanNo

Specifies whether the disk is a Shared Block Storage device.

false
EncryptedbooleanNo

Specifies whether to query only encrypted cloud disks.

  • true: queries only encrypted cloud disks.
  • false: does not query encrypted cloud disks.

Default value: false

false
DryRunbooleanNo

Specifies whether to perform only a dry run without performing the actual request. Valid values:

  • true: performs only a dry run. The systems checks whether your AccessKey pair is valid, whether RAM users are granted permissions, and whether the required parameters are specified. If the request fails the dry run, an error message is returned. If the request passes the dry run, the DryRunOperation error code is returned.
  • false: performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.

Default value: false

false
KMSKeyIdstringNo

The ID of the Key Management Service (KMS) key that is used by the cloud disk.

0e478b7a-4262-4802-b8cb-00d3fb40****
MultiAttachstringNo

Specifies whether the multi-attach feature is enabled for the disk. Valid values:

  • Disabled: The multi-attach feature is not enabled for the disk.
  • Enabled: The multi-attach feature is enabled for the disk.
  • LegacyShared: Shared Block Storage devices are queried.

The multi-attach feature is available to select users. To use this feature, submit a ticket.

Disabled
Tagobject []No

The tags of the disk.

keystringNo

The disk tag key.

Note We recommend that you use the Tag.N.Key parameter to ensure future compatibility.
null
KeystringNo

The disk tag key. Valid values of N: 1 to 20.

Up to 1,000 resources that match the specified tags can be returned in the response. To query more than 1,000 resources that match the specified tags, call the ListTagResources operation.

TestKey
ValuestringNo

The disk tag value. Valid values of N: 1 to 20.

TestValue
valuestringNo

The disk tag value.

Note We recommend that you use the Tag.N.Value parameter to ensure future compatibility.
null
AdditionalAttributesarrayNo

The attribute value. Set the value to IOPS, which indicates the maximum IOPS of the disk.

stringNo

The attribute value. Set the value to IOPS, which indicates the maximum IOPS of the disk.

IOPS

Response parameters

ParameterTypeDescriptionExample
object
NextTokenstring

The returned pagination token which can be used in the next request to retrieve a new page of results.

AAAAAdDWBF2****
PageSizeinteger

The number of entries per page.

1
PageNumberinteger

The returned page number.

1
RequestIdstring

The request ID.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCountinteger

The total number of entries returned.

15
Disksobject []

Details about the cloud disks or local disks.

SerialNumberstring

The serial number of the disk.

bp18um4r4f2fve2****
CreationTimestring

The time when the disk was created.

2021-06-07T06:08:54Z
Statusstring

The state of the cloud disk. Valid values:

  • In_use
  • Available
  • Attaching
  • Detaching
  • Creating
  • ReIniting
In_use
Typestring

The type of the disk. Valid values:

  • system: system disk
  • data: data disk
system
PerformanceLevelstring

The performance level of the ESSD. Valid values:

  • PL0: A single ESSD can deliver up to 10,000 random read/write IOPS.
  • PL1: A single ESSD can deliver up to 50,000 random read/write IOPS.
  • PL2: A single ESSD can deliver up to 100,000 random read/write IOPS.
  • PL3: A single ESSD can deliver up to 1,000,000 random read/write IOPS.
PL0
BdfIdstring

This parameter is in invitational preview and is not publicly available.

null
EnableAutoSnapshotboolean

Indicates whether the automatic snapshot policy feature is enabled for the disk.

false
StorageSetIdstring

The ID of the storage set.

ss-i-bp1j4i2jdf3owlhe****
StorageSetPartitionNumberinteger

The maximum number of partitions in the storage set.

11
DiskIdstring

The ID of the disk.

d-bp18um4r4f2fve24****
DeleteAutoSnapshotboolean

Indicates whether the automatic snapshots of the disk are deleted when the disk is released. Valid values:

  • true: The automatic snapshots of the cloud disk are deleted when the disk is released.
  • false: The automatic snapshots of the cloud disk are retained when the disk is released.

Snapshots that were created in the Elastic Compute Service (ECS) console or by calling the CreateSnapshot operation are retained and not affected by this parameter.

false
StorageClusterIdstring

The ID of the dedicated block storage cluster to which the disk belongs. If your disk belongs to the public block storage cluster, an empty value is returned.

dbsc-j5e1sf2vaf5he8m2****
Encryptedboolean

Indicates whether the cloud disk is encrypted.

false
IOPSReadinteger

The maximum number of read operations per second.

2000
MountInstanceNuminteger

The number of instances to which the Shared Block Storage device is attached.

1
Descriptionstring

The description of the disk.

testDescription
Devicestring

The device name of the disk on the instance to which the disk is attached. Example: /dev/xvdb. Take note of the following items:

  • This parameter has a value only when the Status value is In_use.
  • This parameter is empty for disks that have the multi-attach feature enabled. You can query the attachment information of the disk based on the Attachment values.
Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
/dev/xvdb
DiskNamestring

The name of the disk.

testDiskName
Portableboolean

Specifies whether the disk is removable.

false
ImageIdstring

The ID of the image that was used to create the instance. This parameter is empty unless the cloud disk was created from an image. The value of this parameter remains unchanged throughout the lifecycle of the cloud disk.

m-bp13aqm171qynt3u***
KMSKeyIdstring

The ID of the Key Management Service (KMS) key that is used for the disk.

0e478b7a-4262-4802-b8cb-00d3fb408***
DeleteWithInstanceboolean

Indicates whether the disk is released when the instance to which the disk is attached is released. Valid values:

  • true: The disk is released when the instance to which the disk is attached is released.
  • false: The disk is retained when the instance to which the disk is attached is released.
true
DetachedTimestring

The time when the disk was last detached.

2021-06-07T21:01:22Z
SourceSnapshotIdstring

The ID of the snapshot that was used to create the disk.

This parameter is empty unless the disk was created from a snapshot. The value of this parameter remains unchanged throughout the lifecycle of the disk.

s-bp67acfmxazb4p****
AutoSnapshotPolicyIdstring

The ID of the automatic snapshot policy that is applied to the disk.

sp-bp67acfmxazb4p****
EnableAutomatedSnapshotPolicyboolean

Indicates whether an automatic snapshot policy is applied to the disk.

false
IOPSWriteinteger

The maximum number of write IOPS of the disk.

2000
InstanceIdstring

The ID of the instance to which the disk is attached. Take note of the following items:

  • This parameter has a value only when the Status value is In_use.
  • This parameter is empty for disks that have the multi-attach feature enabled. You can query the attachment information of the disk based on the Attachment values.
i-bp67acfmxazb4q****
IOPSinteger

The maximum number of read/write IOPS of the disk.

4000
RegionIdstring

The region ID of the disk.

cn-hangzhou
ExpiredTimestring

The time when the subscription cloud disk expires.

2021-07-07T16:00Z
Sizeinteger

The size of the disk. Unit: GiB.

60
ResourceGroupIdstring

The ID of the resource group to which the disk belongs.

rg-bp67acfmxazb4p****
DiskChargeTypestring

The billing method of the disk. Valid values:

  • PrePaid: subscription
  • PostPaid: pay-as-you-go
PrePaid
ZoneIdstring

The zone ID of the disk.

cn-hangzhou-i
AttachedTimestring

The time when the disk was last attached. The time follows the ISO 8601 standard in the yyyy-MM-ddThh:mmZ format. The time must be in UTC.

2021-06-07T06:08:56Z
Categorystring

The category of the disk. Valid values:

  • cloud: basic disk
  • cloud_efficiency: ultra disk
  • cloud_ssd: standard SSD
  • cloud_essd: ESSD
  • cloud_auto: ESSD AutoPL disk
  • local_ssd_pro: I/O-intensive local disk
  • local_hdd_pro: throughput-intensive local disk
  • cloud_essd_entry: ESSD Entry disk
  • ephemeral: retired local disk
  • ephemeral_ssd: retired local SSD
cloud_ssd
ProductCodestring

The product code of the disk in Alibaba Cloud Marketplace.

jxsc000204
MultiAttachstring

Indicates whether the multi-attach feature is enabled for the disk.

Disabled
OperationLocksobject []

The reasons why the disk is locked.

LockReasonstring

The security reason why the disk is locked.

security
MountInstancesobject []

The attachment information of the Shared Block Storage device.

AttachedTimestring

The time when the disk was attached. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

2017-12-05T2340:00Z
InstanceIdstring

The ID of the instance to which the disk is attached.

i-bp1j4i2jdf3owlhe****
Devicestring

The mount point of the disk.

/dev/xvda
Tagsobject []

The tags of the disk.

TagValuestring

The tag value.

TestValue
TagKeystring

The tag key.

TestKey
Attachmentsobject []

The attachment information about the cloud disk. The value is an array that consists of the Attachment values. This value is not returned when you query Shared Block Storage devices.

InstanceIdstring

The ID of the instance to which the disk is attached.

i-bp67acfmxazb4q****
Devicestring

The device name of the disk.

/dev/xvda
AttachedTimestring

The time when the disk was attached. The time is displayed in UTC.

2021-06-07T06:08:56Z
ProvisionedIopslong

The provisioned read/write IOPS of the ESSD AutoPL disk. Valid values: 0 to min{50,000, 1,000 × *capacity - Baseline IOPS}. Baseline IOPS = min{1,800 + 50 × *Capacity, 50,000}

This parameter is available only if you set DiskCategory to cloud_auto. For more information, see ESSD AutoPL disks.

40000
BurstingEnabledboolean

Indicates whether the performance burst feature is enabled. Valid values:

  • true
  • false

This parameter is available only if you set DiskCategory to cloud_auto. For more information, see ESSD AutoPL disks.

false
Throughputinteger

The amount of data that is transferred per second. Unit: MB/s.

100
ThroughputReadinteger

The amount of data that is read by the system per second. Unit: MB/s.

100
ThroughputWriteinteger

The amount of data that is written by the system per second. Unit: MB/s.

100

Examples

Sample success responses

JSONformat

{
  "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
      }
    ]
  }
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidDiskType.ValueNotSupportedThe specified disk type is not supported.The specified disk type is not supported.
400InvalidCategory.ValueNotSupportedThe specified disk category is not supported.The specified disk category is not supported.
400InvalidStatus.ValueNotSupportedThe specified disk status is not supported.The disk is in a state that does not support the current operation.
400InvalidTag.MismatchThe 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.
400InvalidTagCountThe specified tags are beyond the permitted range.The number of specified tags exceeds the upper limit.
400InvalidRegion.NotFoundThe specified parameter RegionId is not valid.The specified RegionId parameter is invalid.
400InvalidZoneId.NotFoundThe zoneId provided does not exist in our records.The specified zone ID does not exist.
400MissingParamter.RegionIdThe regionId should not be null.The RegionId parameter is required.
400InvalidParameter.DiskIdsThe specified parameter diskIds is not valid.The specified DiskIds parameter is invalid.
400IncompleteParamterSome fields can not be null in this request.Some required parameters are not specified.
400InvalidParamterSome parameters are invalid in this request.The request contains invalid parameters.
400InvalidSnapshot.NotFoundThe specified parameter SnapshotId is not valid.The specified SnapshotId parameter is invalid.
403InvalidDiskIds.MalformedThe amount of specified disk Ids exceeds the limit.The specified disk ID is invalid.
403UserNotInTheWhiteListThe 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.
403InvalidParameter.MultiAttachAndEnableSharedNotMatchThe parameter MultiAttach and EnableShared are not match.The specified MultiAttach and EnableShared parameters do not match.
403InvalidParameter.MultiAttachThe specified param MultiAttach is not valid.The specified MultiAttach parameter is invalid.
404InvalidDiskChargeType.NotFoundThe DiskChargeType does not exist in our recordsThe specified DiskChargeType parameter does not exist.
404InvalidLockReason.NotFoundThe specified LockReason is not foundThe specified LockReason parameter does not exist.
404InvalidFilterKey.NotFoundThe filter key is not found.-
404InvalidFilterValueThe filter value is not valid.-
404InvalidDiskIds.ValueNotSupportedThe specified parameter "DiskIds" is not supported.-
500InternalErrorThe 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 timeSummary of changesOperation
2023-11-24The Error code has changed. The response structure of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
Output ParametersThe response structure of the API has changed.