接口功能介绍

该接口提供用户多台云主机信息查询功能，用户可以根据此接口的返回值得到多台云主机信息。该接口相较于/v4/ecs/list-instances提供更精简的云主机信息，拥有更高的查找效率
准备工作：
  构造请求：在调用前需要了解如何构造请求，详情查看构造请求
  认证鉴权：openapi请求需要进行加密调用，详细查看认证鉴权
注意事项：
  分页查询：当前查询结果以分页形式进行展示，单次查询最多显示50条数据
  匹配查找：可以通过部分字段进行匹配筛选数据，无符合条件的为空，在指定多台云主机ID的情况下，只返回匹配到的云主机信息。推荐每次使用单个条件查找

接口约束

无

URI

POST /v4/ecs/describe-instances

路径参数
无

Query参数
无

请求参数

请求头header参数
无

请求体body参数

参数	是否必填	参数类型	说明	示例	下级对象
regionID	是	String	资源池ID，您可以查看地域和可用区来了解资源池 获取： 查 资源池列表查询	bb9fdb42056f11eda1610242ac110002
azName	否	String	可用区名称，您可以查看地域和可用区来了解可用区 获取： 查 资源池可用区查询 注：查询结果中zoneList内返回存在可用区名称(即多可用区，本字段填写实际可用区名称)，若查询结果中zoneList为空（即为单可用区，本字段填写default）	cn-huadong1-jsnj1A-public-ctcloud
projectID	否	String	企业项目ID，企业项目管理服务提供统一的云资源按企业项目管理，以及企业项目内的资源管理，成员管理。您可以通过查看创建企业项目了解如何创建企业项目	0
pageNo	否	Integer	页码，取值范围：正整数（≥1），注：默认值为1	1
pageSize	否	Integer	每页记录数目，取值范围：[1, 50]，注：默认值为10	10
state	否	String	云主机状态，取值范围： active（开机）， shutoff（关机）， expired（已到期）， unsubscribed（包周期已退订）， freezing（已冻结）， shelve（节省关机） 注：该参数大小写不敏感（如active可填写为ACTIVE）	active
keyword	否	String	关键字，对部分参数进行模糊查询，包含：instanceName、displayName、instanceID、privateIP	ecs-888
instanceName	否	String	云主机名称，精准匹配	ecs-1
instanceIDList	否	String	云主机ID列表，多台使用英文逗号分割，您可以查看弹性云主机了解云主机的相关信息 获取： 创 创建一台按量付费或包年包月的云主机 创 批量创建按量付费或包年包月云主机	73f321ea-62ff-11ec-a8bc-005056898fe0,88f888ea-88ff-88ec-a8bc-888888888fe8
securityGroupID	否	String	安全组ID，模糊匹配，您可以查看安全组概述了解安全组相关信息 获取： 查 查询用户安全组列表 创 创建安全组	sg-tolywxbe1f
labelList	否	Array of Objects	标签信息列表		labelList

表 labelList

参数	是否必填	参数类型	说明	示例	下级对象
labelKey	是	String	标签键，长度限制1~32字符	test-key
labelValue	是	String	标签值，长度限制1~32字符	test-value

响应参数

参数	参数类型	说明	示例	下级对象
statusCode	Integer	返回状态码（800为成功，900为失败）	800
errorCode	String	错误码，为product.module.code三段式码	Openapi.PatternCheck.NotValid
error	String	错误码，为product.module.code三段式码	Openapi.PatternCheck.NotValid
message	String	失败时的错误描述，一般为英文描述	SUCCESS
description	String	失败时的错误描述，一般为中文描述	成功
returnObj	Object	成功时返回的数据		returnObj

表 returnObj

参数	参数类型	说明	示例	下级对象
currentCount	Integer	当前页记录数目	1
totalCount	Integer	总记录数	10
totalPage	Integer	总页数	1
results	Array of Objects	分页明细		results

表 results

参数	参数类型	说明	示例	下级对象
projectID	String	企业项目ID	0
azName	String	可用区名称	cn-huadong1-jsnj1A-public-ctcloud
azDisplayName	String	可用区展示名称	可用区1
attachedVolume	Array of Strings	云硬盘ID列表	["d36d4736-0724-429e-b7b6-dca67a2a0ef5", "b484565c-b5a0-4b30-85cd-3b674991aff0"]
addresses	Array of Objects	网络地址信息		addresses
instanceID	String	云主机ID	c5a7966a-88e7-362b-6e11-c2d8fbfc07ca
displayName	String	云主机显示名称	test-01
instanceName	String	云主机名称	test-01
osType	Integer	操作系统类型，取值范围： 1（linux）， 2（windows）， 3（redhat）， 4（ubuntu）， 5（centos）， 6（oracle）	5
instanceStatus	String	云主机状态，取值范围： backuping: 备份中， creating: 创建中， expired: 已到期， freezing: 已冻结， rebuild: 重装， restarting: 重启中， running: 运行中， starting: 开机中， stopped: 已关机， stopping: 关机中， error: 错误， snapshotting: 快照创建中， unsubscribed: 包周期已退订， unsubscribing: 包周期退订中。 更多云主机状态请通过状态枚举值查看云主机使用状态	running
expiredTime	String	到期时间	2023-04-19T09:37:53Z
createdTime	String	创建时间	2022-10-19T09:37:53Z
secGroupList	Array of Objects	安全组信息列表		secGroupList
vipInfoList	Array of Objects	虚拟IP信息列表		vipInfoList
affinityGroup	Object	云主机组信息		affinityGroup
image	Object	镜像信息		image
flavor	Object	云主机规格信息		flavor
onDemand	Boolean	付费方式，取值范围： true（按量付费）; false（包周期）	true
keypairName	String	密钥对名称	kp-test2
networkInfo	Array of Objects	网络信息		networkInfo
delegateName	String	委托名称，注：委托绑定目前仅支持多可用区类型资源池，非可用区资源池为空字符串	apiTest01
deletionProtection	Boolean	是否开启实例删除保护	true
instanceDescription	String	云主机描述信息	description_test_001

表 addresses

参数	参数类型	说明	示例	下级对象
vpcName	String	vpc名称	vpc-test3
addressList	Array of Objects	网络地址列表		addressList

表 secGroupList

参数	参数类型	说明	示例	下级对象
securityGroupID	String	安全组ID	sg-w3cn7d00a4
securityGroupName	String	安全组名称	Default-Security-Gr

表 vipInfoList

参数	参数类型	说明	示例	下级对象
vipID	String	虚拟IP的ID	havip-82g6jjhebo
vipAddress	String	虚拟IP地址	192.168.1.52
vipBindNicIP	String	虚拟IP绑定的网卡对应IPv4地址	192.168.1.104
vipBindNicIPv6	String	虚拟IP绑定的网卡对应IPv6地址	100:1:1ec:6600:fb6f:5428:c7e3:fa60
nicID	String	网卡ID	port-10s1q9v9xf

表 affinityGroup

参数	参数类型	说明	示例	下级对象
policy	String	云主机组策略	soft-affinity
affinityGroupName	String	云主机组名称	group-10274
affinityGroupID	String	云主机组ID	682c01af-1eaf-400b-570f-05734a00619d

表 image

参数	参数类型	说明	示例	下级对象
imageID	String	镜像ID	4e5f72c9-fa16-4ae6-b60e-11287edc934c
imageName	String	镜像名称	CentOS7.9 64位

表 flavor

参数	参数类型	说明	示例	下级对象
flavorID	String	规格ID	c5f17f9c-5cfd-9c87-72dd-152171c9002a
flavorName	String	规格名称	s7.medium.2
flavorCPU	Integer	VCPU	1
flavorRAM	Integer	内存	2048
gpuType	String	GPU类型，取值范围：T4、V100、V100S、A10、A100、atlas 300i pro、mlu370-s4，支持类型会随着功能升级增加	T4
gpuCount	Integer	GPU数目	1
gpuVendor	String	GPU名称	gpu-x
videoMemSize	Integer	显存大小	1

表 networkInfo

参数	参数类型	说明	示例	下级对象
subnetID	String	子网ID	subnet-0yy6yy2yyy
ipAddress	String	IP地址	192.168.0.62
boundType	Map of String	绑定类型	{}

表 addressList

参数	参数类型	说明	示例	下级对象
addr	String	IP地址	192.168.0.62
version	Integer	IP版本	4
type	String	网络类型，取值范围： fixed（内网）， floating（弹性公网）	fixed
isMaster	Boolean	是否为主网卡	true
macAddress	String	mac地址	fa:16:3e:50:ef:07

枚举参数

无

请求示例

请求url

无

请求头header

无

请求体body

示例1：指定每页记录数目，指定页云主机信息
华东1指定每页记录数目为3，查看第2页云主机信息
{
    "regionID": "bb9fdb42056f11eda1610242ac110002",
    "pageNo": 2,
    "pageSize": 3
}
示例2：在多可用区类型资源池，查看单个可用区下的云主机信息
华东1可用区2指定每页记录数目为5，查看第3页的云主机信息
{
    "regionID": "bb9fdb42056f11eda1610242ac110002",
    "azName": "cn-huadong1-jsnj1A-public-ctcloud",
    "pageNo": 3,
    "pageSize": 5
}
示例3：查看指定名称的云主机
在华东1资源池查询云主机名称为api-test01的云主机信息
{
    "regionID": "bb9fdb42056f11eda1610242ac110002",
    "instanceName": "api-test01"
}
示例4：筛选云主机状态查询云主机列表
查看华东1中开机的云主机
{
    "regionID": "bb9fdb42056f11eda1610242ac110002",
    "state": "active"
}
示例5：查看指定云主机ID的多个云主机
查看华东1中查找ID为c5a7966a-88e7-362b-6e11-c2d8fbfc07ca和adc614e0-e838-d73f-0618-a6d51d09070a的云主机信息
{
    "regionID": "bb9fdb42056f11eda1610242ac110002",
    "instanceIDList": "c5a7966a-88e7-362b-6e11-c2d8fbfc07ca,adc614e0-e838-d73f-0618-a6d51d09070a"
}
示例6：查找使用指定安全组的云主机
查找华东1中使用安全组ID为sg-tolywxbe1f的云主机（注：多可用区类型资源池中的securityGroupID通常为sg-开头，而非多可用类型资源池不是）
{
    "regionID": "bb9fdb42056f11eda1610242ac110002",
    "securityGroupID": "sg-tolywxbe1f"
}
示例7：查找指定企业项目下的云主机信息<br/>
查找在华东1资源池下，企业项目ID为6732237e53bc4591b0e67d750030ebe3的云主机信息
{
    "regionID": "bb9fdb42056f11eda1610242ac110002",
    "projectID": "6732237e53bc4591b0e67d750030ebe3"
}
示例8：指定标签键值对查找
查找在华东1资源池下标签键为test-key，标签值为test-value的云主机信息
{
    "regionID":"bb9fdb42056f11eda1610242ac110002",
    "labelList":[
        {
            "labelKey":"test-key",
            "labelValue":"test-value"
        }
    ]
}

响应示例

{
	"returnObj": {
		"currentCount": 1,
		"totalCount": 1,
		"totalPage": 1,
		"results": [{
			"azName": "cn-huadong1-jsnj1A-public-ctcloud",
			"azDisplayName": "可用区1",
			"expiredTime": null,
			"createdTime": "2023-05-18T06:00:08Z",
			"projectID": "0",
			"attachedVolume": ["59ce6a6b-9fab-4763-8e13-cbe732b8144a"],
			"instanceID": "197076df-f2e9-4710-bb35-3fcde950bbda",
			"displayName": "api-vm631048",
			"instanceName": "api-vm631048",
			"osType": 5,
			"instanceStatus": "running",
			"onDemand": true,
			"keypairName": "test-keypair",
			"addresses": [{
				"vpcName": "hy-1e6e",
				"addressList": [{
					"addr": "192.168.1.53",
					"version": 4,
					"type": "fixed",
                    "isMaster": true,
                    "macAddress": "fa:16:3e:ef:0e:88"
				}, {
					"addr": "192.168.1.254",
					"version": 4,
					"type": "fixed",
                    "isMaster": true,
                    "macAddress": "fa:16:3e:ef:0e:88"
				}]
			}],
			"secGroupList": [{
				"securityGroupName": "default",
				"securityGroupID": "b0db05af-f6b1-4b48-91eb-b293068ba919"
			}, {
				"securityGroupName": "default",
				"securityGroupID": "b0db05af-f6b1-4b48-91eb-b293068ba919"
			}],
			"vipInfoList": [],
			"networkInfo": [{
				"subnetID": "993bb7ba-d4f5-4cc5-851c-acf5e42bc1fa",
				"ipAddress": "192.168.1.53",
				"boundType": {}
			}, {
				"subnetID": "993bb7ba-d4f5-4cc5-851c-acf5e42bc1fa",
				"ipAddress": "192.168.1.53",
				"boundType": {}
			}],
			"affinityGroup": {
				"policy": "soft-affinity",
				"affinityGroupName": "group-10274",
				"affinityGroupID": "682c01af-1eaf-400b-570f-05734a00619d"
			},
			"image": {
				"imageID": "5678e781-d567-4e3d-8fdb-d2e6f41219a4",
				"imageName": "CentOS7.0"
			},
			"flavor": {
				"flavorID": "1259d696-f477-4658-b7f4-d6b8ced17ceb",
				"flavorName": "s2.small.1",
				"flavorCPU": 1,
				"flavorRAM": 1024,
				"gpuType": null,
				"gpuCount": null,
				"gpuVendor": null,
				"videoMemSize": null
			},
			"delegateInfo": {
              "delegateName": "apiTest01",
              "delegateCreateTime": "1693476767000"
            },
          "deletionProtection": true
		}]
	},
	"message": "SUCCESS",
	"description": "成功",
	"statusCode": 800
}

状态码

请参考 状态码

错误码

请参考 错误码