Purchases a reserved instance. When you call this operation, you can specify parameters, such as InstanceType and Scope, in the request. Reserved instances can be applied to automatically offset fees for pay-as-you-go Elastic Compute Service (ECS) instances.
Operation description
Usage notes
- Before you call this operation, make sure that you fully understand the billing method of reserved instances. For more information, see Reserved instances.
- Before you purchase a reserved instance, you can call the DescribeAvailableResource operation to query available instance resources.
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resourcesis used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| ecs:PurchaseReservedInstancesOffering | create | *ReservedInstance acs:ecs:{#regionId}:{#accountId}:reservedinstance/* |
| none |
Request parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| RegionId | string | Yes | The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list. | cn-hangzhou |
| Tag | array<object> | No | The list of tags. | |
| object | No | |||
| Key | string | No | The key of tag N of the reserved instance. Valid values of N: 1 to 20. The tag key cannot be an empty string. The tag key can be up to 128 characters in length and cannot contain | TestKey |
| Value | string | No | The value of tag N of the reserved instance. Valid values of N: 1 to 20. The tag value cannot be an empty string. The tag value can be up to 128 characters in length and cannot contain | TestValue |
| ResourceGroupId | string | No | The ID of the resource group. | rg-bp199lyny9b3**** |
| ZoneId | string | No | The zone ID of the instance. This parameter is required when | cn-hangzhou-g |
| ReservedInstanceName | string | No | The name of the reserved instance. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with http:// or https://. The name can contain letters, digits, colons (:), underscores (_), and hyphens (-). | testReservedInstanceName |
| InstanceType | string | Yes | The type of the reserved instance. For more information, see Instance family. | ecs.g5.large |
| Scope | string | No | The scope of reserved instance N. Valid values:
Default value: Region. | Zone |
| InstanceAmount | integer | No | The number of pay-as-you-go instances of the same instance type that the reserved instance can match at the same time. Valid values: 1 to 50. For example, if you set the InstanceAmount parameter to 3 and the InstanceType parameter to ecs.g5.large, the reserved instance can be matched three ecs.g5.large pay-as-you-go instances at the same time. | 3 |
| OfferingType | string | No | The payment option of the reserved instance. Valid values:
Default value: All Upfront. | All Upfront |
| Description | string | No | The description of the reserved instance. The description can be 2 to 256 characters in length and cannot start with http:// or https://. This parameter is left empty by default. | testDescription |
| Platform | string | No | The operating system of the image used by the instance. Valid values:
Default value: Linux. | Linux |
| Period | integer | No | The validity period of the reserved instance. Valid values: 1 and 3. Default value: 1. | 1 |
| PeriodUnit | string | No | The unit of the validity period of the reserved instance. Valid value: Year. Default value: Year. | Year |
| ClientToken | string | No | The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence. | 123e4567-e89b-12d3-a456-426655440000 |
| AutoRenew | boolean | No | Specifies whether to enable auto-renewal for the reserved instance. Valid values:
| true |
| AutoRenewPeriod | integer | No | The auto-renewal term of the reserved instance. Unit: months. This parameter takes effect only when AutoRenew is set to true. Valid values: 12 and 36. Default value when PeriodUnit is set to Year: 12. | 1 |
| StartTime | string | No | The time when the reserved instance takes effect. Specify the time in the ISO 8601 standard in the | 2024-07-04T15Z |
Response parameters
Examples
Sample success responses
JSONformat
{
"RequestId": "8C314443-AF0D-4766-9562-C83B7F1A3C8B",
"ReservedInstanceIdSets": {
"ReservedInstanceId": [
"ecsri-2ze53qonjqxg7r****"
]
}
}Error codes
| HTTP status code | Error code | Error message | Description |
|---|---|---|---|
| 400 | InvalidStartTime.ScopeNotMatch | Zonal reservedInstance not supported for scheduled creating. | - |
| 400 | InvalidInstanceType.ValueUnauthorized | The specified InstanceType is not authorized. | You are not authorized to use the specified instance type. |
| 400 | InvalidDescription.Malformed | The specified parameter "Description" is not valid. | The source description can be 2 to 256 characters in length. It cannot start with http:// and https://. |
| 400 | InvalidParameter.Conflict | The specified region and cluster do not match. | The specified region and cluster do not correspond to each other. |
| 400 | InvalidTagKey.Malformed | The specified Tag.n.Key is not valid. | The specified Tag.N.Key parameter is invalid. |
| 400 | RegionUnauthorized | %s | - |
| 400 | Zone.NotOnSale | %s | The requested resources are unavailable in the specified zone. %s is a variable. An error message is dynamically returned based on call conditions. |
| 400 | InvalidPeriodUnit.ValueNotSupported | The specified parameter PeriodUnit is not valid. | The specified PeriodUnit parameter is invalid. |
| 400 | InvalidTagValue.Malformed | The specified Tag.n.Value is not valid. | The specified tag value is invalid. |
| 400 | InvalidChargeType.ValueNotSupported | ChargeType is not valid. | This billing method is not supported. Select another billing method. |
| 400 | InvalidParameter.Scope | The specified parameter 'Scope' is invalid. | - |
| 400 | InvalidReservedInstanceStatus.ValueNotSupported | ReservedInstance status is not supported. | - |
| 400 | InvalidReservedInstanceOfferingType.ValueNotSupported | The OfferingType is not supported. | - |
| 400 | InvalidReservedInstanceOfferingClass.ValueNotSupported | The OfferingClass is not supported. | - |
| 400 | MissingParameter.ZoneId | The specified zoneId should be not empty. | - |
| 400 | MissingParameter.InstanceType | The instanceType should be not empty. | - |
| 400 | MissingParameter.ReservedInstanceId | The ids of reservedInstance can not be empty. | - |
| 400 | MissingParameter.ReservedInstanceConfiguration | The configurations of reservedInstance can not be empty. | - |
| 400 | InvalidParameter.SplitOrMerge | The Many-to-many of modification is not supported. | - |
| 400 | MissingParameter.InstanceTypeAndAmountBothEmpty | The instanceType and amount can not be both empty. | - |
| 400 | InvalidReservedInstancePlatform.ValueNotSupported | The Platform is not supported. | - |
| 400 | InvalidParameter.ReservedInstanceName | ReservedInstanceName is invalid. | - |
| 400 | InvalidReservedInstanceZone.ValueNotSupported | The zoneId is not exist. | - |
| 400 | OperationDenied | The specified InstanceType or Zone is not authorized for current user. | - |
| 400 | InvalidInstanceType.ValueNotSupported | The specified InstanceType beyond the permitted range. | - |
| 400 | InvalidInstanceType.ValueNotSupported | The specified InstanceType does not exist or beyond the permitted range. | The specified instance type does not exist or you are not authorized to manage instances of this instance type. |
| 403 | OperationDenied | The creation of Host to the specified Zone is not allowed. | Dedicated hosts cannot be created in the specified zone. |
| 403 | OperationDenied.NoStock | The requested resource is sold out in the specified zone; try other types of resources or other regions and zones. | The requested resources are insufficient. |
| 403 | OperationDenied | Sales of this resource are temporarily suspended in the specified region; please try again later. | The requested resource is unavailable in the specified region. Try again later. |
| 403 | NodeControllerUnavailable | The Node Controller is temporarily unavailable. | The node controller is unavailable. |
| 403 | OperationDenied | The resource is out of usage. | The instance is not in the Running state. Start the instance or check whether the specified operation is valid. |
| 403 | InvalidParameter.ResourceOwnerAccount | ResourceOwnerAccount is Invalid. | The specified ResourceOwnerAccount parameter is invalid. |
| 403 | Zone.NotOpen | The specified zone is not granted to you to buy resources yet. | You are not authorized to purchase resources in the specified zone. |
| 403 | Zone.NotOnSale | The specified zone is not available for purchase. | The requested resources are unavailable in the specified zone. Try a different instance type or select a different region or zone. |
| 403 | InvalidResourceType.NotSupported | %s | - |
| 403 | InvalidParameter.NotMatch | %s | A specified parameter is invalid. Check whether parameter conflicts exist. |
| 403 | Account.Arrearage | Your account has been in arrears. | Your account does not have enough balance. Please add funds to your account. |
| 403 | InvalidStartTime.MalFormed | The specified StartTime is not valid. | - |
| 403 | InvalidStartTime.NotSupported | The specified startTime is not supported. | - |
| 404 | InvalidZoneId.NotFound | The ZoneId provided does not exist in our records. | The specified zone ID does not exist. |
| 404 | PaymentMethodNotFound | No payment method has been registered on the account. | You have not configured a payment method for your account. |
| 404 | InvalidZoneId.NotFound | The specified ZoneId does not exist. | The specified zone ID does not exist. |
| 500 | InternalError | The request processing has failed due to some unknown error. | An internal error has occurred. Try again later. |
| 500 | InternalError | %s | An internal error has occurred. |
| 500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | An internal error has occurred. Try again later. |
For a list of error codes, visit the Service error codes.
Change history
| Change time | Summary of changes | Operation |
|---|---|---|
| 2024-08-21 | The Error code has changed. The request parameters of the API has changed | View Change Details |
| 2022-11-02 | The Error code has changed. The request parameters of the API has changed | View Change Details |