文档中心

云服务器

实例

PurchaseReservedInstances - 购买预留实例券

调用 PurchaseReservedInstances 接口购买抵扣型资源（预留实例券或预留存储容量包）。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Action string 必选示例值：PurchaseReservedInstances

要执行的操作，取值：PurchaseReservedInstances。

Version string 必选示例值：2020-04-01

API的版本，取值：2020-04-01。

AutoRenew boolean 可选示例值：true

预留券到期后是否自动续费。

true：自动续费

false（默认）：不自动续费

AutoRenewPeriod integer 可选示例值：1

每次自动续费的时长。

当参数AutoRenew取值为True时，该参数有效。

PeriodUnit为Month时，该参数取值为1、2、3、6、12，默认值为1。

ClientToken string 可选示例值：333456899ff****

保证请求幂等性。由客户端自动生成一个参数值，确保不同请求间该参数值唯一，避免当调用API超时或服务器内部错误时，客户端多次重试导致重复性操作。

取值：仅支持ASCII字符，且不能超过64个字符。

Description string 可选示例值：testDescription

预留券的描述，默认值为空字符串。

必须以字母或中文开头。

只能包含中文、字母、数字、点“.”、空格、下划线“_”、中划线“-”、等号“=”、英文逗号“,”、中文逗号“，”和中文句号“。”

长度限制在255个字符以内。

EffectiveAt string 可选示例值：2025-03-29T17:00:00+08:00

预留存储容量包的生效时间，默认为空，即立即生效。

如果指定的生效时间非整点时，则在指定时间的整点生效，例如指定时间为2025-03-29T17:50:00+08:00，则实际生效时间是2025-03-29T17:00:00+08:00。

HpcClusterId string 可选示例值：hpcCluster-1

购买高性能计算GPU型实例的预留实例券时，需指定高性能计算集群ID。

说明

如需购买GPU型的预留实例券，请联系客户经理申请。

InstanceCount integer 可选示例值：1

预留实例券可以抵扣和预留的按量计费实例数量。取值范围：1～100；传入0时或者不传，会默认为1。

例如，实例规格为ecs.ecs.g3i.large，实例数量设置为2，该预留实例券就可以同时匹配2台规格为ecs.ecs.g3i.large的按量计费实例。

InstanceTypeId string 必选示例值：ecs.g3i.large

预留实例券可以抵扣和预留的实例规格。

Period integer 可选示例值：12

预留实例券的购买时长（月）。

取值：1、2、3、4、5、6、7、8、9、12、24、36

默认值：1

PeriodUnit string 可选示例值：Month

购买预留实例券的时长单位，取值：Month。

ProjectName string 可选示例值：project_a

资源所属项目，一个资源只能归属于一个项目。

只能包含字母、数字、下划线“_”、点“.”和中划线“-”。

长度限制在64个字符以内。

RegionId string 可选示例值：cn-beijing

预留实例券所属的地域ID。

您可以调用 DescribeRegions 接口查看地域ID。

说明

Scope取值为RegionalRI时，必须传入该参数。

ReservedCapacity integer 可选示例值：1

预留存储容量包每小时预留的容量大小，单位为GiB/小时，TiB/小时。

取值范围：65535 GiB～64 TiB

容量包总量为ReservedCapacity * 有效期小时数，每小时可抵扣上限为ReservedCapacity*2。

ReservedStorageCapacityName为空时，该参数非必填且不生效。

ReservedStorageCapacityName非空时，该参数必填。

ReservedInstanceName string 必选示例值：reserved-instance-test

预留实例券的名称。

不能以数字、中划线、下划线开头。

只能包含中文、字母、数字、下划线“_”和中划线“-”。

长度限制为1～128个字符。

暂不支持特殊字符。

ReservedStorageCapacityName string 可选示例值：RSC01

预留存储容量包的名称。

不能以数字、中划线、下划线开头。

只能包含中文、字母、数字、下划线和中划线。

长度限制为1～128个字符。

暂不支持特殊字符。

说明

不传则不购买预留存储容量包。

RscAutoRenew boolean 可选示例值：true

预留存储容量包到期后是否自动续费。取值：

true：自动续费。

false（默认）：不自动续费。

RscAutoRenewPeriod integer 可选示例值：1

预留存储容量包每次自动续费的时长。

当参数RscAutoRenew取值为True时，该参数有效。

PeriodUnit为Month时，该参数取值为1、2、3、6、12，默认值为1。

Scope string 可选示例值：ZonalRI

预留实例券的类型，取值：

ZonalRI（默认）：可用区级预留实例券。

RegionalRI：地域级预留实例券。地域级预留实例券正在邀测中，如需试用，请联系客户经理申请。

Tags.N.Key string[] 必选示例值：Tags.1.Key=k1&Tags.2.Key=k2

用户标签的标签键。

参数 - N：表示标签键的序号，取值范围：1～20。

多个标签键之间用&分隔。

命名规则如下：

不能以volc:或sys:的任意大小写组合开头。

只能包含语言字符、数字、空格和英文符号“_”、“.”、“:”、“/”、“=”、“+”、“-”、“@”。

长度限制在1～128个字符之间。

说明

同一资源的标签键不允许重复。

Tags.N.Value string[] 可选示例值：Tags.1.Value=v1&Tags.2.Value=v2

用户标签的标签值。

参数 - N：表示标签值的序号，取值范围：1～20。

多个标签值之间用&分隔。

命名规则如下：

只能包含语言字符、数字、空格和英文符号“_”、“.”、“:”、“/”、“=”、“+”、“-”、“@”。

允许为空，长度限制在0～256个字符之间。

说明

如果传入该参数，则必须先传入Tags.N.Key。

VolumeType string 可选示例值：ESSD_PL0

云盘类型，取值：

ESSD_PL0：极速型SSD PL0

ESSD_FlexPL: 极速型SSD FlexPL

说明

ReservedStorageCapacityName为空时，该参数非必填且不生效。

ReservedStorageCapacityName非空时，该参数必填。

ZoneId string 可选示例值：cn-beijing-a

预留实例券所在可用区ID。

您可以调用 DescribeZones 查询一个地域下的可用区信息。

说明

Scope取值为ZonalRI时，必须传入该参数。

返回参数

下方仅列出本接口特有的返回参数。更多信息请参见返回结构。

ReservedInstanceId string 示例值：ecsri-ycq8kgnlxrb5oxt0****

预留实例券ID。

ReservedStorageCapacityId string 示例值：ebsrsc-3tigy72q3u3vj0x2****

预留存储容量包ID。

请求示例

GET /?Action=PurchaseReservedInstances&Version=2020-04-01&RegionId=cn-beijing&ZoneId=cn-beijing-a&ReservedInstanceName=reserved-instance-test&InstanceTypeId=ecs.g3i.large HTTP/1.1​
Host: ecs.cn-beijing.volcengineapi.com​
Region: cn-beijing​
ServiceName: ecs​

返回示例

{​
    "ResponseMetadata": {​
        "RequestId": "2021062415303301022514515207C4****",​
        "Action": "PurchaseReservedInstances",​
        "Version": "2020-04-01",​
        "Service": "ecs",​
        "Region": "cn-beijing"​
    },​
    "Result": {​
        "ReservedInstanceId": "ecsri-ycq8kgnlxrb5oxt0****"​
    }​
}​

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
400	InvalidConfiguration.Unsupported	The specified configuration includes an unsupported operation.	此规格暂不支持售卖。
400	InvalidCount.Malformed	The specified count is malformed.	指定的参数Count不合法。
400	InvalidInstanceDescription.Malformed	The specified InstanceDescription is malformed.	指定的实例描述不合法。
400	InvalidInstanceTypeForCreateReservedInstance.Unsupported	The specified InstanceType does not support creation of reserved instances.	指定的实例规格不支持创建预留实例券。
400	InvalidPeriod	The specified period is not valid.	指定的计费周期个数不合法。
400	InvalidPeriodUnit	The specified PeriodUnit is not valid, is unsupported, or cannot be used.	指定的计费周期不合法。
400	InvalidReservedInstanceName.Malformed	The specified ReservedInstanceName is malformed.	指定的ReservedInstanceName不合法。
400	InvalidReservedStorageCapacityName.Malformed	The specified ReservedStorageCapacityName is malformed.	指定的ReservedStorageCapacityName不合法。
400	InvalidScope.Malformed	The specified Scope is malformed.	指定的预留实例券级别不合法。
400	InvalidTagKey.Malformed	The specified TagKey is malformed.	指定的标签的键不合法。
400	InvalidTagValue.Malformed	The specified TagValue is malformed.	指定的标签的值不合法。
400	InvalidVolumeType.Malformed	The specified VolumeType is malformed.	指定的云盘类型不合法。
400	LimitExceeded.MaximumInstanceCount	The number of specified InstanceCount exceeds the maximum limit.	指定的InstanceCount超过最大限制。
400	LimitExceeded.MaximumTags	You've reached the limit on the number of tags that you can create.	指定的标签数量超过最大限制。
400	LimitExceeded.MinimumInstanceCount	The number of specified InstanceCount exceeds the minimum limit.	指定的InstanceCount超过最小限制。
400	LimitExceeded.ReservedCapacitySize	The specified reserved capacity size exceeds the limit.	指定的预留存储容量大小(GiB)超出限制。
400	MissingParameter.InstanceTypeId	The required parameter InstanceTypeId is not supplied.	实例规格ID不能为空。
400	MissingParameter.ReservedInstanceName	The required parameter ReservedInstanceName is not supplied.	参数ReservedInstanceName不能为空。
400	MissingParameter.ZoneId	The required parameter ZoneId is not supplied.	可用区ID不能为空。
400	QuotaExceeded.MaximumGeneralCpus	You've reached the limit on the number of general instances CPU that you can create, please submit ticket or sign-on to the Console to request an increase in [general_vcpu] quota.	通用型实例CPU数量配额不足，请提工单或前往控制台申请提高配额。
400	QuotaExceeded.MaximumGpuBasicNums	You've reached the limit on the GPU number of GPU-accelerated instances that you can create, please submit ticket or sign-on to the Console to request an increase in [gpu_basic] quota.	GPU计算型实例卡数配额不足，请提工单或前往控制台申请提高配额。
400	QuotaExceeded.MaximumHighPerformanceGpus	You've reached the limit on the GPU number of High Performance Computing GPU instances that you can create, please submit ticket or sign-on to the Console to request an increase in [gpu_high_performance] quota.	高性能计算GPU型实例卡数配额不足，请提工单或前往控制台申请提高配额。
400	QuotaExceeded.MaximumLocalVolumeCpus	You've reached the limit on the number of local volume instances CPU that you can create, please submit ticket or sign-on to the Console to request an increase in [local_volume_vcpu] quota.	本地盘实例CPU数量配额不足，请提工单或前往控制台申请提高配额。
400	QuotaExceeded.MaximumReservedInstanceCpus	You've reached the limit on the number of reserved instance CPU that you can create, please submit ticket to request an increase in quota.	预留实例CPU数量配额不足，请提工单申请提高配额。
400	QuotaExceeded.MaximumReservedInstanceGeneralCpus	You've reached the limit on the number of general reserved instances CPU that you can create, please submit ticket or sign-on to the Console to request an increase in [general_vcpu_ri_regional] quota.	通用型实例地域级RI CPU数量配额不足，请提工单或前往控制台申请提高配额。
400	QuotaExceeded.MaximumReservedInstanceGpuBasicNums	You've reached the limit on the GPU number of GPU-accelerated reserved instances that you can create, please submit ticket or sign-on to the Console to request an increase in [gpu_basic_ri_regional] quota.	GPU计算型实例地域级RI卡数配额不足，请提工单或前往控制台申请提高配额。
400	QuotaExceeded.MaximumReservedInstanceHighPerformanceGpus	You've reached the limit on the GPU number of High Performance Computing GPU reserved instances that you can create, please submit ticket or sign-on to the Console to request an increase in [gpu_high_performance_ri_regional] quota.	高性能计算GPU型实例地域级RI卡数配额不足，请提工单或前往控制台申请提高配额。
400	QuotaExceeded.MaximumReservedInstanceLocalVolumeCpus	You've reached the limit on the number of local volume reserved instances CPU that you can create, please submit ticket or sign-on to the Console to request an increase in [local_volume_vcpu_ri_regional] quota.	本地盘实例地域级RI CPU数量配额不足，请提工单或前往控制台申请提高配额。
400	QuotaExceeded.MaximumReservedInstanceTypeInstances	You've reached the limit on the number of reserved instance type instances that you can create, please submit ticket to request an increase in quota.	预留规格实例数量配额不足，请提工单申请提高配额。
400	QuotaExceeded.MaximumReservedInstances	You've reached the limit on the number of reserved instances that you can create, please submit ticket to request an increase in quota.	预留实例数量配额不足，请提工单申请提高配额。
404	InvalidHpcCluster.NotFound	The specified HpcCluster does not exist.	指定的高性能集群不存在。
404	InvalidInstanceType.NotFound	The specified InstanceType does not exist.	指定的实例规格不存在。
404	InvalidProject.NotFound	The specified Project does not exist.	指定的Project不存在。
404	InvalidRegion.NotFound	The specified region does not exist.	指定的Region不存在。
404	InvalidZone.NotFound	The specified zone does not exist.	指定的可用区不存在。
409	InvalidTagKey.Conflict	The specified TagKey already exists.	指定的标签键已存在。
412	OperationDenied.ReservedStorageCapacityNotAvailable	The specified operation is denied as the reserved storage capacity is not available.	预留存储容量包功能不可用，请联系管理员。
500	Insufficient.InstanceCapacity	There is not enough capacity to fulfill your request.	当前资源不足，请稍后重试或选择其它实例规格。
500	Insufficient.VolumePoolCapacity	There is not enough capacity to fulfill your request.	当前存储池容量不足。
500	InternalError	An internal error has occurred.	内部错误，请重试。如果多次尝试失败，请提交工单。

最近更新时间：2025.09.04 16:59:41

这个页面对您有帮助吗？

有用

无用