更新时间:2025-09-23 GMT+08:00

查询云服务器列表

功能介绍

查询云服务器列表

URI

GET /v5/{project_id}/host-management/hosts

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

租户项目ID

表2 Query参数

参数

是否必选

参数类型

描述

enterprise_project_id

String

企业项目ID,查询所有企业项目时填写:all_granted_eps

version

String

主机开通的版本,包含如下7种输入。

  • hss.version.null :无。

  • hss.version.basic :基础版。

  • hss.version.advanced :专业版。

  • hss.version.enterprise :企业版。

  • hss.version.premium :旗舰版。

  • hss.version.wtp :网页防篡改版。

  • hss.version.container.enterprise:容器版。

agent_status

String

Agent状态,包含如下6种。

  • installed :已安装。

  • not_installed :未安装。

  • online :在线。

  • offline :离线。

  • install_failed :安装失败。

  • installing :安装中。

  • not_online :不在线的(除了在线以外的所有状态,仅作为查询条件)。

detect_result

String

检测结果,包含如下4种。

  • undetected :未检测。

  • clean :无风险。

  • risk :有风险。

  • scanning :检测中。

host_name

String

服务器名称

host_id

String

服务器ID

host_status

String

主机状态,包含如下4种。

  • ACTIVE :正在运行。

  • SHUTOFF :关机。

  • BUILDING :创建中。

  • ERROR :故障。

os_type

String

操作系统类型,包含如下2种。

  • Linux :Linux。

  • Windows :Windows。

private_ip

String

服务器私有IP

public_ip

String

服务器公网IP

ip_addr

String

公网或私网IP

protect_status

String

防护状态,包含如下2种。

  • closed :关闭。

  • opened :开启。

group_id

String

服务器组ID

group_name

String

服务器组名称

has_intrusion

Boolean

存在告警事件

policy_group_id

String

策略组ID

policy_group_name

String

策略组名称

charging_mode

String

收费模式,包含如下:

  • on_demand :按需。

refresh

Boolean

是否强制从ECS同步主机

above_version

Boolean

是否返回比当前版本高的所有版本

outside_host

Boolean

是否为云主机

asset_value

String

资产重要性,包含如下4种

  • important :重要资产

  • common :一般资产

  • test :测试资产

label

String

资产标签

server_group

String

资产服务器组

agent_upgradable

Boolean

agent是否可升级

protect_interrupt

Boolean

是否防护中断

protect_degradation

Boolean

是否防护降级

limit

Integer

每页显示个数,默认10

offset

Integer

偏移量:指定返回记录的开始位置,必须为数字,取值范围为大于或等于0,默认0

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

x-auth-token

String

用户Token。

通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)

响应参数

状态码:200

表4 响应Body参数

参数

参数类型

描述

total_num

Integer

总数

data_list

Array of Host objects

查询弹性云服务器状态列表

表5 Host

参数

参数类型

描述

host_name

String

服务器名称

host_id

String

服务器ID

agent_id

String

Agent ID

private_ip

String

私有IP地址

public_ip

String

弹性公网IP地址

enterprise_project_id

String

企业项目ID

enterprise_project_name

String

所属企业项目名称

host_status

String

服务器状态,包含如下4种。

  • ACTIVE :运行中。

  • SHUTOFF :关机。

  • BUILDING :创建中。

  • ERROR :故障。

agent_status

String

Agent状态,包含如下5种。

  • installed :已安装。

  • not_installed :未安装。

  • online :在线。

  • offline :离线。

  • install_failed :安装失败。

  • installing :安装中。

install_result_code

String

安装结果,包含如下12种。

  • install_succeed :安装成功。

  • network_access_timeout :网络不通,访问超时。

  • invalid_port :无效端口。

  • auth_failed :认证错误,口令不正确。

  • permission_denied :权限错误,被拒绝。

  • no_available_vpc :没有相同VPC的agent在线虚拟机。

  • install_exception :安装异常。

  • invalid_param :参数错误。

  • install_failed :安装失败。

  • package_unavailable :安装包失效。

  • os_type_not_support :系统类型错误。

  • os_arch_not_support :架构类型错误。

version

String

主机开通的版本,包含如下7种输入。

  • hss.version.null :无。

  • hss.version.basic :基础版。

  • hss.version.advanced :专业版。

  • hss.version.enterprise :企业版。

  • hss.version.premium :旗舰版。

  • hss.version.wtp :网页防篡改版。

  • hss.version.container.enterprise :容器版。

protect_status

String

防护状态,包含如下2种。

  • closed :未防护。

  • opened :防护中。

os_image

String

系统镜像

os_type

String

操作系统类型,包含如下2种。

  • Linux :Linux。

  • Windows :Windows。

os_bit

String

操作系统位数

detect_result

String

云主机安全检测结果,包含如下4种。

  • undetected :未检测。

  • clean :无风险。

  • risk :有风险。

  • scanning :检测中。

expire_time

Long

试用版到期时间(-1表示非试用版配额,当值不为-1时为试用版本过期时间)

charging_mode

String

收费模式,包含如下:

  • on_demand :按需。

resource_id

String

主机安全配额ID(UUID)

outside_host

Boolean

是否非云机器

group_id

String

服务器组ID

group_name

String

服务器组名称

policy_group_id

String

策略组ID

policy_group_name

String

策略组名称

asset

Integer

资产风险

vulnerability

Integer

漏洞风险

baseline

Integer

基线风险

intrusion

Integer

入侵风险

asset_value

String

资产重要性,包含如下4种

  • important :重要资产

  • common :一般资产

  • test :测试资产

labels

Array of strings

标签列表

agent_create_time

Long

agent安装时间,采用时间戳,默认毫秒,

agent_update_time

Long

agent状态修改时间,采用时间戳,默认毫秒,

agent_version

String

agent版本

upgrade_status

String

升级状态,包含如下4种。

  • not_upgrade :未升级,也就是默认状态,客户还没有给这台机器下发过升级。

  • upgrading :正在升级中。

  • upgrade_failed :升级失败。

  • upgrade_succeed :升级成功。

upgrade_result_code

String

升级失败原因,只有当 upgrade_status 为 upgrade_failed 时才显示,包含如下6种。

  • package_unavailable :升级包解析失败,升级文件有错误。

  • network_access_timeout :下载升级包失败,网络异常。

  • agent_offline :agent离线。

  • hostguard_abnormal :agent工作进程异常。

  • insufficient_disk_space :磁盘空间不足。

  • failed_to_replace_file :替换文件失败。

upgradable

Boolean

该服务器agent是否可升级

open_time

Long

开启防护时间,采用时间戳,默认毫秒,

protect_interrupt

Boolean

防护是否中断

protect_degradation

Boolean

防护是否降级

degradation_reason

String

防护降级原因

请求示例

查询agent状态为在线的所有企业项目下的10台linux主机。

GET https://{endpoint}/v5/{project_id}/host-management/hosts?limit=10&offset=0&agent_status=online&os_type=Linux&enterprise_project_id=all_granted_eps

响应示例

状态码:200

云服务器列表

{
  "total_num" : 1,
  "data_list" : [ {
    "agent_id" : "2758d2a61598fd9144cfa6b201049e7c0af8c3f1280cd24e3ec95a2f0811a2a2",
    "agent_status" : "online",
    "asset" : 0,
    "asset_value" : "common",
    "baseline" : 0,
    "charging_mode" : "on_demand",
    "detect_result" : "risk",
    "enterprise_project_id" : "all_granted_eps",
    "enterprise_project_name" : "default",
    "group_id" : "7c659ea3-006f-4687-9f1c-6d975d955f37",
    "group_name" : "default",
    "host_id" : "caa958ad-a481-4d46-b51e-6861b8864515",
    "host_name" : "ecs-r00431580-ubuntu",
    "host_status" : "ACTIVE",
    "intrusion" : 0,
    "expire_time" : -1,
    "os_bit" : "64",
    "os_type" : "Linux",
    "outside_host" : false,
    "policy_group_id" : "2758d2a61598fd9144cfa6b201049e7c0af8c3f1280cd24e3ec95a2f0811a2a2",
    "policy_group_name" : "wtp_ecs-r00431580-ubuntu(default)",
    "private_ip" : "192.168.0.182",
    "protect_status" : "opened",
    "protect_interrupt" : false,
    "public_ip" : "100.85.123.9",
    "resource_id" : "60f08ea4-c74e-4a45-be1c-3c057e373af2",
    "version" : "hss.version.wtp",
    "vulnerability" : 97,
    "labels" : [ "" ],
    "agent_create_time" : 0,
    "agent_update_time" : 0,
    "open_time" : 0
  } ]
}

状态码

状态码

描述

200

云服务器列表

错误码

请参见错误码