DescribeDisks - - 阿里雲

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

Usage notes

You can configure multiple request parameters such as RegionId, ZoneId, DiskIds, and InstanceId as filters. Configured 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 the DiskIds parameter is a JSON array. If the DiskIds parameter is not configured, it is not used as a filter. If the DiskIds parameter is set to an empty JSON array, it 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 configure the query token. Set the value to the NextToken value that was returned in the last call made to the DescribeDisks operation. Then, use MaxResults to specify the maximum number of entries to return per page.
- Method 2: Configure the PageSize parameter to specify the number of entries to return per page, and configure the PageNumber parameter to specify the page number 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 the NextToken parameter is configured, the PageSize and PageNumber parameters do not take effect and the TotalCount parameter in the response is invalid.
A cloud disk that has the multi-attach feature enabled can be attached to multiple instances. You can query the attachment information of the cloud 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. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter	Type	Required	Example	Description
Action	String	Yes	DescribeDisks	The operation that you want to perform. Set the value to DescribeDisks.
RegionId	String	Yes	cn-hangzhou	The region ID of the block storage device. You can call the DescribeRegions operation to query the most recent region list.
ZoneId	String	No	cn-hangzhou-g	The zone ID.
DiskIds	String	No	["d-bp67acfmxazb4p**", "d-bp67acfmxazb4g", … "d-bp67acfmxazb4d**"]	The disk IDs. The value is a JSON array that consists of up to 100 disk IDs. Separate the disk IDs with commas (,).
InstanceId	String	No	i-bp67acfmxazb4q****	The ID of the instance to which the disk is attached.
DiskType	String	No	all	The type of the disk. Valid values: all: system disk and data disk system: system disk data: data disk Default value: all.
Category	String	No	all	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.
Status	String	No	All	The status of the cloud disk. For more information, see Disk states. Valid values: In_use Available Attaching Detaching Creating ReIniting All Default value: All.
SnapshotId	String	No	s-bp67acfmxazb4p****	The ID of the snapshot used to create the cloud disk.
Portable	Boolean	No	false	Specifies whether the disk is removable. Valid values: true. A removable disk can independently exist and can be attached to or detached from an instance within the same zone. false. A disk that is not removable cannot independently exist or be attached to or detached from an instance within the same zone. The `Portable` attribute of the following types of disks is `false`, and these types of disks share the same lifecycle with their associated instances: Local disks Local SSDs Subscription data disks
DeleteWithInstance	Boolean	No	false	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 when its associated instance is released. Default value: false.
DeleteAutoSnapshot	Boolean	No	false	Specifies whether to delete the auto snapshots of the cloud disk when the cloud disk is released. true false Default value: false.
PageNumber	Integer	No	1	The page number. Pages start from page 1. Default value: 1.
PageSize	Integer	No	10	The number of entries per page. Maximum value: 100. Default value: 10.
NextToken	String	No	AAAAAdDWBF2****	The pagination token that is used in the next request to retrieve a new page of results. You must specify the token that is obtained from the previous query as the value of `NextToken`. For information about how to check the responses returned by this operation, see the "Usage notes" section in this topic.
MaxResults	Integer	No	50	The number of entries per page. Valid values: 10 to 500. Take note of the following items: If this parameter is not configured or is set to a value smaller than 10, the value 10 is used. If this parameter is set to a value greater than 500, the value 500 is used.
DiskName	String	No	testDiskName	The name of the disk.
AutoSnapshotPolicyId	String	No	sp-m5e2w2jutw8bv31****	The ID of the automatic snapshot policy that is applied to the cloud disk.
EnableAutoSnapshot	Boolean	No	true	Specifies whether to enable the automatic snapshot policy feature for the cloud disk. Valid values: true false Note By default, the automatic snapshot policy feature is enabled for created cloud disks. You need to only apply an automatic snapshot policy to a cloud disk before you can use the automatic snapshot policy.
EnableAutomatedSnapshotPolicy	Boolean	No	false	Specifies whether an automatic snapshot policy is applied to the cloud disk. Valid values: true false Default value: false.
DiskChargeType	String	No	PostPaid	The billing method of the disk. Valid values: PrePaid: subscription PostPaid: pay-as-you-go
LockReason	String	No	recycling	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 for the dedicated host.
Filter.1.Key	String	No	CreationStartTime	The key of filter 1 that is used to query resources. Set the value to `CreationStartTime`. You can specify a point in time by configuring both the `Filter.1.Key` and `Filter.1.Value` parameters to query resources that are created after the specified point in time.
Filter.2.Key	String	No	CreationEndTime	The key of filter 2 that is used to query resources. Set the value to `CreationEndTime`. You can specify a point in time by configuring both the `Filter.2.Key` and `Filter.2.Value` parameters to query resources that are created before the specified point in time.
Filter.1.Value	String	No	2017-12-05T22:40Z	The value of filter 1 that is used to query resources. If you configure this parameter, you must also configure the `Filter.1.Key` parameter. Set the value in the ISO 8601 standard in the `yyyy-MM-ddTHH:mm:ssZ` format. The time must be in UTC.
Filter.2.Value	String	No	2017-12-06T22:40Z	The value of filter 2 that is used to query resources. If you configure this parameter, you must also configure the `Filter.2.Key` parameter. Set the value in the ISO 8601 standard in the `yyyy-MM-ddTHH:mm:ssZ` format. The time must be in UTC.
ResourceGroupId	String	No	rg-bp67acfmxazb4p****	The ID of the resource group to which the disk belongs. If you use this parameter to filter resources, the number of resources in a specified resource group cannot exceed 1,000. Note Resources in the default resource group cannot be filtered.
EnableShared	Boolean	No	false	Specifies whether the disk is a Shared Block Storage device.
Encrypted	Boolean	No	false	Specifies whether to query only encrypted cloud disks. Valid values: true false Default value: false.
DryRun	Boolean	No	false	Specifies whether to perform only a dry run, without performing the actual request. Valid values: true: performs only a dry run. The system checks the request for potential issues, including invalid AccessKey pairs, unauthorized RAM users, and missing parameter values. If the request passes the dry run, the `DryRunOperation` error code is returned. Otherwise, an error message 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.
KMSKeyId	String	No	0e478b7a-4262-4802-b8cb-00d3fb40****	The ID of the Key Management Service (KMS) key used by the cloud disk.
MultiAttach	String	No	Disabled	Specifies whether the multi-attach feature is enabled. Valid values: Disabled: The multi-attach feature is not enabled. Enabled: The multi-attach feature is enabled. LegacyShared: Shared Block Storage devices are queried. The multi-attach feature is in invitational preview. To use this feature, submit a ticket.
Tag.N.key	String	No	null	The key of tag N of the disk. Note We recommend that you use the other Tag.N.Key parameter to ensure compatibility.
Tag.N.Key	String	No	TestKey	The key of tag N of the disk. Valid values of N: 1 to 20. If a single tag is specified to query resources, up to 1,000 resources that have this tag added are returned. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags added are returned. To query more than 1,000 resources with the specified tags, call the ListTagResources operation.
Tag.N.Value	String	No	TestValue	The value of tag N of the disk. Valid values of N: 1 to 20.
Tag.N.value	String	No	null	The value of tag N of the disk. Note We recommend that you use the other Tag.N.Value parameter to ensure compatibility.
AdditionalAttributes.N	String	No	IOPS	The value of attribute N. Set the value to IOPS, which indicates the maximum input/output operations per second (IOPS) of the disk.

Response parameters

Parameter	Type	Example	Description
NextToken	String	AAAAAdDWBF2****	The query token returned in this call.
PageSize	Integer	1	The number of entries per page.
PageNumber	Integer	1	The page number.
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E	The request ID.
TotalCount	Integer	15	The total number of entries returned.
Disks	Array of Disk		Details about the disks.
Disk
SerialNumber	String	bp18um4r4f2fve2****	The serial number of the disk.
CreationTime	String	2021-06-07T06:08:54Z	The time when the disk was created.
Status	String	In_use	The status of the cloud disk. Valid values: In_use Available Attaching Detaching Creating ReIniting
Type	String	system	The type of the disk. Valid values: system: system disk data: data disk
PerformanceLevel	String	PL0	The performance level of the ESSD. Valid values: PL0: A single ESSD can provide up to 10,000 random read/write IOPS. PL1: A single ESSD can provide up to 50,000 random read/write IOPS. PL2: A single ESSD can provide up to 100,000 random read/write IOPS. PL3: A single ESSD can provide up to 1,000,000 random read/write IOPS.
BdfId	String	null	This parameter is in invitational preview and is not publicly available.
EnableAutoSnapshot	Boolean	false	Indicates whether the automatic snapshot policy feature is enabled for the cloud disk.
StorageSetId	String	ss-i-bp1j4i2jdf3owlhe****	The storage set ID.
StorageSetPartitionNumber	Integer	11	The maximum number of partitions in the storage set.
DiskId	String	d-bp18um4r4f2fve24****	The disk ID.
DeleteAutoSnapshot	Boolean	false	Indicates whether the auto snapshots of the cloud disk are deleted when the cloud disk is released. Valid values: true: The auto snapshots of the cloud disk are deleted when the cloud disk is released. false: The auto snapshots of the cloud disk are retained when the cloud disk is released. Snapshots that are created in the ECS console or by calling the CreateSnapshot operation are retained and not affected by this parameter.
StorageClusterId	String	dbsc-j5e1sf2vaf5he8m2****	The ID of the dedicated block storage cluster to which the cloud disk belongs. If your cloud disk belongs to the public block storage cluster, an empty value is returned.
Encrypted	Boolean	false	Indicates whether the cloud disk is encrypted.
IOPSRead	Integer	2000	The maximum number of I/O read operations per second.
MountInstanceNum	Integer	1	The number of instances to which the Shared Block Storage device is attached.
Description	String	testDescription	The description of the disk.
Device	String	/dev/xvdb	The device name of the disk on its associated instance. Example: /dev/xvdb. Take note of the following items: This parameter has a value only if the `Status` parameter is set to `In_use`. This parameter is empty for cloud disks that have the multi-attach feature enabled. You can query the attachment information of the cloud disk based on the `Attachment` values. Note This parameter will be deprecated. We recommend that you use other parameters to ensure compatibility.
DiskName	String	testDiskName	The name of the disk.
Portable	Boolean	false	Indicates whether the disk is removable.
ImageId	String	m-bp13aqm171qynt3u***	The ID of the image used to create the instance. This parameter is empty unless the cloud disk is created from an image. The value of this parameter remains unchanged throughout the lifecycle of the cloud disk.
KMSKeyId	String	0e478b7a-4262-4802-b8cb-00d3fb408***	The ID of the KMS key that is used by the cloud disk.
DeleteWithInstance	Boolean	true	Indicates whether the cloud disk is released when its associated instance is released. Valid values: true false
DetachedTime	String	2021-06-07T21:01:22Z	The time when the cloud disk was last detached.
SourceSnapshotId	String	s-bp67acfmxazb4p****	The ID of the snapshot that is used to create the cloud disk. This parameter is left empty unless the cloud disk is created from a snapshot. The value of this parameter remains unchanged throughout the lifecycle of the cloud disk.
AutoSnapshotPolicyId	String	sp-bp67acfmxazb4p****	The ID of the automatic snapshot policy that is applied to the cloud disk.
EnableAutomatedSnapshotPolicy	Boolean	false	Indicates whether an automatic snapshot policy is applied to the cloud disk.
IOPSWrite	Integer	2000	The maximum number of write operations per second.
InstanceId	String	i-bp67acfmxazb4q****	The ID of the instance to which the disk is attached. Take note of the following items: This parameter has a value only if the `Status` parameter is set to `In_use`. This parameter is left empty for cloud disks that have the multi-attach feature enabled. You can query the attachment information of the cloud disk based on the `Attachment` values.
IOPS	Integer	4000	The maximum number of IOPS.
RegionId	String	cn-hangzhou	The region ID of the disk.
ExpiredTime	String	2021-07-07T16:00Z	The time when the subscription cloud disk expires.
Size	Integer	60	The size of the disk. Unit: GiB.
ResourceGroupId	String	rg-bp67acfmxazb4p****	The ID of the resource group to which the disk belongs.
DiskChargeType	String	PrePaid	The billing method of the disk. Valid values: PrePaid: subscription PostPaid: pay-as-you-go
ZoneId	String	cn-hangzhou-i	The zone ID of the disk.
AttachedTime	String	2021-06-07T06:08:56Z	The time when the cloud disk was last attached. The time follows the ISO 8601 standard in the yyyy-MM-ddThh:mmZ format. The time is displayed in UTC.
Category	String	cloud_ssd	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
ProductCode	String	jxsc000204	The product code in Alibaba Cloud Marketplace.
MultiAttach	String	Disabled	Indicates whether the multi-attach feature is enabled for the cloud disk.
OperationLocks	Array of OperationLock		The reasons why the disk is locked.
OperationLock
LockReason	String	security	The security reason why the disk is locked.
MountInstances	Array of MountInstance		The attachment information of the Shared Block Storage device.
MountInstance
AttachedTime	String	2017-12-05T2340:00Z	The attachment time. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
InstanceId	String	i-bp1j4i2jdf3owlhe****	The ID of the instance to which the disk is attached.
Device	String	/dev/xvda	The mount point of the disk.
Tags	Array of Tag		The tags of the disk.
Tag
TagValue	String	TestValue	The tag value of the disk.
TagKey	String	TestKey	The tag key of the disk.
Attachments	Array of Attachment		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.
Attachment
InstanceId	String	i-bp67acfmxazb4q****	The ID of the instance to which the disk is attached.
Device	String	/dev/xvda	The device name of the disk.
AttachedTime	String	2021-06-07T06:08:56Z	The attachment time. The time is displayed in UTC.
ProvisionedIops	Long	40000	The provisioned read/write IOPS of the ESSD AutoPL disk. Valid values: 0 to min{50,000, 1,000 × Capacity - Baseline IOPS}. Baseline performance = min{1,800 + 50 × Capacity, 50,000} This parameter is supported only if the `DiskCategory` parameter is set to `cloud_auto`. For more information, see ESSD AutoPL disks.
BurstingEnabled	Boolean	false	Indicates whether the performance burst feature is enabled. Valid values: true false This parameter is supported only if the `DiskCategory` parameter is set to `cloud_auto`. For more information, see ESSD AutoPL disks.
Throughput	Integer	100	The amount of data transferred per second. Unit: MB/s.
ThroughputRead	Integer	100	The amount of data that is read by the system per second. Unit: MB/s.
ThroughputWrite	Integer	100	The amount of data that is written by the system per second. Unit: MB/s.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=DescribeDisks
&RegionId=cn-hangzhou
&PageNumber=1
&PageSize=1
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeDisksResponse>
    <TotalCount>15</TotalCount>
    <NextToken>AAAAAdDWBF2****</NextToken>
    <PageSize>1</PageSize>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
    <PageNumber>1</PageNumber>
    <Disks>
        <Disk>
            <DetachedTime/>
            <Category>cloud_ssd</Category>
            <Description>testDescription</Description>
            <KMSKeyId/>
            <ResourceGroupId/>
            <DedicatedBlockStorageClusterId/>
            <Encrypted>false</Encrypted>
            <Size>40</Size>
            <DeleteAutoSnapshot>false</DeleteAutoSnapshot>
            <DiskChargeType>PrePaid</DiskChargeType>
            <MultiAttach>Disabled</MultiAttach>
            <Attachments>
                <Attachment>
                    <AttachedTime>2021-06-07T06:08:56Z</AttachedTime>
                    <InstanceId>i-bp67acfmxazb4q****</InstanceId>
                    <Device>/dev/xvda</Device>
                </Attachment>
            </Attachments>
            <ExpiredTime>2021-07-07T16:00Z</ExpiredTime>
            <ImageId>m-bp13aqm171qynt3u***</ImageId>
            <StorageSetId/>
            <Tags>
            </Tags>
            <Status>In_use</Status>
            <AttachedTime>2021-06-07T06:08:56Z</AttachedTime>
            <StorageClusterId>dbsc-j5e1sf2vaf5he8m2****</StorageClusterId>
            <ZoneId>cn-hangzhou-i</ZoneId>
            <InstanceId>i-bp67acfmxazb4q****</InstanceId>
            <SourceSnapshotId/>
            <ProductCode/>
            <PerformanceLevel>PL0</PerformanceLevel>
            <Device>/dev/xvdb</Device>
            <DeleteWithInstance>true</DeleteWithInstance>
            <EnableAutomatedSnapshotPolicy>false</EnableAutomatedSnapshotPolicy>
            <EnableAutoSnapshot>false</EnableAutoSnapshot>
            <AutoSnapshotPolicyId>sp-bp67acfmxazb4p****</AutoSnapshotPolicyId>
            <DiskName>testDiskName</DiskName>
            <OperationLocks>
            </OperationLocks>
            <BdfId/>
            <Portable>false</Portable>
            <Type>system</Type>
            <SerialNumber>bp18um4r4f2fve2****</SerialNumber>
            <CreationTime>2021-06-07T06:08:54Z</CreationTime>
            <RegionId>cn-hangzhou</RegionId>
            <DiskId>d-bp18um4r4f2fve24****</DiskId>
        </Disk>
    </Disks>
</DescribeDisksResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "TotalCount" : 15,
  "NextToken" : "AAAAAdDWBF2****",
  "PageSize" : 1,
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "PageNumber" : 1,
  "Disks" : {
    "Disk" : [ {
      "DetachedTime" : "",
      "Category" : "cloud_ssd",
      "Description" : "testDescription",
      "KMSKeyId" : "",
      "ResourceGroupId" : "",
      "DedicatedBlockStorageClusterId" : "",
      "Encrypted" : false,
      "Size" : 40,
      "DeleteAutoSnapshot" : false,
      "DiskChargeType" : "PrePaid",
      "MultiAttach" : "Disabled",
      "Attachments" : {
        "Attachment" : [ {
          "AttachedTime" : "2021-06-07T06:08:56Z",
          "InstanceId" : "i-bp67acfmxazb4q****",
          "Device" : "/dev/xvda"
        } ]
      },
      "ExpiredTime" : "2021-07-07T16:00Z",
      "ImageId" : "m-bp13aqm171qynt3u***",
      "StorageSetId" : "",
      "Tags" : {
        "Tag" : [ ]
      },
      "Status" : "In_use",
      "AttachedTime" : "2021-06-07T06:08:56Z",
      "StorageClusterId" : "dbsc-j5e1sf2vaf5he8m2****",
      "ZoneId" : "cn-hangzhou-i",
      "InstanceId" : "i-bp67acfmxazb4q****",
      "SourceSnapshotId" : "",
      "ProductCode" : "",
      "PerformanceLevel" : "PL0",
      "Device" : "/dev/xvdb",
      "DeleteWithInstance" : true,
      "EnableAutomatedSnapshotPolicy" : false,
      "EnableAutoSnapshot" : false,
      "AutoSnapshotPolicyId" : "sp-bp67acfmxazb4p****",
      "DiskName" : "testDiskName",
      "OperationLocks" : {
        "OperationLock" : [ ]
      },
      "BdfId" : "",
      "Portable" : false,
      "Type" : "system",
      "SerialNumber" : "bp18um4r4f2fve2****",
      "CreationTime" : "2021-06-07T06:08:54Z",
      "RegionId" : "cn-hangzhou",
      "DiskId" : "d-bp18um4r4f2fve24****"
    } ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidDiskType.ValueNotSupported	The specified disk type is not supported.	Invalid disk type.
400	InvalidCategory.ValueNotSupported	The specified disk category is not supported.	Invalid disk category.
400	InvalidStatus.ValueNotSupported	The specified disk status is not supported.	This operation cannot be performed on the disk in the current state.
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 maximum number of tags is exceeded.
400	InvalidRegion.NotFound	The specified parameter RegionId is not valid.	Invalid RegionId value.
400	InvalidZoneId.NotFound	The zoneId provided does not exist in our records.	The specified zone ID is not found.
400	MissingParamter.RegionId	The regionId should not be null.	RegionId is required.
400	InvalidParameter.DiskIds	The specified parameter diskIds is not valid.	Invalid DiskIds value.
400	IncompleteParamter	Some fields can not be null in this request.	A required parameter is 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.	Invalid SnapshotId value.
403	InvalidDiskIds.Malformed	The amount of specified disk Ids exceeds the limit.	Invalid DiskIds value.
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.	Invalid MultiAttach value.
404	InvalidDiskChargeType.NotFound	The DiskChargeType does not exist in our records	The DiskChargeType is not found.
404	InvalidLockReason.NotFound	The specified LockReason is not found	The LockReason is not found.
500	InternalError	The request processing has failed due to some unknown error.	An internal error occurred. Try again later.

For a list of error codes, see Service error codes.