DescribeDisks - 查询块存储

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

接口说明

  • 请求参数RegionIdZoneIdDiskIdsInstanceId等都是过滤器的概念,参数间是逻辑与(AND)关系。

  • 请求参数DiskIds是一个 JSON 格式的数组(Array),如果参数为空,则过滤器不起作用,但是DiskIds如果是一个空数组,则视为该过滤器有效,且返回空。

  • 支持以下两种方式查看返回数据:

    • 方式一:通过NextToken设置查询凭证(Token),其取值是上一次调用 DescribeDisks 返回的NextToken参数值,再通过MaxResults设置单页查询的最大条目数。
    • 方式二:通过PageSize设置单页返回的条目数,再通过PageNumber设置页码。

    以上两种方式只能任选其中之一。当返回的条目数较多时,推荐使用方式一。如果设置了NextToken,则请求参数PageSizePageNumber将失效,且返回数据中的TotalCount无效。

  • 开启多重挂载特性的云盘可以挂载到多个实例上,您可以根据返回结果的Attachment列表查看云盘涉及的所有挂载信息。

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

调试

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

授权信息

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

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
ecs:DescribeDiskslist
  • Disk
    acs:ecs:{#regionId}:{#accountId}:disk/{#diskId}
  • Disk
    acs:ecs:{#regionId}:{#accountId}:disk/*

请求参数

名称类型必填描述示例值
RegionIdstring

块存储所属的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。

cn-hangzhou
ZoneIdstring

可用区 ID。

cn-hangzhou-g
DiskIdsstring

云盘、本地盘或弹性临时盘 ID。一个带有格式的 JSON 数组,最多支持 100 个 ID,用半角逗号(,)隔开。

["d-bp67acfmxazb4p****", "d-bp67acfmxazb4g****", … "d-bp67acfmxazb4d****"]
InstanceIdstring

云盘、本地盘或弹性临时盘挂载的实例 ID。

i-bp67acfmxazb4q****
DiskTypestring

要查询的云盘、本地盘或弹性临时盘类型。取值范围:

  • all:同时查询系统盘与数据盘。
  • system:只查询系统盘。
  • data:只查询数据盘。

默认值:all。

说明 弹性临时盘不支持作为系统盘。
all
Categorystring

磁盘种类。取值范围:

  • 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
Statusstring

磁盘状态。更多信息,请参见云盘状态。取值范围:

  • In_use:使用中。
  • Available:待挂载。
  • Attaching:挂载中 。
  • Detaching:卸载中。
  • Creating:创建中。
  • ReIniting:初始化中。
  • All:所有状态。

默认值:All。

All
SnapshotIdstring

创建云盘时使用的快照 ID。

s-bp67acfmxazb4p****
Portableboolean

磁盘是否支持卸载。取值范围:

  • true:支持。可以独立存在,且可以在可用区内自由挂载和卸载。

  • false:不支持。不可以独立存在,且不可以在可用区内自由挂载和卸载。

以下类型块存储的Portable属性都为false,生命周期与实例等同:

  • 本地盘。
  • 本地 SSD 盘。
  • 包年包月数据盘。
false
DeleteWithInstanceboolean

磁盘是否设置了随实例释放。取值范围:

  • true:磁盘随实例一起释放。
  • false:磁盘保留不释放,转为按量付费数据盘而保留下来。

默认值:false。

false
DeleteAutoSnapshotboolean

释放云盘时,是否会同时释放自动快照。

  • true:是。

  • false:否。

默认值:false。

false
PageNumberinteger

磁盘状态列表的页码。

起始值:1。

默认值:1。

1
PageSizeinteger

分页查询时设置的每页行数。

最大值:100。

默认值:10。

10
NextTokenstring

查询凭证(Token),取值为上一次 API 调用返回的NextToken参数值。

有关本接口查看返回数据的设置方式,请参见上文接口说明。

AAAAAdDWBF2****
MaxResultsinteger

返回的最大数。取值范围:10~500。

默认值:

  • 当不设置值或者设置的值小于 10,默认值为 10。
  • 当设置的值大于 500 时,默认值为 500。
50
DiskNamestring

磁盘的名称。长度为 2~128 个字符,支持 Unicode 中 letter 分类下的字符(其中包括英文、中文和数字等)。可以包含半角冒号(:)、下划线(_)、半角句号(.)或者短划线(-)。

testDiskName
AutoSnapshotPolicyIdstring

根据自动快照策略 ID 查询云盘。

sp-m5e2w2jutw8bv31****
EnableAutoSnapshotboolean

云盘是否启用自动快照策略功能。

  • true:启用。
  • false:未启用。
说明 创建后的云盘默认启用自动快照策略功能,您只需要为云盘绑定自动快照策略即可正常使用。
true
EnableAutomatedSnapshotPolicyboolean

云盘是否设置了自动快照策略。

  • true:已设置。
  • false:未设置。

默认值:false。

false
DiskChargeTypestring

磁盘的计费方式。取值范围:

  • PrePaid:包年包月。
  • PostPaid:按量付费。
PostPaid
LockReasonstring

磁盘被锁定的原因。取值范围:

  • financial:因欠费被锁定。
  • security:因安全原因被锁定。
  • recycling:抢占式实例的待释放锁定状态。
  • dedicatedhostfinancial:因为专有宿主机欠费导致 ECS 实例被锁定。
recycling
Filter.1.Keystring

查询资源时的筛选键,取值必须为CreationStartTime。同时设置Filter.1.KeyFilter.1.Value可以查询在指定时间点后创建的资源信息。

CreationStartTime
Filter.2.Keystring

查询资源时的筛选键,取值必须为CreationEndTime。同时设置Filter.2.KeyFilter.2.Value可以查询在指定时间点前创建的资源信息。

CreationEndTime
Filter.1.Valuestring

查询资源时的筛选值。指定该参数时必须同时指定Filter.1.Key参数,格式为:yyyy-MM-ddTHH:mmZ,采用 UTC +0 时区。

2017-12-05T22:40Z
Filter.2.Valuestring

查询资源时的筛选值。指定该参数时必须同时指定Filter.2.Key参数,格式为:yyyy-MM-ddTHH:mmZ,采用 UTC +0 时区。

2017-12-06T22:40Z
ResourceGroupIdstring

磁盘所在的企业资源组 ID。使用该参数过滤资源时,资源数量不能超过 1000 个。

说明 不支持默认资源组过滤。
rg-bp67acfmxazb4p****
EnableSharedboolean

是否是共享块存储。

false
Encryptedboolean

是否只筛选出加密云盘。

  • true:是。

  • false:否

默认值:false。

false
DryRunboolean

是否只预检此次请求。取值范围:

  • true:发送检查请求,不会查询资源状况。检查项包括 AccessKey 是否有效、RAM 用户的授权情况和是否填写了必需参数。如果检查不通过,则返回对应错误。如果检查通过,会返回错误码DryRunOperation
  • false:发送正常请求,通过检查后返回 2XX HTTP 状态码并直接查询资源状况。

默认值:false。

false
KMSKeyIdstring

云盘使用的 KMS 密钥 ID。

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

是否开启了多重挂载特性。取值范围:

  • Disabled:未开启。
  • Enabled:已开启。
  • LegacyShared:用于查询共享块存储。

多重挂载功能正在邀测中,如需使用,请提交工单

Disabled
Tagarray<object>

磁盘标签列表。

object

磁盘标签列表。

keystring

磁盘的标签键。

说明 为提高代码兼容性,请尽量使用 Tag.N.Key 参数。
null
Keystring

磁盘的标签键。N 的取值范围:1~20。

使用一个标签过滤资源,查询到该标签下的资源数量不能超过 1000 个;使用多个标签过滤资源,查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个,请使用 ListTagResources 接口进行查询。

TestKey
Valuestring

磁盘的标签值。N 的取值范围:1~20。

TestValue
valuestring

磁盘的标签值。

说明 为提高代码兼容性,请尽量使用 Tag.N.Value 参数。
null
AdditionalAttributesarray

其他属性值。目前仅支持传入值为 IOPS,表示查询当前磁盘的 IOPS 上限。

string

其他属性值。目前仅支持传入值为 IOPS,表示查询当前磁盘的 IOPS 上限。

IOPS

返回参数

名称类型描述示例值
object
NextTokenstring

本次调用返回的查询凭证值。

AAAAAdDWBF2****
PageSizeinteger

输入时设置的每页行数。

1
PageNumberinteger

磁盘列表的页码。

1
RequestIdstring

请求 ID。

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

查询结果总条数。

15
Disksarray<object>

磁盘信息组成的集合。

Diskobject

磁盘信息组成的集合。

SerialNumberstring

磁盘的序列号。

bp18um4r4f2fve2****
CreationTimestring

创建时间。

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

磁盘状态。可能值:

  • In_use:使用中。
  • Available:待挂载。
  • Attaching:挂载中 。
  • Detaching:卸载中。
  • Creating:创建中。
  • ReIniting:初始化中。
In_use
Typestring

磁盘类型。可能值:

  • system:系统盘。
  • data:数据盘。
system
PerformanceLevelstring

ESSD 云盘的性能等级。可能值:

  • PL0:单盘最高随机读写 IOPS 1 万。
  • PL1:单盘最高随机读写 IOPS 5 万。
  • PL2:单盘最高随机读写 IOPS 10 万。
  • PL3:单盘最高随机读写 IOPS 100 万。
PL0
BdfIdstring

该参数正在邀测中,暂未开放使用。

null
EnableAutoSnapshotboolean

云盘是否启用自动快照策略功能。

false
StorageSetIdstring

存储集 ID。

ss-i-bp1j4i2jdf3owlhe****
StorageSetPartitionNumberinteger

存储集中的最大分区数量。

11
DiskIdstring

磁盘 ID。

d-bp18um4r4f2fve24****
DeleteAutoSnapshotboolean

是否同时删除自动快照。可能值:

  • true:删除云盘上的快照。
  • false:保留云盘上的快照。

通过 CreateSnapshot 或者在控制台创建的快照,不受这个参数的影响,会始终保留。

false
StorageClusterIdstring

云盘所属的专属块存储集群 ID。如果您的云盘在公共云块存储集群中,则该返回值为空。

dbsc-j5e1sf2vaf5he8m2****
Encryptedboolean

是否为加密云盘。

false
IOPSReadinteger

每秒读操作的次数上限,单位:次/s。

2000
MountInstanceNuminteger

共享存储挂载的实例数量。

1
Descriptionstring

磁盘描述。

testDescription
Devicestring

磁盘挂载的实例的设备名,例如/dev/xvdb。您需要注意:

  • 该参数仅在Status参数值为In_useDetaching时才有值,其他状态时为空。

  • 对于开启多重挂载特性的云盘,该值始终为空。您可以通过返回的Attachment对象组成的列表,查看云盘所涉及的所有挂载信息。

说明 该参数即将停止使用,为提高代码兼容性,建议您尽量不要使用该参数。
/dev/xvdb
DiskNamestring

磁盘名称。

testDiskName
Portableboolean

磁盘是否可卸载。

false
ImageIdstring

创建 ECS 实例时使用的镜像 ID,只有通过镜像创建的云盘才有值,否则为空。这个值在云盘的生命周期内始终不变。

m-bp13aqm171qynt3u***
KMSKeyIdstring

云盘使用的 KMS 密钥 ID。

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

是否随实例释放。可能值:

  • true:释放实例时,这块磁盘随实例一起释放。
  • false:释放实例时,这块磁盘保留不释放。
true
DetachedTimestring

该磁盘最后一次卸载时间。

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

创建云盘使用的快照 ID。

如果创建云盘时,没有指定快照,则该参数值为空。该参数值在云盘的生命周期内始终不变。

s-bp67acfmxazb4p****
AutoSnapshotPolicyIdstring

云盘采用的自动快照策略 ID。

sp-bp67acfmxazb4p****
EnableAutomatedSnapshotPolicyboolean

云盘是否设置了自动快照策略。

false
IOPSWriteinteger

每秒写操作的次数上限,单位:次/s。

2000
InstanceIdstring

磁盘挂载的实例 ID。您需要注意:

  • 该参数值仅在Status参数值为In_useDetaching时才有值,其他状态时为空。

  • 对于开启多重挂载特性的云盘,该值始终为空。您可以通过返回的Attachment对象组成的列表,查看云盘所涉及的所有挂载信息。

i-bp67acfmxazb4q****
IOPSinteger

每秒读写(I/O)操作的次数上限,单位:次/s。

4000
RegionIdstring

磁盘所属的地域 ID。

cn-hangzhou
ExpiredTimestring

包年包月磁盘的过期时间。

2021-07-07T16:00Z
Sizeinteger

磁盘大小,单位 GiB。

60
ResourceGroupIdstring

磁盘所在的企业资源组 ID。

rg-bp67acfmxazb4p****
DiskChargeTypestring

磁盘的计费方式。可能值:

  • PrePaid:包年包月。
  • PostPaid:按量付费。
PrePaid
ZoneIdstring

磁盘所属的可用区 ID。

cn-hangzhou-i
AttachedTimestring

该磁盘最后一次挂载的时间。按照 ISO8601 标准表示,使用 UTC+0 时间。格式为:yyyy-MM-ddThh:mmZ。

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

磁盘种类。可能值:

  • 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
ProductCodestring

云市场的商品标识。

jxsc000204
MultiAttachstring

云盘是否开启了多重挂载特性。

Disabled
OperationLocksarray<object>

磁盘锁定原因类型。

OperationLockobject

磁盘锁定原因类型。

LockReasonstring

磁盘被安全锁定的原因。

security
MountInstancesarray<object>

共享存储挂载到实例上的信息集合。

MountInstanceobject

共享存储挂载到实例上的信息集合。

AttachedTimestring

挂载时间。按照ISO 8601标准表示,使用 UTC +0 时间,格式为 yyyy-MM-ddTHH:mm:ssZ。

2017-12-05T2340:00Z
InstanceIdstring

磁盘挂载的实例 ID。

i-bp1j4i2jdf3owlhe****
Devicestring

磁盘的挂载点。

/dev/xvda
Tagsarray<object>

磁盘的标签集合。

Tagobject

磁盘的标签集合。

TagValuestring

标签值。

TestValue
TagKeystring

标签键。

TestKey
Attachmentsarray<object>

磁盘所涉及的挂载信息。由Attachment对象组成的列表,查询共享块存储时不返回该列表。

Attachmentobject

磁盘所涉及的挂载信息。由Attachment对象组成的列表,查询共享块存储时不返回该列表。

InstanceIdstring

所挂载的实例 ID。

i-bp67acfmxazb4q****
Devicestring

设备名称。

/dev/xvda
AttachedTimestring

挂载的时间,以 UTC +0 时间为准。

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

ESSD AutoPL 云盘预配置的读写 IOPS。可能值:0~min{50000, 1000容量-基准性能}。 基准性能=min{1,800+50容量, 50,000}。

DiskCategory取值为cloud_auto时才支持设置该参数。更多信息,请参见ESSD AutoPL 云盘

40000
BurstingEnabledboolean

是否开启 Burst(性能突发)。可能值:

  • true:是。
  • false:否。

DiskCategory取值为cloud_auto时才支持设置该参数。更多信息,请参见ESSD AutoPL 云盘

false
Throughputinteger

单位时间内可以成功传输的数据数量,单位:MB/s。

100
ThroughputReadinteger

单位时间内系统可以成功读取的数据数量,单位:MB/s。

100
ThroughputWriteinteger

单位时间内系统可以成功写入的数据数量,单位:MB/s。

100
Placementobject

数据存放地集合。

ZoneIdsstring

实际数据存放的可用区列表。

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

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

变更历史

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