Querying ECSs

Function

This API is used to query ECSs.

URI

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

Table 1 Path Parameters

Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID Minimum: 1 Maximum: 256

Table 2 Query Parameters

Parameter	Mandatory	Type	Description
enterprise_project_id	No	String	Enterprise project ID. The value 0 indicates the default enterprise project. To query all enterprise projects, set this parameter to all_granted_eps. Default: 0 Minimum: 1 Maximum: 256
version	No	String	HSS edition. Its values and their meaning are as follows: hss.version.null: none hss.version.enterprise: enterprise edition hss.version.premium: premium edition hss.version.container.enterprise: container edition
agent_status	No	String	Agent status. Its value can be: not_ installed online offline install_failed installing not_online: All status except online, which is used only as a query condition.
detect_result	No	String	Detection result. Its value can be: undetected clean risk scanning
host_name	No	String	Server name
host_id	No	String	Server ID
host_status	No	String	Host status. Its value can be: ACTIVE SHUTOFF BUILDING ERROR
os_type	No	String	OS type. Its value can be: Linux Windows
private_ip	No	String	Server private IP address
public_ip	No	String	Server public IP address
ip_addr	No	String	Public or private IP address
protect_status	No	String	Protection status. Its value can be: closed opened
group_id	No	String	Server group ID
group_name	No	String	Server group name Minimum: 1 Maximum: 64
policy_group_id	No	String	Policy group ID Minimum: 0 Maximum: 128
policy_group_name	No	String	Policy group name Minimum: 0 Maximum: 256
charging_mode	No	String	on_demand: pay-per-use
refresh	No	Boolean	Whether to forcibly synchronize servers from ECSs
above_version	No	Boolean	Whether to return all the versions later than the current version
outside_host	No	Boolean	Whether a server is a non-cloud server
asset_value	No	String	Asset importance. Its value can be: important common test
label	No	String	Asset tag Minimum: 1 Maximum: 64
server_group	No	String	Asset server group Minimum: 1 Maximum: 64
limit	No	Integer	Number of records displayed on each page. Minimum: 0 Maximum: 200 Default: 10
offset	No	Integer	Offset, which specifies the start position of the record to be returned. Minimum: 0 Maximum: 2000000 Default: 0

Request Parameters

Table 3 Request header parameters

Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. Minimum: 1 Maximum: 32768

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter	Type	Description
total_num	Integer	Total number of records Minimum: 0 Maximum: 2097152
data_list	Array of Host objects	Query on the cloud server status and list Array Length: 0 - 10241

Table 5 Host

Parameter	Type	Description
host_name	String	Server name Minimum: 0 Maximum: 128
host_id	String	Server ID Minimum: 0 Maximum: 128
agent_id	String	Agent ID Minimum: 0 Maximum: 128
private_ip	String	Private IP address Minimum: 0 Maximum: 128
public_ip	String	Elastic IP address Minimum: 0 Maximum: 128
enterprise_project_id	String	Enterprise project ID. The value 0 indicates the default enterprise project. To query all enterprise projects, set this parameter to all_granted_eps. Minimum: 0 Maximum: 256
enterprise_project_name	String	Enterprise project name Minimum: 0 Maximum: 256
host_status	String	Server status. Its value can be: ACTIVE SHUTOFF BUILDING ERROR
agent_status	String	Agent status. Its value can be: not_ installed online offline install_failed installing
install_result_code	String	Installation result. This API is available only for agents that are installed in batches. The options are as follows: install_succeed network_access_timeout: Connection timed out. Network error. invalid_port auth_failed: The authentication failed due to incorrect password. permission_denied: Insufficient permissions. no_available_vpc: There is no server with an online agent in the current VPC. install_exception invalid_param: Incorrect parameter. install_failed package_unavailable os_type_not_support: Incorrect OS type os_arch_not_support: Incorrect OS architecture
version	String	HSS edition. Its values and their meaning are as follows: hss.version.null: none hss.version.enterprise: enterprise edition hss.version.premium: premium edition hss.version.container.enterprise: container edition
protect_status	String	Protection status. Its value can be: closed opened
os_image	String	System disk image Minimum: 0 Maximum: 128
os_type	String	OS type. Its value can be: Linux Windows
os_bit	String	OS bit version Minimum: 0 Maximum: 128
detect_result	String	Server scan result. Its value can be: undetected clean risk scanning
charging_mode	String	on_demand: pay-per-use
resource_id	String	Cloud service resource instance ID (UUID) Minimum: 0 Maximum: 128
outside_host	Boolean	Whether a server is a non-cloud server
group_id	String	Server group ID Minimum: 1 Maximum: 128
group_name	String	Server group name Minimum: 1 Maximum: 128
policy_group_id	String	Policy group ID Minimum: 1 Maximum: 128
policy_group_name	String	Policy group name Minimum: 1 Maximum: 128
asset	Integer	Asset risk Minimum: 0 Maximum: 2097152
vulnerability	Integer	Total number of vulnerabilities, including Linux, Windows, Web-CMS, and application vulnerabilities. Minimum: 0 Maximum: 2097152
baseline	Integer	Total number of baseline risks, including configuration risks and weak passwords. Minimum: 0 Maximum: 2097152
intrusion	Integer	Total intrusion risks Minimum: 0 Maximum: 2097152
asset_value	String	Asset importance. Its value can be: important common test
labels	Array of strings	Tag list Minimum: 0 Maximum: 64 Array Length: 0 - 100
agent_create_time	Long	Agent installation time, which is a timestamp. The default unit is milliseconds. Minimum: 0 Maximum: 4824695185000
agent_update_time	Long	Time when the agent status is changed. This is a timestamp. The default unit is milliseconds. Minimum: 0 Maximum: 4824695185000
agent_version	String	Agent version Minimum: 1 Maximum: 32
upgrade_status	String	Upgrade status. Its value can be: not_upgrade: Not upgraded. This is the default status. The customer has not delivered any upgrade command to the server. upgrading: The upgrade is in progress. upgrade_failed: The upgrade failed. upgrade_succeed
upgrade_result_code	String	Upgrade failure cause. This parameter is displayed only if upgrade_status is upgrade_failed. Its value can be: package_unavailable: The upgrade package fails to be parsed because the upgrade file is incorrect. network_access_timeout: Failed to download the upgrade package because the network is abnormal. agent_offline: The agent is offline. hostguard_abnormal: The agent process is abnormal. insufficient_disk_space failed_to_replace_file: Failed to replace the file.
upgradable	Boolean	Whether the agent of the server can be upgraded

Example Requests

Query the 10 Linux servers in all enterprise projects whose agent status is online.

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

Example Responses

Status code: 200

cloud server list

{
  "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",
    "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
  } ]
}

Status Codes

Status Code	Description
200	cloud server list

Error Codes

See Error Codes.

last updated: 2024-11-13 14:56 UTC - commit: 5a24b83d79f89c6961ca080f765a6ba0043bab85