DescribeInstances

最近更新时间：2023.09.08 16:33:06

首次发布时间：2021.07.31 07:48:16

调用 DescribeInstances 接口查询实例信息。

说明

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

请求参数

名称	类型	是否必填	示例值	描述
Action	String	是	DescribeInstances	要执行的操作，取值：DescribeInstances。
Version	String	是	2020-04-01	API的版本，取值：2020-04-01。
InstanceIds.N	String	否	InstanceIds.1=i-3ti9101aju3vj0****&InstanceIds.2= i-3tiegs1y963vj0****	实例ID，最多支持100个ID。参数 - N：表示实例的序号。多个Instance ID之间用&分隔。
InstanceName	String	否	instance-test	实例的名称，支持关键字模糊查询。
ZoneId	String	否	cn-beijing-a	实例所属可用区ID，您可以调用DescribeZones查询一个地域下的可用区信息。
VpcId	String	否	vpc-3thbinq64t4bwb******	私有网络ID，您可以调用DescribeVpcs查询满足条件的私有网络。
Status	String	否	RUNNING	实例的状态，取值： CREATING：创建中 RUNNING：运行中 STOPPING：停止中 STOPPED：已停止 REBOOTING: 重启中 STARTING：启动中 REBUILDING：重装中 RESIZING：更配中 ERROR：错误 DELETING：删除中
PrimaryIpAddress	String	否	172.16.XX.XX	实例的私网IP地址，例如主网卡或辅助网卡IP地址。
NextToken	String	否	-	分页查询凭证，用于标记分页的位置，初次调用该接口时无需设置。下次查询时，取值为上一次API调用返回的`NextToken`参数值。
MaxResults	Integer	否	10	分页查询时设置的每页行数。最大值：100 默认值：10
HpcClusterId	String	否	hpcCluster-3tean8ni5m3vj0******	当查询高性能计算GPU型实例时，可以指定高性能计算集群ID。
KeyPairName	String	否	kp-test-123	密钥对的名称。
InstanceChargeType	String	否	PostPaid	实例的计费方式，取值： PostPaid：按量计费 PrePaid：包年包月
InstanceTypeIds.N	String	否	InstanceTypeIds.1=ecs.g2i.2xlarge&InstanceTypeIds.2=ecs.c2i.2xlarge	根据规格过滤实例，最多支持100个实例规格。参数 - N：表示实例的序号。多个实例规格之间用&分隔。
InstanceTypeFamilies.N	String	否	InstanceTypeFamilies.1=ecs.g2i&InstanceTypeFamilies.2=ecs.c2i	根据规格族过滤实例，最多支持100个实例规格族。参数 - N：表示实例的序号。多个实例规格族之间用&分隔。
ProjectName	String	否	project_a	资源所属项目，一个资源只能归属于一个项目。只能包含字母、数字、下划线“_”、点“.”和中划线“-”。长度限制在64个字符以内。
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`。不传则表示查询同一标签键下的所有标签值。传入空字符串时，表示查询标签值为空的标签。
DeploymentSetIds.N	String	否	DeploymentSetIds.1=dps-yc1o9aahks5m57nk**&DeploymentSetIds.2=dps-ybr1vulgy87grbt6**	使用部署集ID，查询对应部署集内的实例。参数 - N：表示部署集的序号，取值范围：1～100。多个 DeploymentSetId之间用&分隔。
DeploymentSetGroupNumbers.N	String	否	DeploymentSetGroupNumbers.1=1&DeploymentSetGroupNumbers.2=2	使用部署集组号，查询对应部署集组内的实例。参数 - N：表示部署集组的序号，取值范围：1～3。多个DeploymentSetGroupNumber之间用&分隔。说明部署集组高可用策略正在邀测中，如需试用，请提交工单或联系客户经理申请。
DedicatedHostId	String	否	dh-3tigy72q3u3vj0x2****	专有宿主机ID。您可以调用DescribeDedicatedHosts接口查询专有宿主机列表。
DedicatedHostClusterId	String	否	dc-ycle6b76kgv2wrsm****	专有宿主机集群ID。您可以调用DescribeDedicatedHostClusters接口查询宿主机集群ID。

返回数据

名称	类型	示例值	描述
Instances	Array of Struct	-	符合条件的实例信息。具体请参见下表 “ Instance结构 ”。
NextToken	String	bHpwdXJja2RxemU1eG5sb3NzdGcW1-RCEq******	本次调用返回的查询凭证值，返回为空表示没有下一页。

Instance结构

名称	类型	示例值	描述
CreatedAt	String	2021-06-28T18:29:38+08:00	创建时间。
UpdatedAt	String	2021-06-29T18:11:46+08:00	更新时间。
InstanceId	String	i-3ti9101aju3vj0******	实例ID。
ZoneId	String	cn-beijing-a	可用区ID。
ImageId	String	image-3tefr6wgx63vj0******	镜像ID。
Status	String	RUNNING	实例的状态。
InstanceName	String	instance-test	实例名称。
Description	String	用于测试的云服务器实例	实例描述。
Hostname	String	instance-host-name	实例主机名。
VpcId	String	vpc-3thbinq64t4bwb******	私有网络ID。
InstanceTypeId	String	ecs.c2i.xlarge	实例规格ID。
Cpus	Integer	4	CPU数量。
MemorySize	Integer	32768	内存大小，单位：MiB。
OsName	String	CentOS 7.6 64位	镜像操作系统的名称。
OsType	String	Linux	操作系统类型： Linux Windows
NetworkInterfaces	Array of Struct	-	实例挂载的网卡信息。具体请参见下表“ NetworkInterface结构 ”。
RdmaIpAddresses	List	["198.18.xx.xx","198.18.xx.xx"]	当查询高性能计算GPU型实例时，列表形式返回各网卡的RDMA IP地址。
KeyPairName	String	kp-test-123	密钥对名称。
KeyPairId	String	kp-3tgh3ifp8j44kd******	密钥对ID。
SpotStrategy	String	NoSpot	按量计费的抢占式策略，取值： NoSpot（默认）：正常按量计费实例。 SpotAsPriceGo：系统自动出价，跟随当前市场实际价格的抢占式实例。 SpotWithPriceLimit：设置出价上限的抢占式实例。
SpotPriceLimit	Float32	0.78	抢占式实例的每小时最高价格，支持最大3位小数。说明仅当`SpotStrategy=SpotWithPriceLimit`时，返回该参数。
DeploymentSetId	String	dps-yc1o9aahks5m57nk****	实例所属部署集ID。
DeploymentSetGroupNumber	Integer	2	部署集组序号。
StoppedMode	String	KeepCharging	实例是否启用了节省停机功能，取值： KeepCharging：普通停机模式，停机后继续收费，且为您保留相关资源。 StopCharging：节省停机模式。节省停机功能正在邀测中，如需试用，请提交工单或联系客户经理申请。仅部分实例支持节省停机模式，详情请参见节省停机模式说明。停机后，将释放vCPU、内存等计算资源；所挂载的云盘、公网IP和带宽(固定带宽模式)将被保留并继续计费。停机后再次启动实例，将重新创建vCPU、内存等资源，如果实例所在地域库存不足，将启动失败。私网IP地址及实例停机前已绑定的公网IP地址，在实例重启后仍保持不变。 NotApplicable：表示本实例不支持节省停机功能。
InstanceChargeType	String	PostPaid	实例的计费方式，取值： PostPaid：按量计费 PrePaid：包年包月
ExpiredAt	String	2200-01-01T00:00:00+08:00	实例的过期时间，仅`InstanceChargeType=PrePaid`时返回。
Uuid	String	4f35e8f7-f549-5c55-9531-5f43ca78****	实例的唯一标识符，该信息不随实例状态而改变。
EipAddress	Struct	-	实例绑定的公网IP地址列表，具体请参见下表“ EipAddress结构 ”
LocalVolumes	Array of Struct	-	实例对应的本地盘配置信息，具体请参见下表“ LocalVolume结构 ”。
ProjectName	String	project_a	资源所属项目。
CpuOptions	Array of Struct	-	CPU配置详情，具体请参见下表“ CpuOptions结构 ”。
Tags	Array of Struct	-	资源的标签信息，具体请参见下表“ Tag结构 ”。
Placement	Array of Struct	-	专有宿主机实例信息，具体请参见下表“ Placement 结构 ”。

NetworkInterface结构

名称	类型	示例值	描述
NetworkInterfaceId	String	eni-3tiu4lmhwq4e8i******	网卡ID。
VpcId	String	vpc-3thbinq64t4bwb******	私有网络ID。
SubnetId	String	subnet-3tisodmzai4e8i******	子网ID。
PrimaryIpAddress	String	172.16.xx.xx	私网IP地址。
Type	String	primary	网卡属性，取值： primary：主网卡 secondary：辅助网卡
MacAddress	String	00:16:3e:5b: :	MAC地址。

EipAddress结构

名称	类型	示例值	描述
AllocationId	String	eip-2749d8a20h4hs7fap8taa****	公网IP的ID。

LocalVolume结构

名称	类型	示例值	描述
VolumeType	String	LOCAL_SSD	本地盘类型，取值： LOCAL_SSD：SSD本地盘 LOCAL_HDD：HDD本地盘
Size	Integer	200	实例挂载的本地盘的单盘容量，单位GiB。
Count	Integer	4	实例挂载的本地盘数量。

名称

类型

示例值

描述

VolumeType

String

LOCAL_SSD

本地盘类型，取值：

LOCAL_SSD：SSD本地盘
LOCAL_HDD：HDD本地盘

Size

Integer

200

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

Count

Integer

实例挂载的本地盘数量。

CpuOptions结构

名称	类型	示例值	描述
CoreCount	Integer	4	CPU物理核心数。
ThreadsPerCore	Integer	2	CPU每核线程数，表示CPU是否开启超线程。取值： 1：关闭超线程 2：打开超线程 vCPU数量=CPU物理核心数*每核线程数

名称

类型

示例值

描述

CoreCount

Integer

CPU物理核心数。

ThreadsPerCore

Integer

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

1：关闭超线程
2：打开超线程

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

Tag结构

名称	类型	示例值	描述
Key	String	k1	实例的标签键。
Value	String	v1	实例的标签值。

Placement 结构

名称	类型	示例值	描述
Placement.Affinity	String	Default	专有宿主机实例是否与专有宿主机关联，取值： Default（默认）：不关联专有宿主机。启用节省停机模式的实例重新启动时，若原专有宿主机资源不足，可迁移至自动部署资源池中的其它专有宿主机上。 Host：关联专有宿主机。启用节省停机模式的实例重新启动时，仍会部署在原宿主机上。
Placement.DedicatedHostId	String	dh-bp67acfmxazb4p****	实例所在的专有宿主机ID。
Placement.Tenancy	String	Default	是否在专有宿主机上创建实例，取值： Default（默认）：创建普通云服务器实例。 Host：创建专有宿主机实例。若您不指定`DedicatedHostId`，则由系统自动选择专有宿主机放置实例。
DedicatedHostClusterId	String	dc-ycle6b76kgv2wrsm****	实例所在的专有宿主机集群ID。

请求示例

GET /?Action=DescribeInstances&Version=2020-04-01&InstanceIds.1=i-3ti9101aju3vj0****** HTTP/1.1
Host: open.volcengineapi.com
Region: cn-beijing
Service: ecs

返回示例

{
    "ResponseMetadata": {
        "RequestId": "2021110417394001022514606307D7****",
        "Action": "DescribeInstances",
        "Version": "2020-04-01",
        "Service": "ecs",
        "Region": "cn-beijing"
    },
    "Result": {
        "Instances": [{
            "CreatedAt": "2021-06-28T18:29:38+08:00",
            "UpdatedAt": "2021-06-29T18:11:46+08:00",
            "InstanceId": "i-3tiegs1y963vj0x0****",
            "ZoneId": "cn-beijing-a",
            "ImageId": "image-3ti94y52ui3vj0wt****",
            "Status": "RUNNING",
            "InstanceName": "sh-testh",
            "Description": "API-create",
            "Hostname": "sh",
            "VpcId": "vpc-3thwbkvycq3vj0x2****",
            "InstanceTypeId": "ecs.c2i.xlarge",
            "Cpus": 4,
            "MemorySize": 8192,
            "OsName": "Windows Server 2012 R2 Datacenter Edition 64-bit Chinese",
            "OsType": "Windows",
            "NetworkInterfaces": [{
                    "NetworkInterfaceId": "eni-3tirof3ove3vj0x1****",
                    "VpcId": "vpc-3thwbkvycq3vj0x2****",
                    "SubnetId": "subnet-3thwbl2z6y3vj0x2****",
                    "PrimaryIpAddress": "192.168.**.**",
                    "Type": "primary",
                    "MacAddress": "00:16:3e:79:**:**"
                },
                {
                    "NetworkInterfaceId": "eni-3ti7147rmy3vj0wt****",
                    "VpcId": "vpc-3thwbkvycq3vj0x2****",
                    "SubnetId": "subnet-3thwbl2z6y3vj0x2****",
                    "PrimaryIpAddress": "192.168.**.**",
                    "Type": "secondary",
                    "MacAddress": "00:16:3e:22:**:**"
                }
            ],
            "RdmaIpAddresses": [],
            "KeyPairName": "",
            "KeyPairId": "kp-ybqcopwrdwl8j1******",
            "InstanceChargeType": "PostPaid",
            "StoppedMode": "KeepCharging",
            "SpotStrategy": "NoSpot",
            "DeploymentSetId": "dps-yc1o9aahks5m57nk****",           
            "EipAddress": {
                "AllocationId": "eip-2749d8a20h4hs7fap8taa****"
                },
            "ExpiredAt": "",
            "Uuid": "4f35e8f7-f549-5c55-9531-5f43ca78****",
            "LocalVolumes": [], 
            "Tags": [ 
                {
                    "Key": "k1",
                    "Value": "v1"
                }
            ],
            "CpuOptions": {
                "CoreCount": "2",
                "ThreadsPerCore": "2"
            }
        ],    
        "NextToken": ""
    }
}

错误码

HttpCode	错误码	错误信息	描述
400	InvalidArgument	The specified argument is invalid.	指定的参数不合法。
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.MaximumTagFilterKeys	You've reached the limit on the number of TagFilterKeys that you can set.	指定的标签键超过最大限制。
400	LimitExceeded.MaximumTagFilterValues	You've reached the limit on the number of TagFilterValues that you can set.	指定的标签值超过最大限制。
400	InvalidTagFilterKey.Malformed	The specified TagFilterKey is malformed.	指定的标签键不合法。
400	InvalidTagFilterValue.Malformed	The specified TagFilterValue is malformed.	指定的标签值不合法。
400	LimitExceeded.MaximumTagFilterResults	You've reached the limit on the number of resources that you can describe by TagFilters.	通过标签过滤出的资源数量超过上限。
400	LimitExceeded.MaximumDeploymentSetIds	You've reached the limit on the number of DeploymentSetIds that you can set.	指定的部署集数量超过最大限制。
400	LimitExceeded.MaximumDeploymentSetGroupNumbers	You've reached the limit on the number of DeploymentSetGroupNumbers that you can set.	指定的部署集组数量超过最大限制。
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.	内部错误，请重试。如果多次尝试失败，请提交工单。

请求参数

返回数据

Instance结构

请求示例

返回示例

错误码

云服务器

DescribeInstances

请求参数

返回数据

Instance结构

NetworkInterface结构

EipAddress结构

LocalVolume结构

CpuOptions结构

Tag结构

Placement 结构

请求示例

返回示例

错误码