You need to enable JavaScript to run this app.
导航
云服务器
  • 文档首页
    • /
  • 云服务器

PurchaseReservedInstances - 购买预留实例券

最近更新时间：2024.05.21 10:23:57

首次发布时间：2023.11.21 10:21:45

我的收藏

调用 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个字符。

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时，必须传入该参数。

ReservedInstanceName
String
是

reserved-instance-test

预留实例券的名称。

  • 不能以数字、中划线、下划线开头。
  • 只能包含中文、字母、数字、下划线“_”和中划线“-”。
  • 长度限制为1～128个字符。
  • 暂不支持特殊字符。
Scope
String
否

ZonalRI

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

  • ZonalRI（默认）：可用区级预留实例券。
  • RegionalRI：地域级预留实例券。地域级预留实例券正在邀测中，如需试用，请联系客户经理申请。
Tags.N.Key
Array of String
是

Tags.1.Key=k1&Tags.2.Key=k2

用户标签的标签键。

  • 参数 - N：表示标签键的序号，取值范围：1～20。
  • 多个标签键之间用&分隔。

命名规则如下：

  • 不能以volc:或sys:的任意大小写组合开头。
  • 只能包含语言字符、数字、空格和英文符号“_”、“.”、“:”、“/”、“=”、“+”、“-”、“@”。
  • 长度限制在1～128个字符之间。

说明

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

Tags.N.Value
Array of String
否

Tags.1.Value=v1&Tags.2.Value=v2

用户标签的标签值。

  • 参数 - N：表示标签值的序号，取值范围：1～20。
  • 多个标签值之间用&分隔。

命名规则如下：

  • 只能包含语言字符、数字、空格和英文符号“_”、“.”、“:”、“/”、“=”、“+”、“-”、“@”。
  • 允许为空，长度限制在0～256个字符之间。

说明

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

ZoneId
String
否

cn-beijing-a

预留实例券所在可用区ID。
您可以调用 DescribeZones 查询一个地域下的可用区信息。

说明

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

返回参数

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

参数
类型
示例值
描述
ReservedInstanceId
String

ecsri-ycq8kgnlxrb5oxt0****

预留实例券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: open.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
InvalidInstanceTypeForCreateReservedInstance.Unsupported
The specified InstanceType does not support creation of reserved instances.

指定的实例规格不支持创建预留实例券。

400
InvalidCount.Malformed
The specified count is malformed.

指定的参数Count不合法。

400
InvalidTagValue.Malformed
The specified TagValue is malformed.

指定的标签的值不合法。

400
InvalidTagKey.Malformed
The specified TagKey is malformed.

指定的标签的键不合法。

400
InvalidScope.Malformed
The specified Scope is malformed.

指定的预留实例券级别不合法。

400
InvalidReservedInstanceName.Malformed
The specified ReservedInstanceName is malformed.

指定的ReservedInstanceName不合法。

400
InvalidPeriodUnit
The specified PeriodUnit is not valid, is unsupported, or cannot be used.

指定的计费周期不合法。

400
InvalidPeriod
The specified period is not valid.

指定的计费周期个数不合法。

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.

预留实例数量配额不足，请提工单申请提高配额。

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.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
MissingParameter.ZoneId
The required parameter ZoneId is not supplied.

可用区ID不能为空。

400
MissingParameter.ReservedInstanceName
The required parameter ReservedInstanceName is not supplied.

参数ReservedInstanceName不能为空。

400
MissingParameter.InstanceTypeId
The required parameter InstanceTypeId is not supplied.

实例规格ID不能为空。

400
LimitExceeded.MinimumInstanceCount
The number of specified InstanceCount exceeds the minimum limit.

指定的InstanceCount超过最小限制。

400
LimitExceeded.MaximumTags
You've reached the limit on the number of tags that you can create.

指定的标签数量超过最大限制。

400
LimitExceeded.MaximumInstanceCount
The number of specified InstanceCount exceeds the maximum limit.

指定的InstanceCount超过最大限制。

404
InvalidZone.NotFound
The specified zone does not exist.

指定的可用区不存在。

404
InvalidRegion.NotFound
The specified region does not exist.

指定的Region不存在。

404
InvalidProject.NotFound
The specified Project does not exist.

指定的Project不存在。

404
InvalidInstanceType.NotFound
The specified InstanceType does not exist.

指定的实例规格不存在。

404
InvalidHpcCluster.NotFound
The specified HpcCluster does not exist.

指定的高性能集群不存在。

409
InvalidTagKey.Conflict
The specified TagKey already exists.

指定的标签键已存在。

500
InternalError
An internal error has occurred.

内部错误，请重试。如果多次尝试失败，请提交工单。

500
Insufficient.VolumePoolCapacity
There is not enough capacity to fulfill your request.

当前存储池容量不足。

500
Insufficient.InstanceCapacity
There is not enough capacity to fulfill your request.

当前资源不足，请稍后重试或选择其它实例规格。