describeInstances
描述
查询一台或多台云主机实例的详细信息。
详细操作说明请参考帮助文档:查找实例
接口说明
- 使用
filters
过滤器进行条件筛选,每个 filter
之间的关系为逻辑与(AND)的关系。
- 如果使用子帐号查询,只会查询到该子帐号有权限的云主机实例。关于资源权限请参考 IAM概述。
- 单次查询最大可查询100条云主机实例数据。
- 尽量一次调用接口查询多条数据,不建议使用该批量查询接口一次查询一条数据,如果使用不当导致查询过于密集,可能导致网关触发限流。
- 由于该接口为
GET
方式请求,最终参数会转换为 URL
上的参数,但是 HTTP
协议下的 GET
请求参数长度是有大小限制的,使用者需要注意参数超长的问题。
请求方式
GET
请求地址
https://vm.jdcloud-api.com/v1/regions/{regionId}/instances
名称 |
类型 |
是否必需 |
示例值 |
描述 |
regionId |
String |
是 |
cn-north-1 |
地域ID。 |
请求参数
名称 |
类型 |
是否必选 |
示例值 |
描述 |
pageNumber |
Integer |
否 |
1 |
页码;默认为1。 |
pageSize |
Integer |
否 |
20 |
分页大小; 默认为20;取值范围[10, 100]。 |
filters |
Filter[ ] |
否 |
|
filters 中支持使用以下关键字进行过滤
instanceId : 云主机ID,精确匹配,支持多个
privateIpAddress : 云主机挂载的网卡内网主IP地址,模糊匹配,支持多个
az : 可用区,精确匹配,支持多个
vpcId : 私有网络ID,精确匹配,支持多个
status : 云主机状态,精确匹配,支持多个,参考 云主机状态
name : 云主机名称,模糊匹配,支持单个
imageId : 镜像ID,精确匹配,支持多个
networkInterfaceId : 弹性网卡ID,精确匹配,支持多个
subnetId : 子网ID,精确匹配,支持多个
agId : 使用可用组id,支持单个
faultDomain : 错误域,支持多个
dedicatedHostId : 专有宿主机ID,精确匹配,支持多个
dedicatedPoolId : 专有宿主机池ID,精确匹配,支持多个
instanceType : 实例规格,精确匹配,支持多个,可通过查询 DescribeInstanceTypes 接口获得实例规格
elasticIpAddress : 公网IP地址,精确匹配,支持单个。该条件会将公网IP转换成 networkInterfaceId 进行查询,所以与 networkInterfaceId 为或者的关系。
|
Filter
名称 |
类型 |
是否必选 |
示例值 |
描述 |
name |
String |
是 |
|
过滤条件的名称 |
operator |
String |
否 |
|
过滤条件的操作符,默认eq |
values |
String[ ] |
是 |
|
过滤条件的值 |
返回参数
名称 |
类型 |
示例值 |
描述 |
result |
Result |
|
响应结果。 |
requestId |
String |
c2hmmaan8w06w19qcdfuic4w03f7ft2d |
请求ID。 |
Result
名称 |
类型 |
示例值 |
描述 |
instances |
Instance[ ] |
|
云主机实例列表。 |
totalCount |
Number |
|
本次查询可匹配到的总记录数,使用者需要结合 pageNumber 和 pageSize 计算是否可以继续分页。 |
Instance
名称 |
类型 |
示例值 |
描述 |
instanceId |
String |
i-eumm****d6 |
云主机ID。 |
instanceName |
String |
test |
云主机名称。 |
hostname |
String |
|
云主机hostname。 |
instanceType |
String |
g.n2.medium |
实例规格。 |
vpcId |
String |
vpc-z9r3****p8 |
主网卡所属VPC的ID。 |
subnetId |
String |
subnet-c2p3****9o |
主网卡所属子网的ID。 |
privateIpAddress |
String |
10.0.0.3 |
主网卡主内网IP地址。 |
elasticIpId |
String |
fip-z1z1****ja |
主网卡主IP绑定弹性IP的ID。 |
elasticIpAddress |
String |
|
主网卡主IP绑定弹性IP的地址。 |
status |
String |
running |
云主机状态,参考 云主机状态。 |
description |
String |
|
云主机描述。 |
imageId |
String |
img-m5s0****29 |
云主机使用的镜像ID。 |
systemDisk |
InstanceDiskAttachment |
|
系统盘配置。 |
dataDisks |
InstanceDiskAttachment[ ] |
|
数据盘配置列表。 |
primaryNetworkInterface |
InstanceNetworkInterfaceAttachment |
|
主网卡主IP关联的弹性公网IP配置。 |
secondaryNetworkInterfaces |
InstanceNetworkInterfaceAttachment[ ] |
|
辅助网卡配置列表。 |
launchTime |
String |
2020-11-11 12:22:56 |
云主机实例的创建时间。 |
az |
String |
cn-north-1b |
云主机所在可用区。 |
keyNames |
String[ ] |
key123 |
云主机使用的密钥对名称。 |
charge |
Charge |
|
云主机的计费信息。 |
ag |
Ag |
|
云主机关联的高可用组,如果创建云主机使用了高可用组,此处可展示高可用组名称。 |
faultDomain |
String |
2 |
高可用组中的故障域。 |
tags |
Tag[ ] |
|
Tag信息。 |
chargeOnStopped |
String |
keepCharging |
停机不计费模式。可能值:
keepCharging :关机后继续计费。
stopCharging :关机后停止计费。
|
policies |
Policy[ ] |
|
任务策略,关联了自动任务策略时可获取相应信息。 |
Policy
名称 |
类型 |
示例值 |
描述 |
policyId |
String |
policy-g65r****o2 |
自动任务策略ID。 |
policyType |
String |
AutoImage |
自动任务策略类型,当前只支持 AutoImage 即自动镜像策略。 |
Tag
名称 |
类型 |
示例值 |
描述 |
key |
String |
环境 |
标签key。长度不能超过127字符,不能以 jrn: 或 jdc- 开头,仅支持中文、大/小写英文、数字及如下符号:\_.,:\/=+-@ 。 |
value |
String |
测试 |
标签value。长度不能超过255字符,仅支持中文、大/小写英文、数字及如下符号:\_.,:\/=+-@ 。 |
Ag
名称 |
类型 |
示例值 |
描述 |
name |
String |
ag-123 |
高可用组名称。 |
id |
String |
ag-81qq****pn |
高可用组ID。 |
Charge
名称 |
类型 |
示例值 |
描述 |
chargeMode |
String |
postpaid_by_duration |
计费模式。 可能值:
postpaid_by_duration :按配置(后付费)
prepaid_by_duration :包年包月(预付费)
postpaid_by_usage :按用量(后付费) 仅弹性公网IP计费模式可能出现postpaid_by_usage
|
chargeStatus |
String |
normal |
费用支付状态。可能值:
normal :正常
overdue :已到期
arrear :已欠费 |
chargeStartTime |
String |
2020-11-11 12:22:56 |
计费开始时间。遵循ISO8601标准,使用UTC时间,格式为:YYYY-MM-DDTHH:mm:ssZ。 |
chargeExpiredTime |
String |
|
到期时间。预付费资源的到期时间,遵循ISO8601标准,使用UTC时间,格式为:YYYY-MM-DDTHH:mm:ssZ,后付费资源此字段内容为空。 |
chargeRetireTime |
String |
|
预期释放时间。到期/欠费后资源的预期释放时间,预付费/后付费资源均有此值,遵循ISO8601标准,使用UTC时间,格式为:YYYY-MM-DDTHH:mm:ssZ。 |
InstanceNetworkInterfaceAttachment
名称 |
类型 |
示例值 |
描述 |
deviceIndex |
Integer |
1 |
网卡设备Index。 对于主网卡默认Index为1。
|
autoDelete |
Boolean |
true |
是否随实例一起删除。可能值:
true :随实例删除。
false :不随实例删除。
|
networkInterface |
InstanceNetworkInterface |
|
网卡设备详细配置。 |
InstanceNetworkInterface
NetworkInterfacePrivateIp
名称 |
类型 |
示例值 |
描述 |
privateIpAddress |
String |
127.0.0.1 |
私有IP的IPV4地址。 |
elasticIpId |
String |
fip-z1z1****ja |
弹性IP实例ID。 |
elasticIpAddress |
String |
116.111.11.1 |
弹性IP实例地址。 |
SecurityGroupSimple
名称 |
类型 |
示例值 |
描述 |
groupId |
String |
sg-p2d1****ya |
安全组ID。 |
groupName |
String |
默认安全组 |
安全组名称。 |
InstanceDiskAttachment
名称 |
类型 |
示例值 |
描述 |
diskCategory |
String |
cloud |
磁盘类型。 系统盘:可能值:local :本地系统盘, cloud :云盘系统盘。 数据盘:可能值:local :本地数据盘, cloud :云盘数据盘。
|
autoDelete |
Boolean |
true |
是否随实例一起删除,即删除实例时是否自动删除此磁盘。
true :随实例删除。
false :不随实例删除。
|
localDisk |
LocalDisk |
|
本地磁盘配置,对应 diskCategory=local 。 |
cloudDisk |
Disk |
|
云硬盘配置,对应 diskCategory=cloud 。 |
deviceName |
String |
vdb |
磁盘逻辑挂载点。 系统盘:默认为vda。 数据盘:可能值:[vdb~vdbm] 。
|
status |
String |
attached |
磁盘挂载状态。 可能值:attaching、detaching、attached、detached、error_attach、error_detach 。 |
Disk
名称 |
类型 |
示例值 |
描述 |
diskId |
String |
disk123 |
云硬盘ID。 |
az |
String |
cn-north-1c |
云硬盘所属AZ。 |
name |
String |
test1 |
云硬盘名称,只允许输入中文、数字、大小写字母、英文下划线“_”及中划线“-”,不允许为空且不超过32字符。 |
description |
String |
|
云硬盘描述,允许输入UTF-8编码下的全部字符,不超过256字符。 |
diskType |
String |
ssd.gp1 |
云硬盘类型,可能值: ssd.gp1、ssd.io1、hdd.std1
|
diskSizeGB |
Integer |
40 |
云硬盘大小,单位为 GiB。 |
iops |
Integer |
2000 |
该云硬盘实际应用的iops值。 |
status |
String |
in-use |
云硬盘状态,可能值: creating、available、in-use、extending、restoring、deleting、deleted、error_create、error_delete、error_restore、error_extend 。 |
snapshotId |
String |
|
创建该云硬盘的快照ID。 |
multiAttachable |
Boolean |
false |
云盘是否支持多挂载。 |
encrypted |
Boolean |
false |
云盘是否为加密盘。 |
createTime |
String |
2021-07-19 20:32:53 |
创建云硬盘时间。 |
LocalDisk
名称 |
类型 |
示例值 |
描述 |
diskType |
String |
HDD |
磁盘类型。可能值:NVMe SSD、HDD 。 |
diskSizeGB |
Integer |
1187 |
磁盘大小。 |
请求示例
GET
/v1/regions/cn-north-1/instances?pageNumber=1&pageSize=10&filters.1.name=instanceId&filters.1.values.1=i-eumm****d6&filters.1.values.2=i-y5nh****9w
返回示例
{
"requestId": "e822b1613bde0dac45596cf756e9c37b",
"result": {
"instances": [
{
"az": "cn-north-1c",
"charge": {
"chargeMode": "postpaid_by_duration",
"chargeStartTime": "2021-07-19T12:33:17Z",
"chargeStatus": "normal"
},
"chargeOnStopped": "keepCharging",
"description": "",
"hostName": "test1",
"imageId": "img-m5s0****29",
"instanceId": "i-eumm****d6",
"instanceName": "test1",
"instanceType": "g.n2.large",
"launchTime": "2021-07-19 20:33:17",
"primaryNetworkInterface": {
"autoDelete": true,
"deviceIndex": 1,
"networkInterface": {
"macAddress": "fa:16:3e:a8:a4:3a",
"networkInterfaceId": "port-n2h7****se",
"primaryIp": {
"privateIpAddress": "127.0.0.1"
},
"securityGroups": [
{
"groupId": "sg-p2d1****ya",
"groupName": "test1"
}
],
"subnetId": "subnet-c2p3****9o",
"vpcId": "vpc-z9r3****p8"
}
},
"privateIpAddress": "127.0.0.1",
"status": "stopped",
"subnetId": "subnet-c2p3****9o",
"systemDisk": {
"autoDelete": true,
"cloudDisk": {
"az": "cn-north-1c",
"createTime": "2021-07-19 20:32:53",
"diskId": "vol-u8r2****c1",
"diskSizeGB": 40,
"diskType": "ssd.gp1",
"encrypt": false,
"encrypted": false,
"iops": 2000,
"multiAttachable": false,
"name": "test1",
"status": "in-use"
},
"deviceName": "vda",
"diskCategory": "cloud",
"status": "attached"
},
"vpcId": "vpc-z9r3****p8"
},
{
"az": "cn-north-1a",
"charge": {
"chargeMode": "postpaid_by_duration",
"chargeStartTime": "2021-04-16T02:08:26Z",
"chargeStatus": "normal"
},
"chargeOnStopped": "keepCharging",
"dataDisks": [
{
"autoDelete": true,
"deviceName": "vdb",
"diskCategory": "local",
"localDisk": {
"diskSizeGB": 894,
"diskType": "SSD"
},
"status": "attached"
},
{
"autoDelete": true,
"deviceName": "vdc",
"diskCategory": "local",
"localDisk": {
"diskSizeGB": 894,
"diskType": "SSD"
},
"status": "attached"
}
],
"description": "",
"elasticIpAddress": "111.111.111.111",
"elasticIpId": "fip-z1z1****ja",
"hostName": "test2",
"imageId": "img-m5s0****29",
"instanceId": "i-y5nh****9w",
"instanceName": "test2",
"instanceType": "p.n1p40.7xlarge",
"launchTime": "2021-04-16 10:08:26",
"primaryNetworkInterface": {
"autoDelete": true,
"deviceIndex": 1,
"networkInterface": {
"macAddress": "fa:16:3e:36:a1:cd",
"networkInterfaceId": "port-n2h7****se",
"primaryIp": {
"elasticIpAddress": "111.111.111.111",
"elasticIpId": "fip-z1z1****ja",
"privateIpAddress": "127.0.0.2"
},
"securityGroups": [
{
"groupId": "sg-p2d1****ya",
"groupName": "Linux安全组开放22端口"
}
],
"subnetId": "subnet-c2p3****9o",
"vpcId": "vpc-z9r3****p8"
}
},
"privateIpAddress": "127.0.0.2",
"status": "running",
"subnetId": "subnet-c2p3****9o",
"systemDisk": {
"autoDelete": true,
"cloudDisk": {
"az": "cn-north-1a",
"createTime": "2021-04-16 10:08:01",
"diskId": "vol-u8r2****c1",
"diskSizeGB": 40,
"diskType": "ssd.gp1",
"encrypt": false,
"encrypted": false,
"iops": 2000,
"multiAttachable": false,
"name": "test2",
"status": "in-use"
},
"deviceName": "vda",
"diskCategory": "cloud",
"status": "attached"
},
"vpcId": "vpc-z9r3****p8"
}
],
"totalCount": 2
}
}
返回码
HTTP状态码 |
错误码 |
描述 |
错误解析 |
200 |
|
OK |
|
400 |
OUT_OF_RANGE |
PageSize out of range |
分页大小超出规定范围。 |
500 |
INTERNAL |
Internal server error |
系统内部错误,请稍后重试。如果多次尝试失败,请提交工单。 |
500 |
UNKNOWN |
Unknown server error |
服务暂时不可用,请稍后重试。如果多次尝试失败,请提交工单。 |