云服务器
云服务器
文档指南
请输入
- 文档首页
云服务器云服务器ECSAPI参考实例DescribeInstances - 查询实例列表
复制全文
下载 pdfDescribeInstances - 查询实例列表
文档反馈
问问助手调用 DescribeInstances 接口获取实例信息。
注意事项
调试
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。
DedicatedHostId string 可选 示例值：dh-3tigy72q3u3vj0x2****
专有宿主机ID。
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
- 参数 - 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地址之间用&分隔。
说明
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。
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。
- 不传则表示查询同一标签键下的所有标签值。
- 传入空字符串时，表示查询标签值为空的标签。
返回参数
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******
本次调用返回的查询凭证值，返回为空表示该页为末页。
请求示例
GET /?Action=DescribeInstances&Version=2020-04-01&InstanceIds.1=i-3ti9101aju3vj0****** HTTP/1.1
Host: ecs.cn-beijing.volcengineapi.com
Region: cn-beijing
Service: ecs
返回示例
{
"ResponseMetadata": {
"RequestId": "20250220105008F21A3268CDC9D9A2****",
"Action": "DescribeInstances",
"Version": "2020-04-01",
"Service": "ecs",
"Region": "cn-beijing"
},
"Result": {
"Instances": [
{
"CreatedAt": "2025-02-19T14:43:45+08:00",
"UpdatedAt": "2025-02-19T14:43:53+08:00",
"ZoneId": "cn-beijing-b",
"ImageId": "image-38deuiek3bg6tehx****",
"Status": "RUNNING",
"InstanceName": "ECS-MwaP",
"Description": "",
"VpcId": "vpc-mj48apqnmcqo5smt1arf****",
"NetworkInterfaces": [
{
"NetworkInterfaceId": "eni-mimrg8yzp0jk5smt1axz****",
"VpcId": "vpc-mj48apqnmcqo5smt1arf****",
"SubnetId": "subnet-rr9k4pzqcb28v0x58k1****",
"PrimaryIpAddress": "192.168.**.**",
"Type": "primary",
"MacAddress": "00:16:3e:42:**:**",
"Ipv6Addresses": [],
"SecurityGroupIds": [
"sg-mj48avnqyio05smt1awh****"
]
}
],
"RdmaIpAddresses": [],
"RdmaNetworkInterfaceDetails": [
{
"Ip": "26.xx.xx.2",
"Mask": "255.xx.xx.254",
"Gateway": "26.xx.xx.46",
"SwitchName": "HB****.VEGS0-0-7",
"SwitchPort": "ethernet1a"
}
],
"HpcClusterId": "",
"KeyPairName": "**",
"KeyPairId": "kp-yd6njlvoj6ldcrkn****",
"StoppedMode": "NotApplicable",
"InstanceChargeType": "PostPaid",
"DeploymentSetId": "",
"Tags": [
{
"Key": "sys:tag:createdBy",
"Value": "IAMUser:3723****:****"
}
],
"Volumes": [
{
"VolumeId": "vol-3wbz8gzti84g6no9****"
}
],
"InstanceTypeId": "ecs.d2s.xlarge",
"ProjectName": "default",
"EipAddress": {
"IpAddress": "180.184.**.**",
"AllocationId": "eip-13fncoh4gd81s3n6nu5tn****"
},
"ExpiredAt": "2200-01-01T00:00:00+08:00",
"OsType": "Linux",
"OsName": "CentOS 6.9 64位",
"Cpus": 4,
"MemorySize": 16384,
"InstanceId": "i-ydpq4a603kwh2yov****",
"Hostname": "iv-ydpq4a603kwh2yov****",
"Uuid": "000c67b5-7da0-0000-000b-b79d02******",
"EnableJumboFrame": false,
"LocalVolumes": [
{
"VolumeType": "LOCAL_HDD",
"Size": 7452,
"Count": 2
}
],
"CpuOptions": {
"CoreCount": 2,
"ThreadsPerCore": 2
},
"DeletionProtection": true,
"SpotStrategy": "NoSpot",
"DeploymentSetGroupNumber": 0,
"Placement": {
"DedicatedHostId": "",
"Tenancy": "Default",
"Affinity": "Default",
"DedicatedHostClusterId": ""
},
"SpotPriceLimit": 0,
"ScheduledInstanceId": "",
"ElasticScheduledInstanceType": "NoEsi",
"AffinityGroupId": ""
}
]
}
}
错误码
最近更新时间：2026.07.10 15:41:47
这个页面对您有帮助吗？
有用
有用
无用
无用