DescribeDisks - 查询块存储 - 云服务器 ECS

查询一块或多块已创建的块存储（包括云盘、本地盘以及弹性临时盘）信息。

接口说明

请求参数RegionId、ZoneId、DiskIds和InstanceId等都是过滤器的概念，参数间是逻辑与（AND）关系。
请求参数DiskIds是一个 JSON 格式的数组（Array），如果参数为空，则过滤器不起作用，但是DiskIds如果是一个空数组，则视为该过滤器有效，且返回空。
支持以下两种分页方式：
- Token 分页：通过NextToken设置查询凭证（Token），其取值是上一次调用 DescribeDisks 返回的NextToken参数值，再通过MaxResults设置单页查询的最大条目数。
- 固定分页：通过PageSize设置单页返回的条目数，再通过PageNumber设置页码。
以上两种方式只能任选其中之一。当返回的条目数较多时，推荐使用方式一。如果设置了NextToken，则请求参数PageSize和PageNumber将失效，且返回数据中的TotalCount无效。
开启多重挂载特性的云盘可以挂载到多个实例上，您可以根据返回结果的Attachment列表查看云盘涉及的所有挂载信息。

通过阿里云 CLI 调用 API 时，不同数据类型的请求参数取值必须遵循格式要求。更多信息，请参见 CLI 参数格式说明。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
ecs:DescribeDisks	list	Disk `acs:ecs:{#regionId}:{#accountId}:disk/{#diskId}` Disk `acs:ecs:{#regionId}:{#accountId}:disk/*`	无	无

请求参数

名称	类型	必填	描述	示例值
RegionId	string	是	块存储所属的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。	cn-hangzhou
ZoneId	string	否	可用区 ID。	cn-hangzhou-g
DiskIds	string	否	云盘、本地盘或弹性临时盘 ID。一个带有格式的 JSON 数组，最多支持 100 个 ID，用半角逗号（,）隔开。	["d-bp67acfmxazb4p**", "d-bp67acfmxazb4g", … "d-bp67acfmxazb4d**"]
InstanceId	string	否	云盘、本地盘或弹性临时盘挂载的实例 ID。	i-bp67acfmxazb4q****
DiskType	string	否	要查询的云盘、本地盘或弹性临时盘类型。取值范围： all：同时查询系统盘与数据盘。 system：只查询系统盘。 data：只查询数据盘。默认值：all。说明弹性临时盘不支持作为系统盘。	all
Category	string	否	磁盘种类。取值范围： all：所有云盘以及本地盘。 cloud：普通云盘。 cloud_efficiency：高效云盘。 cloud_ssd：SSD 盘。 cloud_essd：ESSD 云盘。 cloud_auto：ESSD AutoPL 云盘。 local_ssd_pro：I/O 密集型本地盘。 local_hdd_pro：吞吐密集型本地盘。 cloud_essd_entry：ESSD Entry 云盘。 elastic_ephemeral_disk_standard：弹性临时盘-标准版。 elastic_ephemeral_disk_premium：弹性临时盘-高级版。 ephemeral：（已停售）本地盘。 ephemeral_ssd：（已停售）本地 SSD 盘。默认值：all。	all
Status	string	否	磁盘状态。更多信息，请参见云盘状态。取值范围： In_use：使用中。 Available：待挂载。 Attaching：挂载中。 Detaching：卸载中。 Creating：创建中。 ReIniting：初始化中。 All：所有状态。默认值：All。	All
SnapshotId	string	否	创建云盘时使用的快照 ID。	s-bp67acfmxazb4p****
Portable	boolean	否	磁盘是否支持卸载。取值范围： true：支持。可以独立存在，且可以在可用区内自由挂载和卸载。 false：不支持。不可以独立存在，且不可以在可用区内自由挂载和卸载。以下类型块存储的`Portable`属性都为`false`，生命周期与实例等同：本地盘。本地 SSD 盘。包年包月数据盘。	false
DeleteWithInstance	boolean	否	磁盘是否设置了随实例释放。取值范围： true：磁盘随实例一起释放。 false：磁盘保留不释放，转为按量付费数据盘而保留下来。默认值：false。	false
DeleteAutoSnapshot	boolean	否	释放云盘时，是否会同时释放自动快照。 true：是。 false：否。默认值：false。	false
PageNumber	integer	否	磁盘状态列表的页码。起始值：1。默认值：1。	1
PageSize	integer	否	分页查询时设置的每页行数。最大值：100。默认值：10。	10
NextToken	string	否	查询凭证（Token），取值为上一次调用 API 返回的`NextToken`参数值。有关本接口查看返回数据的设置方式，请参见上文接口说明部分。	AAAAAdDWBF2****
MaxResults	integer	否	返回的最大数。取值范围：10~500。默认值：当不设置值或者设置的值小于 10，默认值为 10。当设置的值大于 500 时，默认值为 500。	50
DiskName	string	否	磁盘的名称。长度为 2~128 个字符，支持 Unicode 中 letter 分类下的字符（其中包括英文、中文和数字等）。可以包含半角冒号（:）、下划线（_）、半角句号（.）或者短划线（-）。	testDiskName
AutoSnapshotPolicyId	string	否	根据自动快照策略 ID 查询云盘。	sp-m5e2w2jutw8bv31****
EnableAutoSnapshot	boolean	否	云盘是否启用自动快照策略功能。 true：启用。 false：未启用。说明创建后的云盘默认启用自动快照策略功能，您只需要为云盘绑定自动快照策略即可正常使用。	true
EnableAutomatedSnapshotPolicy	boolean	否	云盘是否设置了自动快照策略。 true：已设置。 false：未设置。默认值：false。	false
DiskChargeType	string	否	磁盘的计费方式。取值范围： PrePaid：包年包月。 PostPaid：按量付费。	PostPaid
LockReason	string	否	磁盘被锁定的原因。取值范围： financial：因欠费被锁定。 security：因安全原因被锁定。 recycling：抢占式实例的待释放锁定状态。 dedicatedhostfinancial：因为专有宿主机欠费导致 ECS 实例被锁定。	recycling
Filter.1.Key	string	否	查询资源时的筛选键，取值必须为`CreationStartTime`。同时设置`Filter.1.Key`和`Filter.1.Value`可以查询在指定时间点后创建的资源信息。	CreationStartTime
Filter.2.Key	string	否	查询资源时的筛选键，取值必须为`CreationEndTime`。同时设置`Filter.2.Key`和`Filter.2.Value`可以查询在指定时间点前创建的资源信息。	CreationEndTime
Filter.1.Value	string	否	查询资源时的筛选值。指定该参数时必须同时指定`Filter.1.Key`参数，格式为：`yyyy-MM-ddTHH:mmZ`，采用 UTC +0 时区。	2017-12-05T22:40Z
Filter.2.Value	string	否	查询资源时的筛选值。指定该参数时必须同时指定`Filter.2.Key`参数，格式为：`yyyy-MM-ddTHH:mmZ`，采用 UTC +0 时区。	2017-12-06T22:40Z
ResourceGroupId	string	否	磁盘所在的企业资源组 ID。使用该参数过滤资源时，资源数量不能超过 1000 个。说明不支持默认资源组过滤。	rg-bp67acfmxazb4p****
EnableShared	boolean	否	是否是共享块存储。	false
Encrypted	boolean	否	是否只筛选出加密云盘。 true：是。 false：否默认值：false。	false
DryRun	boolean	否	是否只预检此次请求。取值范围： true：发送检查请求，不会查询资源状况。检查项包括 AccessKey 是否有效、RAM 用户的授权情况和是否填写了必需参数。如果检查不通过，则返回对应错误。如果检查通过，会返回错误码`DryRunOperation`。 false：发送正常请求，通过检查后返回 2XX HTTP 状态码并直接查询资源状况。默认值：false。	false
KMSKeyId	string	否	云盘使用的 KMS 密钥 ID。	0e478b7a-4262-4802-b8cb-00d3fb40****
MultiAttach	string	否	是否开启了多重挂载特性。取值范围： Disabled：未开启。 Enabled：已开启。 LegacyShared：用于查询共享块存储。多重挂载功能正在邀测中，如需使用，请提交工单。	Disabled
Tag	array<object>	否	磁盘标签列表。
	object	否	磁盘标签列表。
key	string	否	磁盘的标签键。说明为提高代码兼容性，请尽量使用 Tag.N.Key 参数。	null
Key	string	否	磁盘的标签键。N 的取值范围：1~20。使用一个标签过滤资源，查询到该标签下的资源数量不能超过 1000 个；使用多个标签过滤资源，查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个，请使用 ListTagResources 接口进行查询。	TestKey
Value	string	否	磁盘的标签值。N 的取值范围：1~20。	TestValue
value	string	否	磁盘的标签值。说明为提高代码兼容性，请尽量使用 Tag.N.Value 参数。	null
AdditionalAttributes	array	否	其他属性值列表。目前仅支持传入值为`Placement`，表示查询当前磁盘的数据存放地。说明目前仅同城冗余类型的磁盘有数据存放地。
	string	否	其他属性值。目前仅支持传入值为 Placement，表示查询当前磁盘的数据存放地。	Placement

返回参数

名称	类型	描述	示例值
	object
NextToken	string	本次调用返回的查询凭证值。	AAAAAdDWBF2****
PageSize	integer	输入时设置的每页行数。	1
PageNumber	integer	磁盘列表的页码。	1
RequestId	string	请求 ID。	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCount	integer	查询结果总条数。	15
Disks	array<object>	磁盘信息组成的集合。
Disk	object	磁盘信息组成的集合。
SerialNumber	string	磁盘的序列号。	bp18um4r4f2fve2****
CreationTime	string	创建时间。	2021-06-07T06:08:54Z
Status	string	磁盘状态。可能值： In_use：使用中。 Available：待挂载。 Attaching：挂载中。 Detaching：卸载中。 Creating：创建中。 ReIniting：初始化中。	In_use
Type	string	磁盘类型。可能值： system：系统盘。 data：数据盘。	system
PerformanceLevel	string	ESSD 云盘的性能等级。可能值： PL0：单盘最高随机读写 IOPS 1 万。 PL1：单盘最高随机读写 IOPS 5 万。 PL2：单盘最高随机读写 IOPS 10 万。 PL3：单盘最高随机读写 IOPS 100 万。	PL0
BdfId	string	该参数正在邀测中，暂未开放使用。	null
EnableAutoSnapshot	boolean	云盘是否启用自动快照策略功能。	false
StorageSetId	string	存储集 ID。	ss-i-bp1j4i2jdf3owlhe****
StorageSetPartitionNumber	integer	存储集中的最大分区数量。	11
DiskId	string	磁盘 ID。	d-bp18um4r4f2fve24****
DeleteAutoSnapshot	boolean	是否同时删除自动快照。可能值： true：删除云盘上的快照。 false：保留云盘上的快照。通过 CreateSnapshot 或者在控制台创建的快照，不受这个参数的影响，会始终保留。	false
StorageClusterId	string	云盘所属的专属块存储集群 ID。如果您的云盘在公共云块存储集群中，则该返回值为空。	dbsc-j5e1sf2vaf5he8m2****
Encrypted	boolean	是否为加密云盘。	false
IOPSRead	integer	每秒读操作的次数上限，单位：次/s。	2000
MountInstanceNum	integer	共享存储挂载的实例数量。	1
Description	string	磁盘描述。	testDescription
Device	string	磁盘挂载的实例的设备名，例如/dev/xvdb。您需要注意：该参数仅在`Status`参数值为`In_use`或`Detaching`时才有值，其他状态时为空。对于开启多重挂载特性的云盘，该值始终为空。您可以通过返回的`Attachment`对象组成的列表，查看云盘所涉及的所有挂载信息。说明该参数即将停止使用，为提高代码兼容性，建议您尽量不要使用该参数。	/dev/xvdb
DiskName	string	磁盘名称。	testDiskName
Portable	boolean	磁盘是否可卸载。	false
ImageId	string	创建 ECS 实例时使用的镜像 ID，只有通过镜像创建的云盘才有值，否则为空。这个值在云盘的生命周期内始终不变。	m-bp13aqm171qynt3u***
KMSKeyId	string	云盘使用的 KMS 密钥 ID。	0e478b7a-4262-4802-b8cb-00d3fb408***
DeleteWithInstance	boolean	是否随实例释放。可能值： true：释放实例时，这块磁盘随实例一起释放。 false：释放实例时，这块磁盘保留不释放。	true
DetachedTime	string	该磁盘最后一次卸载时间。	2021-06-07T21:01:22Z
SourceSnapshotId	string	创建云盘使用的快照 ID。如果创建云盘时，没有指定快照，则该参数值为空。该参数值在云盘的生命周期内始终不变。	s-bp67acfmxazb4p****
AutoSnapshotPolicyId	string	云盘采用的自动快照策略 ID。	sp-bp67acfmxazb4p****
EnableAutomatedSnapshotPolicy	boolean	云盘是否设置了自动快照策略。	false
IOPSWrite	integer	每秒写操作的次数上限，单位：次/s。	2000
InstanceId	string	磁盘挂载的实例 ID。您需要注意：该参数值仅在`Status`参数值为`In_use`或`Detaching`时才有值，其他状态时为空。对于开启多重挂载特性的云盘，该值始终为空。您可以通过返回的`Attachment`对象组成的列表，查看云盘所涉及的所有挂载信息。	i-bp67acfmxazb4q****
IOPS	integer	每秒读写（I/O）操作的次数上限，单位：次/s。	4000
RegionId	string	磁盘所属的地域 ID。	cn-hangzhou
ExpiredTime	string	包年包月磁盘的过期时间。	2021-07-07T16:00Z
Size	integer	磁盘大小，单位 GiB。	60
ResourceGroupId	string	磁盘所在的企业资源组 ID。	rg-bp67acfmxazb4p****
DiskChargeType	string	磁盘的计费方式。可能值： PrePaid：包年包月。 PostPaid：按量付费。	PrePaid
ZoneId	string	磁盘所属的可用区 ID。	cn-hangzhou-i
AttachedTime	string	该磁盘最后一次挂载的时间。按照 ISO8601 标准表示，使用 UTC+0 时间。格式为：yyyy-MM-ddThh:mmZ。	2021-06-07T06:08:56Z
Category	string	磁盘种类。可能值： cloud：普通云盘。 cloud_efficiency：高效云盘。 cloud_ssd：SSD 盘。 cloud_essd：ESSD 云盘。 cloud_auto：ESSD AutoPL 云盘。 local_ssd_pro：I/O 密集型本地盘。 local_hdd_pro：吞吐密集型本地盘。 cloud_essd_entry：ESSD Entry 云盘。 elastic_ephemeral_disk_standard：弹性临时盘-标准版。 elastic_ephemeral_disk_premium：弹性临时盘-高级版。 ephemeral：（已停售）本地盘。 ephemeral_ssd：（已停售）本地 SSD 盘。	cloud_ssd
ProductCode	string	云市场的商品标识。	jxsc000204
MultiAttach	string	云盘是否开启了多重挂载特性。	Disabled
OperationLocks	array<object>	磁盘锁定原因类型。
OperationLock	object	磁盘锁定原因类型。
LockReason	string	磁盘被安全锁定的原因。	security
MountInstances	array<object>	共享存储挂载到实例上的信息集合。
MountInstance	object	共享存储挂载到实例上的信息集合。
AttachedTime	string	挂载时间。按照ISO 8601标准表示，使用 UTC +0 时间，格式为 yyyy-MM-ddTHH:mm:ssZ。	2017-12-05T2340:00Z
InstanceId	string	磁盘挂载的实例 ID。	i-bp1j4i2jdf3owlhe****
Device	string	磁盘的挂载点。	/dev/xvda
Tags	array<object>	磁盘的标签集合。
Tag	object	磁盘的标签集合。
TagValue	string	标签值。	TestValue
TagKey	string	标签键。	TestKey
Attachments	array<object>	磁盘所涉及的挂载信息。由`Attachment`对象组成的列表，查询共享块存储时不返回该列表。
Attachment	object	磁盘所涉及的挂载信息。由`Attachment`对象组成的列表，查询共享块存储时不返回该列表。
InstanceId	string	所挂载的实例 ID。	i-bp67acfmxazb4q****
Device	string	设备名称。	/dev/xvda
AttachedTime	string	挂载的时间，以 UTC +0 时间为准。	2021-06-07T06:08:56Z
ProvisionedIops	long	ESSD AutoPL 云盘预配置的读写 IOPS。可能值：0~min{50000, 1000容量-基准性能}。基准性能=min{1,800+50容量, 50,000}。当`DiskCategory`取值为`cloud_auto`时才支持设置该参数。更多信息，请参见ESSD AutoPL 云盘。	40000
BurstingEnabled	boolean	是否开启 Burst（性能突发）。可能值： true：是。 false：否。当`DiskCategory`取值为`cloud_auto`时才支持设置该参数。更多信息，请参见ESSD AutoPL 云盘。	false
Throughput	integer	单位时间内可以成功传输的数据数量，单位：MB/s。	100
ThroughputRead	integer	单位时间内系统可以成功读取的数据数量，单位：MB/s。	100
ThroughputWrite	integer	单位时间内系统可以成功写入的数据数量，单位：MB/s。	100
Placement	object	数据存放地集合。只有入参指定 `AdditionalAttributes.N = Placement` 时，才会返回该字段。说明当前仅有 ESSD 同城冗余类型（cloud_regional_disk_auto）磁盘具有有效值。
ZoneIds	string	实际数据存放的可用区列表。	cn-hangzhou-b cn-hangzhou-j

示例

正常返回示例

JSON格式

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

错误码

HTTP status code	错误码	错误信息	描述
400	InvalidDiskType.ValueNotSupported	The specified disk type is not supported.	指定的磁盘属性不支持。
400	InvalidCategory.ValueNotSupported	The specified disk category is not supported.	不支持指定的磁盘种类。
400	InvalidStatus.ValueNotSupported	The specified disk status is not supported.	指定的磁盘状态不支持此类操作。
400	InvalidTag.Mismatch	The specified Tag.n.Key and Tag.n.Value are not match.	指定的 Tag.N.Key 和 Tag.N.Value 不匹配。
400	InvalidTagCount	The specified tags are beyond the permitted range.	指定的标记超出取值范围。
400	InvalidRegion.NotFound	The specified parameter RegionId is not valid.	RegionId 参数不合法。
400	InvalidZoneId.NotFound	The zoneId provided does not exist in our records.	指定的可用区 ID 不存在。
400	MissingParamter.RegionId	The regionId should not be null.	参数 RegionId 不得为空。
400	InvalidParameter.DiskIds	The specified parameter diskIds is not valid.	指定的参数 diskIds 无效。
400	IncompleteParamter	Some fields can not be null in this request.	请求中缺失参数。
400	InvalidParamter	Some parameters are invalid in this request.	请求中包含非法参数。
400	InvalidSnapshot.NotFound	The specified parameter SnapshotId is not valid.	指定的 SnapshotId 不合法。
403	InvalidDiskIds.Malformed	The amount of specified disk Ids exceeds the limit.	指定的磁盘 ID 格式不正确。
403	UserNotInTheWhiteList	The user is not in volume white list.	用户不在共享块存储白名单中，请您提交工单申请白名单。
403	InvalidParameter.MultiAttachAndEnableSharedNotMatch	The parameter MultiAttach and EnableShared are not match.	设置的 MultiAttach 参数和 EnableShared 参数的值不兼容。
403	InvalidParameter.MultiAttach	The specified param MultiAttach is not valid.	MultiAttach 参数的取值有误。
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.	指定的磁盘计费方式不存在。
404	InvalidLockReason.NotFound	The specified LockReason is not found.	所指定的锁定原因不存在
500	InternalError	The request processing has failed due to some unknown error.	内部错误，请重试。

访问错误中心查看更多错误码。

变更历史

变更时间	变更内容概要	操作
2024-05-08	OpenAPI 去除了 deprecated 标记、OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更	查看变更详情
2023-11-24	OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更	查看变更详情