本接口支持根据不同请求条件查询实例列表，并关联查询实例的详细信息。
接口说明
使用须知
- 通过阿里云 CLI 调用 API 时，不同数据类型的请求参数取值必须遵循格式要求。更多信息，请参见 CLI 参数格式说明。
- 如果您使用的是 RAM 用户账号或者 RAM 角色，当用户或者角色缺乏接口权限时，将会返回空列表。
使用建议
-
通过请求参数 DryRun 发送预检请求，可以检查参数有效性和授权情况。
-
接口支持以下两种方式查看返回数据：
- 方式一：分页查询首页时，仅需设置
MaxResults以限制返回信息的条目数，返回结果中的NextToken值将作为查询后续页的凭证。查询后续页时，将NextToken参数设置为上一次返回结果中获取到的NextToken值作为查询凭证，并设置MaxResults限制返回条目数。 - 方式二：通过
PageSize设置单页返回的条目数，再通过PageNumber设置页码。
以上两种方式只能任选其中之一，当返回的条目数较多时，推荐使用方式一。
说明 如果设置了MaxResults或NextToken参数，则请求参数PageSize和PageNumber将失效，且返回数据中的TotalCount无效。 - 方式一：分页查询首页时，仅需设置
调试
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：
- 操作：是指具体的权限点。
- 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
- 资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用
全部资源表示。
- 条件关键字：是指云产品自身定义的条件关键字。
- 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
| 操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
|---|---|---|---|---|
| ecs:DescribeInstances | get | *Instance acs:ecs:{#regionId}:{#accountId}:instance/**Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId} |
| 无 |
请求参数
| 名称 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| RegionId | string | 是 | 实例所属的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。 | cn-hangzhou |
| VpcId | string | 否 | 专有网络 VPC ID。 | v-bp67acfmxazb4p**** |
| VSwitchId | string | 否 | 交换机 ID。 | vsw-bp67acfmxazb4p**** |
| ZoneId | string | 否 | 可用区 ID。 | cn-hangzhou-g |
| InstanceNetworkType | string | 否 | 实例网络类型。取值范围：
| vpc |
| SecurityGroupId | string | 否 | 实例所属的安全组。 | sg-bp67acfmxazb4p**** |
| InstanceIds | string | 否 | 实例 ID。取值可以由多个实例 ID 组成一个 JSON 数组，最多支持 100 个 ID，ID 之间用半角逗号（,）隔开。 | ["i-bp67acfmxazb4p****", "i-bp67acfmxazb4p****", … "i-bp67acfmxazb4p****"] |
| PageNumber | integer | 否 | 实例状态列表的页码。 起始值：1。 默认值：1。 | 1 |
| PageSize | integer | 否 | 分页查询时设置的每页行数。 最大值为 100。 默认值为 10。 | 10 |
| NextToken | string | 否 | 查询凭证（Token），取值为上一次 API 调用返回的 | caeba0bbb2be03f84eb48b699f0a4883 |
| MaxResults | integer | 否 | 分页查询时每页行数。最大值为 100。 默认值：
| 10 |
| InnerIpAddresses | string | 否 | 经典网络类型实例的内网 IP 列表。当 InstanceNetworkType=classic 时生效，取值可以由多个 IP 组成一个 JSON 数组，最多支持 100 个 IP，IP 之间用半角逗号（,）隔开。 | ["10.1.1.1", "10.1.2.1", … "10.1.10.1"] |
| PrivateIpAddresses | string | 否 | VPC 网络类型实例的私有 IP。当 InstanceNetworkType=vpc 时生效，取值可以由多个 IP 组成一个 JSON 数组，最多支持 100 个 IP，IP 之间用半角逗号（,）隔开。 | ["172.16.1.1", "172.16.2.1", … "172.16.10.1"] |
| PublicIpAddresses | string | 否 | 实例的公网 IP 列表。取值可以由多个 IP 组成一个 JSON 数组，最多支持 100 个 IP，IP 之间用半角逗号（,）隔开。 | ["42.1.1.**", "42.1.2.**", … "42.1.10.**"] |
| EipAddresses | string | 否 | 实例的弹性公网 IP 列表。当 InstanceNetworkType=vpc 时该参数生效，取值可以由多个 IP 组成一个 JSON 数组，最多支持 100 个 IP，IP 之间用半角逗号（,）隔开。 | ["42.1.1.**", "42.1.2.**", … "42.1.10.**"] |
| InstanceChargeType | string | 否 | 实例的计费方式。取值范围：
| PostPaid |
| InternetChargeType | string | 否 | 公网带宽计费方式。取值范围：
说明
按使用流量计费模式下的出入带宽峰值都是带宽上限，不作为业务承诺指标。当出现资源争抢时，带宽峰值可能会受到限制。如果您的业务需要有带宽的保障，请使用按固定带宽计费模式。
| PayByTraffic |
| InstanceName | string | 否 | 实例名称，支持使用通配符*进行模糊搜索。 | Test |
| ImageId | string | 否 | 镜像 ID。 | m-bp67acfmxazb4p**** |
| Status | string | 否 | 实例状态。取值范围：
| Running |
| LockReason | string | 否 | 资源被锁定的原因。取值范围：
| security |
| Filter.1.Key | string | 否 | 查询资源时的筛选键，取值必须为 | CreationStartTime |
| Filter.2.Key | string | 否 | 查询资源时的筛选键，取值必须为 | CreationEndTime |
| Filter.3.Key | string | 否 | 查询资源时的筛选键，取值必须为 | ExpiredStartTime |
| Filter.4.Key | string | 否 | 查询资源时的筛选键，取值必须为 | ExpiredEndTime |
| Filter.1.Value | string | 否 | 查询资源时的筛选值。指定该参数时必须同时指定 | 2017-12-05T22:40Z |
| Filter.2.Value | string | 否 | 查询资源时的筛选值。指定该参数时必须同时指定 | 2017-12-06T22:40Z |
| Filter.3.Value | string | 否 | 查询资源时的筛选值。指定该参数时必须同时指定 | 2017-12-07T22:40Z |
| Filter.4.Value | string | 否 | 查询资源时的筛选值。指定该参数时必须同时指定 | 2017-12-08T22:40Z |
| DeviceAvailable | boolean | 否 | 说明
该参数正在邀测中，暂不支持使用。
| false |
| IoOptimized | boolean | 否 | 是否是 I/O 优化型实例。取值范围：
| true |
| NeedSaleCycle | boolean | 否 | 说明
该参数正在邀测中，暂不支持使用。
| false |
| InstanceType | string | 否 | 实例的规格。 | ecs.g5.large |
| InstanceTypeFamily | string | 否 | 实例的规格族。 | ecs.g5 |
| KeyPairName | string | 否 | 实例使用的 SSH 密钥对名称。 | KeyPairNameTest |
| ResourceGroupId | string | 否 | 实例所在的企业资源组 ID。使用该参数过滤资源时，资源数量不能超过 1000 个。 说明
不支持默认资源组过滤。
| rg-bp67acfmxazb4p**** |
| HpcClusterId | string | 否 | 实例所在的 HPC 集群 ID。 | hpc-bp67acfmxazb4p**** |
| RdmaIpAddresses | string | 否 | HPC 实例的 RDMA 网络 IP。 | 10.10.10.102 |
| DryRun | boolean | 否 | 是否只预检此次请求。取值范围：
默认值：false。 | false |
| HttpEndpoint | string | 否 | enabled | |
| HttpTokens | string | 否 | 访问实例元数据时是否强制使用加固模式（IMDSv2）。取值范围：
默认值：optional。 说明
有关访问实例元数据模式的更多信息，请参见实例元数据访问模式。
| optional |
| HttpPutResponseHopLimit | integer | 否 | 说明
该参数暂未开放使用。
| 0 |
| Ipv6Address | array | 否 | 为弹性网卡指定的 IPv6 地址。 | |
| string | 否 | 弹性网卡的 IPv6 地址。N 表示可以设置多个 IPv6 地址，N 的取值范围为 1~100。 | 2408:4321:180:1701:94c7:bc38:3bfa:**** | |
| Tag | array<object> | 否 | 标签列表。 | |
| object | 否 | 标签列表。 | ||
| key | string | 否 | 标签键。 说明
为提高兼容性，建议您使用另一个 Tag.N.Key参数。
| keyTest |
| Key | string | 否 | 实例的标签键。N 的取值范围为 1~20。 使用一个标签过滤资源，查询到该标签下的资源数量不能超过 1000 个；使用多个标签过滤资源，查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个，请使用 ListTagResources 接口进行查询。 | TestKey |
| Value | string | 否 | 实例的标签值。N 的取值范围：1~20。 | TestValue |
| value | string | 否 | 标签值。 说明
为提高兼容性，建议您使用另一个 Tag.N.Value参数。
| valueTest |
| AdditionalAttributes | array | 否 | 其他属性值。N 的取值范围为 1~20。取值范围：
| |
| string | 否 | 其他属性值。N 的取值范围为 1~20。取值范围：
| META_OPTIONS |
返回参数
示例
正常返回示例
JSON格式
{
"NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
"PageSize": 10,
"PageNumber": 1,
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
"TotalCount": 1,
"Instances": {
"Instance": [
{
"CreationTime": "2017-12-10T04:04Z",
"SerialNumber": "51d1353b-22bf-4567-a176-8b3e12e4****",
"Status": "Running",
"DeploymentSetId": "ds-bp67acfmxazb4p****",
"KeyPairName": "testKeyPairName",
"SaleCycle": "month",
"SpotStrategy": "NoSpot",
"DeviceAvailable": true,
"LocalStorageCapacity": 1000,
"Description": "testDescription",
"SpotDuration": 1,
"InstanceNetworkType": "vpc",
"InstanceName": "InstanceNameTest",
"OSNameEn": "CentOS 7.4 64 bit",
"HpcClusterId": "hpc-bp67acfmxazb4p****",
"SpotPriceLimit": 0.98,
"Memory": 16384,
"OSName": "CentOS 7.4 64 位",
"DeploymentSetGroupNo": 1,
"ImageId": "m-bp67acfmxazb4p****",
"VlanId": "10",
"ClusterId": "c-bp67acfmxazb4p****",
"GPUSpec": "NVIDIA V100",
"AutoReleaseTime": "2017-12-10T04:04Z",
"DeletionProtection": false,
"StoppedMode": "KeepCharging",
"GPUAmount": 4,
"HostName": "testHostName",
"InstanceId": "i-bp67acfmxazb4p****",
"InternetMaxBandwidthOut": 5,
"InternetMaxBandwidthIn": 50,
"InstanceType": "ecs.g5.large",
"InstanceChargeType": "PostPaid",
"RegionId": "cn-hangzhou",
"IoOptimized": true,
"StartTime": "2017-12-10T04:04Z",
"Cpu": 8,
"LocalStorageAmount": 2,
"ExpiredTime": "2017-12-10T04:04Z",
"ResourceGroupId": "rg-bp67acfmxazb4p****",
"InternetChargeType": "PayByTraffic",
"ZoneId": "cn-hangzhou-g",
"Recyclable": false,
"ISP": "null",
"CreditSpecification": "Standard",
"InstanceTypeFamily": "ecs.g5",
"OSType": "linux",
"NetworkInterfaces": {
"NetworkInterface": [
{
"Type": "Primary",
"MacAddress": "00:16:3e:32:b4:**",
"PrimaryIpAddress": "172.17.**.***",
"NetworkInterfaceId": "eni-2zeh9atclduxvf1z****",
"PrivateIpSets": {
"PrivateIpSet": [
{
"PrivateIpAddress": "172.17.**.**",
"Primary": true,
"PrivateDnsName": "dnsTestName"
}
]
},
"Ipv6Sets": {
"Ipv6Set": [
{
"Ipv6Address": "2408:4321:180:1701:94c7:bc38:3bfa:***"
}
]
},
"Ipv4PrefixSets": {
"Ipv4PrefixSet": [
{
"Ipv4Prefix": "192.168.*.*/28"
}
]
},
"Ipv6PrefixSets": {
"Ipv6PrefixSet": [
{
"Ipv6Prefix": "2001:1111:*:*::/80"
}
]
}
}
]
},
"OperationLocks": {
"LockReason": [
{
"LockMsg": "The specified instance is locked due to financial reason.",
"LockReason": "Recycling"
}
]
},
"Tags": {
"Tag": [
{
"TagValue": "TestValue",
"TagKey": "TestKey"
}
]
},
"RdmaIpAddress": {
"IpAddress": [
"10.10.10.102"
]
},
"SecurityGroupIds": {
"SecurityGroupId": [
"sg-bp67acfmxazb4p****"
]
},
"PublicIpAddress": {
"IpAddress": [
"121.40.**.**"
]
},
"InnerIpAddress": {
"IpAddress": [
"10.170.**.**"
]
},
"VpcAttributes": {
"VpcId": "vpc-2zeuphj08tt7q3brd****",
"NatIpAddress": "172.17.**.**",
"VSwitchId": "vsw-2zeh0r1pabwtg6wcs****",
"PrivateIpAddress": {
"IpAddress": [
"172.17.**.**"
]
}
},
"EipAddress": {
"IsSupportUnassociate": true,
"InternetChargeType": "PayByTraffic",
"IpAddress": "42.112.**.**",
"Bandwidth": 5,
"AllocationId": "eip-2ze88m67qx5z****"
},
"HibernationOptions": {
"Configured": false
},
"DedicatedHostAttribute": {
"DedicatedHostId": "dh-bp67acfmxazb4p****",
"DedicatedHostName": "testDedicatedHostName",
"DedicatedHostClusterId": "dc-bp67acfmxazb4h****"
},
"EcsCapacityReservationAttr": {
"CapacityReservationPreference": "cr-bp67acfmxazb4p****",
"CapacityReservationId": "cr-bp67acfmxazb4p****"
},
"DedicatedInstanceAttribute": {
"Affinity": "default",
"Tenancy": "default"
},
"CpuOptions": {
"Numa": "null",
"CoreCount": 2,
"ThreadsPerCore": 4,
"TopologyType": "DiscreteCoreToHTMapping"
},
"MetadataOptions": {
"HttpEndpoint": "enabled",
"HttpPutResponseHopLimit": 0,
"HttpTokens": "optional"
},
"ImageOptions": {
"LoginAsNonRoot": false,
"CurrentOSNVMeSupported": true
},
"SpotInterruptionBehavior": "Terminate",
"PrivateDnsNameOptions": {
"EnableInstanceIdDnsARecord": false,
"EnableInstanceIdDnsAAAARecord": false,
"EnableIpDnsARecord": true,
"EnableIpDnsPtrRecord": true,
"HostnameType": "Custom"
}
}
]
}
}错误码
| HTTP status code | 错误码 | 错误信息 | 描述 |
|---|---|---|---|
| 400 | InvalidTag.Mismatch | The specified Tag.n.Key and Tag.n.Value are not match. | 指定的 Tag.N.Key 和 Tag.N.Value 不匹配。 |
| 400 | InvalidTagCount | The specified tags are beyond the permitted range. | 指定的标记超出取值范围。 |
| 400 | InvalidHpcClusterId.NotFound | The specified HpcClusterId is not found. | 指定的参数 HpcClusterId 不存在。 |
| 400 | InvalidHpcClusterId.Creating | The specified HpcClusterId is creating. | 指定的 HPC 集群正在创建中。 |
| 400 | InternalError | The request processing has failed due to some unknown error, exception or failure. | 内部错误，请重试。 |
| 404 | InvalidInstanceChargeType.NotFound | The InstanceChargeType does not exist in our records. | 指定的实例计费方式不存在。 |
| 404 | InvalidInternetChargeType.ValueNotSupported | The specified InternetChargeType is not valid. | 暂不支持指定的网络付费类型的实例，请确认相关参数是否正确。 |
| 404 | InvalidLockReason.NotFound | The specified LockReason is not found. | 所指定的锁定原因不存在 |
| 404 | InvalidFilterKey.NotFound | Invalid filter.%s. | - |
| 404 | InvalidFilterValue | Invalid filter.%s. | - |
| 404 | InvalidNetworkType.NotFound | The specified InstanceNetworkType is not found. | - |
| 404 | InvalidStatus.NotFound | The specified Status is not found. | 指定的资源状态不存在。 |
访问错误中心查看更多错误码。
变更历史
| 变更时间 | 变更内容概要 | 操作 |
|---|---|---|
| 2024-10-30 | OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更 | 查看变更详情 |
| 2024-08-08 | OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更 | 查看变更详情 |
| 2023-12-14 | OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更 | 查看变更详情 |
| 2023-12-11 | OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更 | 查看变更详情 |
| 2021-12-13 | OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更 | 查看变更详情 |
| 2021-05-20 | OpenAPI 去除了 deprecated 标记、OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |