调用CreateCapacityReservation创建容量预定服务-云服务器 ECS-阿里云-云服务器 ECS(ECS)-阿里云帮助中心

指定需要预留的实例规格、总数量，生效方式和可用区等，创建容量预定服务。

接口说明

您可以通过容量预定服务，指定可用区、实例规格等属性，系统会以私有池的方式预留属性相匹配的资源。更多信息，请参见立即生效容量预定概述。

目前服务仅支持立即生效模式。购买立即生效容量预定服务后，实例规格即开始遵循按量付费标准计费，不论是否实际创建了按量付费实例，直至您自行手动释放或到期系统自动释放立即生效容量预订。
- 您可以通过 CreateInstance 或 RunInstances 创建实例时设置私有池容量选项，或者通过 ModifyInstanceAttachmentAttributes 修改实例的私有池容量选项。实例成功匹配私有池容量后，将根据您的实例配置收取实例规格、云盘、公网带宽等相关资源费用。
- 未实际创建按量付费实例时，仅收取实例规格的费用。
立即生效容量预定的匹配的实例和未使用的容量账单支持通过节省计划、地域级预留实例券抵扣小时账单，不支持通过可用区级预留实例券抵扣小时账单。推荐您先购买预留实例券或节省计划，在预留实例券或节省计划的覆盖下使用立即生效容量预定服务，可以免费获取资源的确定性保障。

说明

调用 API 方式仅支持创建立即生效容量预定。通过 ECS 控制台可以创建立即生效容量预定或指定时间生效容量预定，更多信息，请参见资源预定服务。

调试

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

调试

授权信息

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

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

操作

访问级别

资源类型

条件关键字

关联操作

ecs:CreateCapacityReservation

create

*CapacityReservation

acs:ecs:{#regionId}:{#accountId}:capacityreservation/*

无

请求参数

名称	类型	必填	描述	示例值
RegionId	string	是	容量预定服务所属地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。	cn-hangzhou
ResourceGroupId	string	否	容量预定服务所在的企业资源组 ID。	rg-bp67acfmxazb4p****
Tag	array<object>	否	容量预定服务绑定的标签对列表。
	object	否	标签对。
Key	string	否	容量预定服务的标签键。N 的取值范围：1~20。一旦传入该值，则不允许为空字符串。最多支持 128 个字符，不能以`aliyun`和`acs:`开头，不能包含`http://`或者`https://`。	TestKey
Value	string	否	容量预定服务的标签值。N 的取值范围：1~20。一旦传入该值，允许为空字符串。最多支持 128 个字符，不能以`acs:`开头，不能包含`http://`或者`https://`。	TestValue
ClientToken	string	否	保证请求幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。`ClientToken`只支持 ASCII 字符，且不能超过 64 个字符。更多信息，请参见如何保证幂等性。	0c593ea1-3bea-11e9-b96b-88e9fe637760
PrivatePoolOptions.Name	string	否	容量预定服务的名称。长度为 2~128 个英文或中文字符。必须以大小写字母或中文开头，不能以`http://`和`https://`开头。可以包含数字、半角冒号（:）、下划线（_）或者短划线（-）。	crpTestName
Description	string	否	容量预定服务的描述信息。长度为 2~256 个英文或中文字符，不能以`http://`和`https://`开头。默认值：空。	This is description.
PrivatePoolOptions.MatchCriteria	string	否	容量预定服务生效后生成的私有资源池的类型。取值范围： Open：开放模式。启动实例时将自动匹配开放类型的私有池容量。如果没有符合条件的私有池容量，则使用公共池资源启动。 Target：专用模式。使用指定的私有池容量启动实例，如果该私有池容量不可用，则实例会启动失败。默认值：Open。	Open
InstanceAmount	integer	是	在一个实例规格内，需要预留的实例的总数量。	2
InstanceType	string	是	实例规格。目前仅支持为一个实例规格设置容量预定服务。您可以调用 DescribeInstanceTypes 查询云服务器 ECS 提供的实例规格信息。	ecs.g6.xlarge
StartTime	string	否	容量预定服务的生效方式。目前调用 API 的方式仅支持设置为立即生效。说明该参数不传值即表示设置为立即生效。	2021-10-30T05:32:00Z
EndTime	string	否	容量预定服务的失效时间。时间格式以 ISO 8601 为标准，并需要使用 UTC +0 时间，格式为`yyyy-MM-ddTHH:mm:ssZ`。更多信息，请参见ISO 8601。	2021-10-30T06:32:00Z
EndTimeType	string	否	容量预定服务的失效方式。取值范围： Limited：指定时间释放。必须同时指定`EndTime`参数。 Unlimited：手动释放。不限制时间。	Unlimited
Platform	string	否	实例使用的镜像的操作系统类型。该参数与地域级预留实例券的`Platform`参数对应。如果容量预定服务和地域级预留实例券的操作系统类型相匹配，则可以使用地域级预留实例券来抵扣容量预定服务中的未使用容量的账单。取值范围： Windows：Windows Server 类型的操作系统。 Linux：Linux 及类 Unix 类型的操作系统。默认值：Linux。说明该参数暂未开放使用。	Linux
InstanceChargeType	string	否
ZoneId	array	是	容量预定服务所属地域下的可用区 ID。目前仅支持在一个可用区下创建容量预定服务。	cn-hangzhou-h
	string	否	容量预定服务所属地域下的可用区 ID。	cn-hangzhou-h

返回参数

名称	类型	描述	示例值
	object
PrivatePoolOptionsId	string	容量预定服务 ID。	crp-bp67acfmxazb4****
RequestId	string	请求 ID。	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

示例

正常返回示例

JSON格式

{
  "PrivatePoolOptionsId": "crp-bp67acfmxazb4****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

错误码

HTTP status code	错误码	错误信息	描述
400	InvalidParameter.RegionId	The specified RegionId is invalid.	指定的地域不存在或不可用。
400	NoStock	The stock in the availability zone is insufficient.	该可用区没有足够的库存
400	MissingParameter	The input parameter StartTime is missing.
400	OperationDenied	The specified instanceType or zone is not available or not authorized.	指定的规格或可用区不可用
400	MissingParameter.RegionId	The specified RegionId should not be null.	RegionId是必选参数。
400	InvalidStartTime.NotSupported	The specified StartTime should be within 180 calendar days from the current date, and you must specify a precision to hour.	指定的 StartTime 参数不在有效取值范围内。
400	InvalidStartTime.MalFormed	The specified StartTime is out of the permitted range.	指定的 StartTime 参数超出了最大有效取值。
400	Invalid.PrivatePoolOptionsName.MalFormed	The specified PrivatePoolOptions.Name is not valid.	指定的PrivatePoolOptions.Name无效
400	Invalid.ZoneId	The specified ZoneId is not valid.	指定的ZoneId不合法
400	Invalid.InstanceType	The specified InstanceType is not valid.	指定的InstanceType不合法。
400	DedicatedHostNotSupported	DedicatedHost is not supported for PrivatePool.	私有池不支持专有宿主机。
400	SpotNotSupported	Spot is not supported for PrivatePool.	私有池不支持抢占式实例。
400	ClassicNetworkNotSupported	Classic network is not supported for PrivatePool.	私有池不支持经典网络类型实例。
400	Invalid.InstanceId	Instance does not exist.	实例不存在。
400	Invalid.PrivatePoolOptions.MatchCriteria	Target mode does not support this operation.	Target模式不支持本次操作。
400	MissingParameter.PrivatePoolOptions.Id	The specified PrivatePoolOptions.Id should not be null.	PrivatePoolOptions.Id 参数不能为空。
400	Invalid.PrivatePoolOptions.Id	The PrivatePool does not exist.	私有池不存在。
400	Invalid.InstanceChargeType	The InstanceChargeType does not match the PrivatePool.	实例计费类型与私有池不匹配。
400	Invalid.PrivatePoolOptions.status	The PrivatePool has been used up.	该资源已用完。
400	InvalidPlatform.ValueNotSupported	The Platform does not match the PrivatePool.	指定的Platform参数与私有池不匹配。
400	InvalidAliUid	The PrivatePool does not belong to the user of the Instance.	私有池不属于创建实例的用户。
400	MissingParameter.PackageType	The specified parameter "PackageType" can not be empty.	指定的参数PackageType不能为空。
400	MissingParameter.PrivatePoolOptions.Ids	The specified parameter "PrivatePoolOptions.Ids" can not be empty.	指定参数“PrivatePoolOptions.ids”不能为空。
400	MissingParameter.InstanceCpuCoreCount	The specified parameter "InstanceCpuCoreCount" can not be empty.	指定的参数 'InstanceCpuCocount'不能为空。
400	MissingParameter.InstanceAmount	The specified parameter "InstanceAmount" can not be empty.	指定的参数InstanceAmount不能为空。
400	MissingParameter.InstanceCpuCoreCountOrInstanceAmount	The specified parameter "InstanceCpuCoreCount" and "InstanceAmount" must not be empty at the same time.	指定的参数InstanceCpuCoreCount和InstanceAmount不能同时为空。
400	Invalid.TooManyPrivatePoolOptions.Ids	Too many PrivatePoolOptions.Ids in this request.	PrivatePoolOptions.Ids参数超过上限。
400	Invalid.TooManyZoneIds	Too many ZoneIds in the request.	ZoneIds参数超过上限。
400	Invalid.TooManyInstanceTypes	Too many InstanceTypes in the request.	InstanceTypes参数超过上限。
400	Invalid.TooManyUnpaidPrivatePool	Too many PrivatePools create but still unpaid.	多个私有池未支付。
400	Invalid.InstanceCpuCoreCountOrInstanceAmount	Both InstanceCpuCoreCount and InstanceAmount are provided.	InstanceCpuCoreCount和InstanceAmount两个参数不需要同时提供。
400	Invalid.PrivatePoolOptions.Ids	The specified parameter "PrivatePoolOptions.Ids" exist invalid element Id.	指定的私有池ID不存在。
400	Invalid.PackageType	The specified parameter "PackageType" is invalid.	指定的参数“PackageType”无效。
400	Invalid.PrivatePool.Purchase	The PrivatePool has already paid.	私有池已经支付。
400	Invalid.AssuranceTimes.NotSupported	The value of AssuranceTimes is not supported.	AssuranceTimes参数值不支持。
400	RepeatStartPrivatePool	PrivatePool has already been started.	私有池已经启动。
400	Invalid.TimeSlot	The param time slot is invalid.	参数“TimeSlot”无效。
400	Invalid.EndTime	The specified parameter "EndTime" is not valid.	指定的EndTime参数不合法。
400	StartTime.NotNeed	The specified parameter "StartTime" should leave empty.	指定的参数“StartTime”应该为空。
400	AccountForbidden.ProductCreationLimited	The commodity must be officially operated by Aliyun and in pay-as-you-go billing method.	集团上云客户只能购买按量付费的 ECS，且不能购买第三方的商品比如由镜像市场提供的镜像。请检查参数，传入符合条件的参数重试。
400	RegionUnauthorized	There is no authority to create private pool in the specified region.	在指定的地域内没有创建私有池的权限
400	PriceNotFound	The price of your queried resource is not available now, please try other resources.	未找到价格，请修改相应的参数值重试。
500	InternalError	The request processing has failed due to some unknown error, exception or failure.	内部错误，请重试。
403	Zone.NotOpen	The specified zone is not granted to you to buy resources yet.
403	InvalidResourceType.NotSupported	%s	指定资源组合不存在，请更换其他可用区或规格
403	OperationDenied.NoStock	The resource is out of stock in the specified zone. Please try other types, or choose other regions and zones.	指定的资源在指定可用区中无货。请尝试其他类型，或选择其他可用区和地域。
403	InvalidInstanceType.NotSupported	The specified InstanceType is invalid.
403	Invalid.ZoneIds	At least one of the specified ZoneIds are invalid.	指定的ZoneIds中至少有一个无效。
403	Zone.NotOnSale	The specified zone is not available for purchase.	指定可用区已经售罄，请您更换实例规格或者更换地域创建。
404	InvalidZoneId.NotFound	The specified zoneId does not exist.	指定的可用区 ID 不存在。
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	资源组并不在记录中。

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

变更历史

更多信息，参考变更详情。