调用 DescribeInstances 接口获取实例信息。

注意事项

调用该接口时，使用TagFilters.N.Key和TagFilters.N.Values.N查询到的实例数量不能超过1000个。若超过1000个，请使用DesribeTags接口进行查询。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Action string 必选示例值：DescribeInstances

要执行的操作，取值：DescribeInstances。

Version string 必选示例值：2020-04-01

API的版本，取值：2020-04-01。

AffinityGroupIds.N string[] 可选示例值：AffinityGroupIds.1=affinityGroup-ydp80pygaoujldck****&AffinityGroupIds.2=affinityGroup-ydp7hq2wowujldck****

亲和组ID，最多支持100个。

参数 - N：表示亲和组的序号。

多个ID之间用&分隔。

DedicatedHostClusterId string 可选示例值：dc-ycle6b76kgv2wrsm****

专有宿主机集群ID。

您可以调用DescribeDedicatedHostClusters接口查询宿主机集群ID。

DedicatedHostId string 可选示例值：dh-3tigy72q3u3vj0x2****

专有宿主机ID。

您可以调用DescribeDedicatedHosts接口查询专有宿主机列表。

DeploymentSetGroupNumbers.N integer[] 可选示例值：DeploymentSetGroupNumbers.1=1&DeploymentSetGroupNumbers.2=2

使用部署集组号，查询对应部署集组内的实例。

参数 - N：表示部署集组的序号，取值范围：1～7。

多个DeploymentSetGroupNumber之间用&分隔。

DeploymentSetIds.N string[] 可选示例值：DeploymentSetIds.1=dps-yc1o9aahks5m57nk****&DeploymentSetIds.2=dps-ybr1vulgy87grbt6****

使用部署集ID，查询对应部署集内的实例。

参数 - N：表示部署集的序号，取值范围：1～100。

多个 DeploymentSetId之间用&分隔。

EipAddresses.N string[] 可选示例值：EipAddresses.1=12.XX.XX.89&EipAddresses.2=12.XX.XX.35

公网IP地址，最多支持100个。您可以调用DescribeEipAddresses接口查询公网IP地址。

参数 - N：表示公网IP地址的序号。

多个公网IP的IP地址之间用&分隔。

HpcClusterId string 可选示例值：hpcCluster-3tean8ni5m3vj0wz****

当查询高性能计算GPU型实例时，可以指定高性能计算集群ID。

InstanceChargeType string 可选示例值：PostPaid

实例的计费方式，取值：

PostPaid：按量计费

PrePaid：包年包月

InstanceIds.N string[] 可选示例值：InstanceIds.1=i-3ti9101aju3vj0******&InstanceIds.2=i-3tiegs1y963vj0******

实例ID，最多支持100个。

参数 - N：表示实例的序号。

多个Instance ID之间用&分隔。

InstanceName string 可选示例值：instance-test

实例的名称，支持关键字模糊查询。

InstanceTypeFamilies.N string[] 可选示例值：InstanceTypeFamilies.1=ecs.g2i&InstanceTypeFamilies.2=ecs.c2i

根据规格族过滤实例，最多支持100个实例规格族。

参数 - N：表示实例的序号。

多个实例规格族之间用&分隔。

InstanceTypeIds.N string[] 可选示例值：InstanceTypeIds.1=ecs.g2i.2xlarge&InstanceTypeIds.2=ecs.c2i.2xlarge

根据规格过滤实例，最多支持100个实例规格。

参数 - N：表示实例的序号。

多个实例规格之间用&分隔。

Ipv6Addresses.N string[] 可选示例值：Ipv6Addresses.1=2406:d440:103:5f00:a4a2:cbe2:efa0:****

实例的IPv6地址。

参数 -N：表示IPv6地址的序号，取值范围：1～100。

多个IPv6地址之间用&分隔。

说明

为网卡分配IPv6地址的功能正在邀测中，暂仅支持完成企业认证的账号申请试用，如需试用，请联系客户经理。

KeyPairName string 可选示例值：kp-test-123

密钥对的名称。

MaxResults integer 可选示例值：10

分页查询时设置的每页行数。

最大值：100

默认值：10

NextToken string 可选示例值：--

分页查询凭证，用于标记分页的位置，初次调用该接口时无需设置。下次查询时，取值为上一次API调用返回的NextToken参数值。

PrimaryIpAddress string 可选示例值：172.16.XX.XX

实例的私网IP地址，例如主网卡或辅助网卡IP地址。

ProjectName string 可选示例值：project_a

资源所属项目，一个资源只能归属于一个项目。

只能包含字母、数字、下划线“_”、点“.”和中划线“-”。

长度限制在64个字符以内。

ScheduledInstanceId string 可选示例值：esi-ycmfqs85zrm0tqlp****

弹性预约单ID。

您可以调用DescribeScheduledInstances接口查询弹性预约单ID。

Status string 可选示例值：RUNNING

实例的状态，取值：

CREATING：创建中

RUNNING：运行中

STOPPING：停止中

STOPPED：已停止

REBOOTING: 重启中

STARTING：启动中

REBUILDING：重装中

RESIZING：更配中

ERROR：错误

DELETING：删除中

TagFilters.N.Key string[] 可选示例值：TagFilters.1.Key=k1

根据标签查询资源时指定的标签键。

参数 - N：表示标签键的序号，取值范围：1～10。

多个标签键之间用&分隔。

不允许重复。

TagFilters.N.Values.N string[] 可选示例值：TagFilters.1.Values.1=v1&TagFilters.1.Values.2=v2

根据标签查询资源时指定的标签值。

第一个N：表示标签键的序号，取值范围：1～10。

第二个N：表示标签值的序号，取值范围：1～3，即同一标签键最多支持同时查询3个标签值。

多个标签值之间用&分隔。

说明

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

不传则表示查询同一标签键下的所有标签值。

传入空字符串时，表示查询标签值为空的标签。

VpcId string 可选示例值：vpc-3thbinq64t4bwbha****

私有网络ID。

您可以调用DescribeVpcs查询满足条件的私有网络。

ZoneId string 可选示例值：cn-beijing-a

实例所属可用区ID。

您可以调用DescribeZones查询一个地域下的可用区信息。

返回参数

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

Instances object[] 示例值：--

符合条件的实例信息。

AffinityGroupId string 示例值：affinityGroup-ydp80pygaoujldck****

亲和组ID。

CpuOptions object 示例值：--

CPU配置详情。

TopologyType string 示例值：DiscreteCoreToHTMapping

CPU拓扑模式。取值：

ContinuousCoreToHTMapping：HT连续模式。

DiscreteCoreToHTMapping：HT离散模式。

CoreCount integer 示例值：4

CPU物理核心数。

ThreadsPerCore integer 示例值：2

CPU每核线程数，表示CPU是否开启超线程。

取值：

1：关闭超线程

2：打开超线程

vCPU数量=CPU物理核心数*每核线程数

Cpus integer 示例值：4

CPU数量。

CreatedAt string 示例值：2021-06-28T18:29:38+08:00

创建时间。

DeletionProtection boolean 示例值：true

实例删除保护属性，指定是否支持通过控制台或API删除实例。取值：

true：开启实例删除保护。

false：关闭实例删除保护。

DeploymentSetGroupNumber integer 示例值：2

部署集组序号。

DeploymentSetId string 示例值：dps-yc1o9aahks5m57nk****

实例所属部署集ID。

Description string 示例值：ECS instance for testing.

实例描述。

EipAddress object 示例值：--

实例绑定的公网IP地址列表。

AllocationId string 示例值：eip-2749d8a20h4hs7fap8taa****

公网IP的ID。

IpAddress string 示例值：101.126.XX.XX

公网IP地址。

ElasticScheduledInstanceType string 示例值：NoEsi

弹性预约实例类型，取值：

NoEsi：非弹性预约实例。

Esi：弹性预约实例。

Segmented：弹性预约实例-时段型。

EnableJumboFrame boolean 示例值：false

实例是否开启巨型帧。取值：

true：已开启。

false：未开启。

ExpiredAt string 示例值：2200-01-01T00:00:00+08:00

实例的过期时间。

仅InstanceChargeType取值为PrePaid时返回。

Hostname string 示例值：instance-host-name

实例主机名。

HpcClusterId string 示例值：hpcCluster-3tean8ni5m3vj0******

高性能计算集群ID。

ImageId string 示例值：image-3tefr6wgx63vj0******

镜像ID。

InstanceChargeType string 示例值：PostPaid

实例的计费方式，取值：

PostPaid：按量计费

PrePaid：包年包月

InstanceId string 示例值：i-3ti9101aju3vj0******

实例ID。

InstanceName string 示例值：instance-test

实例名称。

InstanceTypeId string 示例值：ecs.c2i.xlarge

实例规格。

KeyPairId string 示例值：kp-3tgh3ifp8j44kd******

密钥对ID。

KeyPairName string 示例值：kp-test-123

密钥对名称。

LocalVolumes object[] 示例值：--

实例对应的本地盘配置信息。

Count integer 示例值：4

实例挂载的本地盘数量。

Size integer 示例值：200

实例挂载的本地盘的单盘容量，单位GiB。

VolumeType string 示例值：LOCAL_SSD

本地盘类型，取值：

LOCAL_SSD：SSD本地盘

LOCAL_HDD：HDD本地盘

MemorySize integer 示例值：32768

内存大小，单位：MiB。

MetadataOptions object 示例值：--

实例元数据选项集合。

HttpTokens string 示例值：optional

实例元数据的访问模式，是否强制使用加固模式。取值:

optional：不强制使用（兼容模式）。

required：强制使用（仅加固模式）。

说明

关于元数据的查看方式以及支持查看的元数据项，请参见查看实例元数据。

NetworkInterfaces object[] 示例值：--

实例挂载的网卡信息。

Ipv6Addresses string[] 示例值：["2408::153:3921:XX:XX:7b12:1c5f", "2408:4008:2cf:XX:XX:dd1e:2a22:5ddf"]

网卡的IPv6地址。

MacAddress string 示例值：00:16:3e:5b:** :**

MAC地址。

NetworkInterfaceId string 示例值：eni-3tiu4lmhwq4e8i******

网卡ID。

PrimaryIpAddress string 示例值：172.16.XX.XX

私网IP地址。

SecurityGroupIds string[] 示例值：["sg-mj48avnqyio05smt1a******","sg-3cj59ih2v9hj46c6rr******"]

网卡关联的安全组ID。

SubnetId string 示例值：subnet-3tisodmzai4e8i******

子网ID。

Type string 示例值：primary

网卡属性，取值：

primary：主网卡

secondary：辅助网卡

VpcId string 示例值：vpc-3thbinq64t4bwb******

私有网络ID。

OsName string 示例值：CentOS 7.6 64位

镜像操作系统的名称。

OsType string 示例值：Linux

操作系统类型：

Linux

Windows

Placement object 示例值：--

专有宿主机实例信息。

Affinity string 示例值：Default

针对节省停机模式的ECS实例，停止后会释放部分资源，本参数用于查看ECS实例重新启动时是否仍固定部署在原宿主机上。取值：

Host：启用节省停机模式的实例重新启动时，仍会部署在原宿主机上。

Default（默认）：启用节省停机模式的实例重新启动时，会优先迁移到支持自动部署的宿主机；若支持自动部署的宿主机资源不足，则在原宿主机上进行启动。

DedicatedHostClusterId string 示例值：dc-ycle6b76kgv2wrsm****

实例所在的专有宿主机集群ID。

DedicatedHostId string 示例值：dh-bp67acfmxazb4p****

实例所在的专有宿主机ID。

Tenancy string 示例值：Default

是否在专有宿主机上创建实例，取值：

Default（默认）：创建普通云服务器实例。

Host：创建专有宿主机实例。若您不指定DedicatedHostId，则由系统自动选择专有宿主机放置实例。

ProjectName string 示例值：project_a

资源所属项目，一个资源只能归属于一个项目。

只能包含字母、数字、下划线“_”、点“.”和中划线“-”。

长度限制在64个字符以内。

RdmaIpAddresses string[] 示例值：["198.18.xx.xx","198.18.xx.xx"]

当查询高性能计算GPU型实例时，列表形式返回各网卡的RDMA IP地址。

RdmaNetworkInterfaceDetails object[] 示例值：--

当查询高性能计算GPU型实例时，列表形式返回各网卡的信息。

该接口邀测中，如需试用，请联系客户经理申请。

Gateway string 示例值：26.xx.xx.46

网关地址。

Ip string 示例值：26.xx.xx.2

IP地址。

Mask string 示例值：255.xx.xx.254

子网掩码。

SwitchName string 示例值：HB****.VEGS0-0-01

交换机名称。

SwitchPort string 示例值：ethernet1a

交换机端口。

ScheduledInstanceId string 示例值：esi-ycmfqs85zrm0tqlp****

弹性预约单ID。

SpotPriceLimit float 示例值：0.78

抢占式实例的每小时最高价格，支持最大3位小数。

仅SpotStrategy取值为SpotWithPriceLimit时，返回该参数。

SpotStrategy string 示例值：NoSpot

按量计费的抢占式策略，取值：

NoSpot（默认）：正常按量计费实例。

SpotAsPriceGo：系统自动出价，跟随当前市场实际价格的抢占式实例。

SpotWithPriceLimit：设置出价上限的抢占式实例。

Status string 示例值：RUNNING

实例的状态。

StoppedMode string 示例值：KeepCharging

实例是否启用了节省停机功能，取值：

KeepCharging：普通停机模式，停机后继续收费，且为您保留相关资源。

StopCharging：节省停机模式。详情请参见按量计费节省停机模式说明。

NotApplicable：表示本实例不支持节省停机功能。

Tags object[] 示例值：--

资源的标签信息。

Key string 示例值：k1

实例的标签键。

Value string 示例值：v1

实例的标签值。

UpdatedAt string 示例值：2021-06-29T18:11:46+08:00

更新时间。

Uuid string 示例值：4f35e8f7-f549-5c55-9531-5f43ca78****

实例的唯一标识符，该信息不随实例状态而改变。

Volumes object[] 示例值：--

实例挂载的云盘信息。

VolumeId string 示例值：vol-3wbz8gzti84g6no9****

云盘ID。

VpcId string 示例值：vpc-3thbinq64t4bwb******

私有网络ID。

ZoneId string 示例值：cn-beijing-a

可用区ID。

NextToken string 示例值：bHpwdXJja2RxemU1eG5sb3NzdGcW1-RCEq******

本次调用返回的查询凭证值，返回为空表示该页为末页。

请求示例

返回示例

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
400	InvalidArgument	The specified argument is invalid.	指定的参数不合法。
400	InvalidCpuOptionsCoreCount.Malformed	The specified cpu options core count is malformed.	指定的CoreCount参数不合法。
400	InvalidCpuOptionsThreadsPerCore.Malformed	The specified cpu options threads per core is malformed.	指定的ThreadsPerCore参数不合法。
400	InvalidTagFilterKey.Malformed	The specified TagFilterKey is malformed.	指定的查询标签的键格式错误。
400	InvalidTagFilterValue.Malformed	The specified TagFilterValue is malformed.	指定的查询标签的值格式错误。
400	LimitExceeded.MaximumAffinityGroupIds	The number of specified AffinityGroupIds exceeds the maximum limit.	指定的AffinityGroupIds超过最大限制。
400	LimitExceeded.MaximumDeploymentSetGroupNumbers	You've reached the limit on the number of DeploymentSetGroupNumbers that you can set.	指定的DeploymentSetGroupNumbers数量超过最大限制。
400	LimitExceeded.MaximumDeploymentSetIds	You've reached the limit on the number of DeploymentSetIds that you can set.	指定的DeploymentSets数量超过最大限制。
400	LimitExceeded.MaximumEipAddresses	The number of specified EipAddresses exceeds the maximum limit.	指定的EipAddresses超过最大限制。
400	LimitExceeded.MaximumInstanceIds	You've reached the limit on the number of InstanceIds that you can set.	指定的InstanceIds数量超过最大限制。
400	LimitExceeded.MaximumInstanceTypeFamilies	You've reached the limit on the number of InstanceTypeFamilies that you can set.	指定的InstanceTypeFamilies数量超过最大限制。
400	LimitExceeded.MaximumInstanceTypeIds	You've reached the limit on the number of InstanceTypeIds that you can set.	指定的InstanceTypeIds数量超过最大限制。
400	LimitExceeded.MaximumIpv6Addresses	The number of specified Ipv6Addresses exceeds the maximum limit.	指定的Ipv6Addresses超过最大限制。
400	LimitExceeded.MaximumTagFilterKeys	You've reached the limit on the number of TagFilterKeys that you can set.	指定的查询标签键超出取值范围。
400	LimitExceeded.MaximumTagFilterResults	You've reached the limit on the number of resources that you can describe by TagFilters.	通过标签过滤出的资源数量超过上限。
400	LimitExceeded.MaximumTagFilterValues	You've reached the limit on the number of TagFilterValues that you can set.	指定的查询标签值超出取值范围。
400	LimitExceeded.PrimaryIpAddresses	You've reached the limit on the number of PrimaryIpAddresses that you can set.	指定的私网IP地址超过最大限制。
404	InvalidActionOrVersion	Could not find operation %s for version %s.	请求接口不存在。
404	InvalidProject.NotFound	The specified Project does not exist.	指定的Project不存在。
409	InvalidTagFilterKey.Conflict	The specified TagFilterKey already exists.	指定的过滤标签键已存在。
429	FlowLimitExceeded	You've reach the limit on request rate of resources.	您已超过资源请求限速。
500	InternalError	An internal error has occurred.	内部错误，请重试。如果多次尝试失败，请提交工单。

云服务器