1. Interface Description
Interface request domain name: cvm.api3.convergecloud.com.
This API (DescribeInstances) is used to query the detailed information of one or more instances.
- You can query the detailed information of an instance based on information such as the instance ID, instance name, or instance billing mode. For detailed filtering information, see the
Filter. - If no parameter is defined, a specific number (specified by the
Limit, 20 by default) of instances of the current user are returned.
Default interface request rate limit: 20 times per second.
Interface update time: 2022-10-26 11:54:05.
The interface only verifies the signature but does not authenticate.
2. Input Parameters
The following list of request parameters only lists interface request parameters and some public parameters, For a complete list of public parameters see public request parameters.
| Parameter name | Required | Allow NULL | Type | Description |
|---|---|---|---|---|
| Action | Yes | No | String | Public parameter, The value of this interface: DescribeInstances |
| Version | Yes | No | String | Public parameter, The value of this interface: 2017-03-12 |
| Region | No | No | String | Public parameter,Regional information A list of supported geographies is available through the DescribeRegions interface |
| InstanceIds | No | No | Array of String | Query by one or more instance IDs. The instance ID is in the format of ins-11112222. For the specific format of this parameter, see the section id.N in the API Introduction. A maximum of 100 instances per request are allowed. This parameter does not support specifying InstanceIds and Filters at the same time.Example: ['ins-rf6ogz49'] |
| Filters | No | No | Array of Filter | Filtering conditions. For details, see the instance filtering condition table below. Each request can have up to 10 filters, and each filter can have up to 5 values. The InstanceIds and Filters parameters cannot be specified at the same time. zone Filter by [availability zone]. For example, ap-region1-1. Type: String. Required: No. Valid values: Availability zone list. project-id Filter by [project ID]. You can query the list of created projects by calling DescribeProject or log in to the console to view projects. You can also call AddProject to create a project. For example, 1002189. Type: Integer. Required: No. host-id Filter by [CDH ID]. For example, host-xxxxxxxx. Type: String. Required: No. vpc-id Filter by [VPC ID]. For example, vpc-xxxxxxxx. Type: String. Required: No. subnet-id Filter by [subnet ID]. For example, subnet-xxxxxxxx. Type: String. Required: No. instance-id Filter by [instance ID]. For example, ins-61dyt49hxxxx. Type: String. Required: No. security-group-id Filter by [security group ID]. For example, sg-8jlk3f3r. Type: String. Required: No. instance-name Filter by [instance name]. Type: String. Required: No. instance-charge-type Filter by [instance billing mode]. (POSTPAID_BY_HOUR: post-payment, that is, pay-as-you-go. |
| Offset | No | No | Int64 | Offset, 0 by default. For further introduction to the Offset, see relevant sections in the API Introduction.Example: 1 |
| Limit | No | No | Int64 | Number of returns, 20 by default, and the maximum value is 100. For further introduction to the Limit, see relevant sections in the API Introduction.Example: 5 |
| InnerVpcIds | No | No | Array of Int64 | Internal parameters, list of numeric vpcIds. Example: NA |
| InnerSubnetIds | No | No | Array of Int64 | Internal parameters, list of numeric subnetIds. Example: NA |
| IpAddresses | No | No | Array of String | Internal parameters, precise lists of private and public network IPs. Example: NA |
| VagueIpAddress | No | No | String | Internal parameters, fuzzy matching of private and public network IPs. Example: NA |
| VagueInstanceName | No | No | String | Internal parameters, fuzzy matching of instance alias. Example: NA |
3. Output Parameters
| Parameter name | Type | Description |
|---|---|---|
| TotalCount | Int64 | Number of eligible instances. Example: 1 |
| InstanceSet | Array of Instance | List of detailed information of instances. Example:View |
| RequestId | String | Unique request id, Each request will return. The RequestId of the request needs to be provided when locating the problem. |
4. Error Code
The following lists only the error codes related to the interface business logic, For other error codes, see public ErrorCode.
| Error Code | Description |
|---|---|
| InvalidFilter | Invalid filter. |
| InvalidParameterValue | Invalid parameter value. The format of the parameter value is incorrect or not supported, etc. |
| InvalidFilterValue.LimitExceeded | The number of Filter parameter values exceeds the limit. |
| InternalServerError | Internal operation error. |
| InvalidParameterValue.LimitExceeded | The parameter value is out of range |
| InvalidHostId.Malformed | Invalid CDH ID. The format of the specified CDH ID is incorrect, for example, an ID length error host-1122. |
| InvalidInstanceId.Malformed | Invalid Instance ID. The format of the specified instance ID is incorrect, for example, an instance ID length error ins-1122. |
| InvalidParameter | Invalid parameter. The parameter does not meet the requirements, is not supported, or the like. |
| InvalidZone.MismatchRegion | The specified zone does not exist. |