DescribeReservedInstances - 查询预留实例券详细信息列表 - 云服务器 ECS

本接口主要用于查询指定地域下您已经购买的预留实例券信息列表，支持您根据标签、预留实例券属性等参数获取预留实例券详细信息列表。

接口说明

适用场景

查询指定地域下所有的预留实例券。
根据预留实例券 ID 或名称查询其详细信息。
根据实例规格或者实例规格族过滤查询您已购买的预留实例券。
根据预留实例券范围或者状态过滤查询您已购买的预留实例券。

请求示例

示例：查询杭州地域下所有已购买的预留实例券

"Region":"cn-hangzhou" //设置地域为杭州

示例：查询杭州地域下 ID 为 ecsri-bp129enntoynwwj5****的预留实例券的详细信息

"Region":"cn-hangzhou", //设置地域为杭州
"ReservedInstanceId":"ecsri-bp129enntoynwwj5****" //设置预留实例券 ID

示例：查询杭州地域下可以抵扣实例规格为 ecs.c5.2xlarge 的预留实例券

"Region":"cn-hangzhou", //设置地域为杭州
"InstanceType":"ecs.c5.2xlarge" //设置实例规格

示例：查询杭州地域下在有效期中的地域级预留实例券

"Region":"cn-hangzhou", //设置地域为杭州
"Scope":"Region", //设置预留实例券范围
"Status":["Active"] //设置状态为在有效期中

调试

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

调试

授权信息

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

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

操作	访问级别	资源类型	条件关键字	关联操作
ecs:DescribeReservedInstances	get	ReservedInstance `acs:ecs:{#regionId}:{#accountId}:reservedinstance/` *ReservedInstance `acs:ecs:{#regionId}:{#accountId}:reservedinstance/{#reservedinstanceId}`	无	无

请求参数

名称	类型	必填	描述	示例值
RegionId	string	是	预留实例券所属的地域 ID。您可以调用 DescribeRegions 获取最新的阿里云地域列表。	cn-hangzhou
PageNumber	integer	否	预留实例券列表的页码，起始值：1。默认值：1。	1
PageSize	integer	否	分页查询时的每页行数，最大值：100。默认值：10。	50
Tag	array<object>	否	标签数组。数组长度：1~20。
	object	否	标签。
Key	string	否	预留实例券的标签键。不允许为空字符串，最多支持 128 个字符，不能以 aliyun 和 acs:开头，不能包含 http://或者 https://。说明使用一个标签过滤资源，查询到该标签下的资源数量不能超过 1000 个；使用多个标签过滤资源，查询到同时绑定了多个标签的资源数量不能超过 1000 个；如果资源数量超过 1000 个，请使用 ListTagResources 接口进行查询。	TestKey
Value	string	否	预留实例券的标签值。不允许为空字符串,最多支持 128 个字符，不能以`acs:`开头，不能包含`http://`或者`https://`。	TestValue
ZoneId	string	否	实例所属的可用区编号，当 Scope 为 Zone 时生效并且必填。您可以通过 DescribeZones 获取可用区列表。	cn-hangzhou-z
ReservedInstanceName	string	否	预留实例券名称。说明完全匹配，暂不支持模糊查询过滤。	testReservedInstanceName
LockReason	string	否	锁定类型。取值范围： financial：账号欠费或服务过期。 security：安全原因。	security
InstanceType	string	否	预留实例券对应的实例规格。取值请参见实例规格族。说明购买预留实例券时选择的实例规格，实际抵扣的时候，地域级预留实例券支持同规格组内的不同大小规格换算抵扣。	ecs.g5.large
InstanceTypeFamily	string	否	预留实例券对应的实例规格族。取值请参见实例规格族。	ecs.g5
Scope	string	否	预留实例券的范围。取值范围： Region：地域级别。 Zone：可用区级别。	Region
OfferingType	string	否	预留实例券的付款类型。取值范围： No Upfront：零预付。 Partial Upfront：部分预付。 All Upfront：全预付。	All Upfront
AllocationType	string	否	分配类型。取值范围： Normal：查询当前账号下的预留实例券。 Shared：查询当前账号下已经建立主子账号共享的预留实例券。默认值：Normal。	Normal
ReservedInstanceId	array	否	预留实例券 ID 数组。数组长度：1~100。
	string	否	预留实例券 ID。	ri-bpzhex2ulpzf53****
Status	array	否	预留实例券的状态数组。
	string	否	预留实例券的状态。状态值取值范围： Creating：正在创建。 Active：在有效期中。 Retired：失效。 Updating：正在更改预留实例券的属性。 Expired：已过期。预留实例券过期后立即失效，该取值目前已废弃，后续将移除。	Active

返回参数

名称	类型	描述	示例值
	object
PageSize	integer	输入时设置的每页行数。	1
RequestId	string	请求 ID。	E572643C-6A29-49D6-9D4E-6CFA4E063A3E
PageNumber	integer	预留实例券列表的页码。	1
TotalCount	integer	预留实例券的总数。	1
ReservedInstances	array<object>	由 ReservedInstance 组成的数组格式，返回预留实例券的详细信息。
ReservedInstance	object	由 ReservedInstance 组成的数组格式，返回预留实例券的详细信息。
Status	string	状态。	Active
CreationTime	string	创建时间。	2018-12-10T12:07Z
ReservedInstanceName	string	名称。	riZbpzhex2ulpzf53****
ReservedInstanceId	string	预留实例券 ID。	ri-bpzhex2ulpzf53****
InstanceType	string	匹配的按量付费实例的规格。	ecs.g5.large
InstanceAmount	integer	可以匹配同规格按量付费实例的数量。	10
RegionId	string	地域 ID。	cn-hangzhou
OfferingType	string	付款类型。	All Upfront
StartTime	string	生效时间。	2018-12-10T12:00Z
Description	string	描述。	testDescription
AllocationStatus	string	当 AllocationType 值为 Shared 时，该参数表示预留实例券的分配状态。可能值： allocated：已分配给其他用户的预留实例券。 beAllocated：被其他用户分配的预留实例券。	allocated
ExpiredTime	string	到期时间。	2019-12-10T12:07Z
ResourceGroupId	string	资源组。	EcsDocTest
ZoneId	string	可用区 ID。	cn-hangzhou-z
Platform	string	实例使用的镜像的操作系统类型。可能值： Windows：Windows Server 类型的操作系统。 Linux：Linux 及类 Unix 类型的操作系统。	Linux
Scope	string	范围。	region
OperationLocks	array<object>	是否被锁定。
OperationLock	object	是否被锁定。
LockReason	string	锁定原因。	security
Tags	array<object>	预留实例券的标签对信息。
Tag	object	预留实例券的标签对信息。
TagValue	string	预留实例券的标签值。	TestValue
TagKey	string	预留实例券的标签键。	TestKey

示例

正常返回示例

JSON格式

{
  "PageSize": 1,
  "RequestId": "E572643C-6A29-49D6-9D4E-6CFA4E063A3E",
  "PageNumber": 1,
  "TotalCount": 1,
  "ReservedInstances": {
    "ReservedInstance": [
      {
        "Status": "Active",
        "CreationTime": "2018-12-10T12:07Z",
        "ReservedInstanceName": "riZbpzhex2ulpzf53****",
        "ReservedInstanceId": "ri-bpzhex2ulpzf53****",
        "InstanceType": "ecs.g5.large",
        "InstanceAmount": 10,
        "RegionId": "cn-hangzhou",
        "OfferingType": "All Upfront",
        "StartTime": "2018-12-10T12:00Z",
        "Description": "testDescription",
        "AllocationStatus": "allocated",
        "ExpiredTime": "2019-12-10T12:07Z",
        "ResourceGroupId": "EcsDocTest",
        "ZoneId": "cn-hangzhou-z",
        "Platform": "Linux",
        "Scope": "region",
        "OperationLocks": {
          "OperationLock": [
            {
              "LockReason": "security"
            }
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagValue": "TestValue",
              "TagKey": "TestKey"
            }
          ]
        }
      }
    ]
  }
}

错误码

HTTP status code	错误码	错误信息	描述
400	MissingParamter.RegionId	The regionId should not be null.	参数 RegionId 不得为空。
400	InvalidRegion.NotFound	The specified parameter RegionId is not valid.	RegionId 参数不合法。
400	InvalidZone.NotFound	The specified parameter ZoneId is not valid.	指定的ZoneId不合法。
400	InvalidReservedInstanceOfferingType.ValueNotSupported	the OfferingType is not supported	-
400	InvalidReservedInstanceOfferingClass.ValueNotSupported	the OfferingClass is not supported	-
400	OperationDenied	The specified InstanceType or Zone is not authorized for current user.	-
400	InvalidEndTime.ValueNotSupported	The specified endTime is out of the permitted range.	指定的 EndTime 超过限制。
400	InvalidReservedInstanceLockReason.ValueNotSupported	The specified LockReason is not supported.	-
400	InvalidReservedInstanceStatus.ValueNotSupported	The specified Status is not supported.	-
400	InvalidAllocationType.ValueNotSupported	The specified AllocationType is not supported.	指定的分配类型无效。
403	RAM.ApiNotSupported	This call is not supported from ram accessing.	RAM 用户没有权限执行该操作。
404	InvalidRegionId.NotFound	The specified RegionId does not exist in our records.	指定的RegionId不存在，请您检查此产品在该地域是否可用。

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

变更历史

变更时间	变更内容概要	操作
2024-12-26	OpenAPI 描述信息更新、OpenAPI 错误码发生变更	查看变更详情