Querying ECSs

Updated on 2024-01-31 GMT+08:00

View PDF

Function

This API is used to query ECSs.

Calling Method

For details, see Calling APIs.

URI

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

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	User project ID Minimum: 1 Maximum: 256

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
enterprise_project_id	No	String	Enterprise project ID Default: 0 Minimum: 1 Maximum: 256
version	No	String	HSS edition. Its value can be: hss.version.null hss.version.basic: basic edition hss.version.advanced: professional edition hss.version.enterprise: enterprise edition hss.version.premium: premium edition hss.version.wtp: WTP edition hss.version.container.enterprise: container edition Minimum: 1 Maximum: 64
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. Minimum: 1 Maximum: 20
detect_result	No	String	Detection result. Its value can be: undetected clean risk scanning Minimum: 1 Maximum: 32
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 Minimum: 1 Maximum: 32
os_type	No	String	OS type. Its value can be: Linux Windows Minimum: 0 Maximum: 64
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 Minimum: 1 Maximum: 32
group_id	No	String	Server group ID
group_name	No	String	Server group name Minimum: 1 Maximum: 64
has_intrusion	No	Boolean	Alarms exist.
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	Billing mode. Its value can be: packet_cycle: yearly/monthly on_demand: pay-per-use Minimum: 1 Maximum: 32
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 Huawei Cloud server
asset_value	No	String	Asset importance. Its value can be: important common test Minimum: 0 Maximum: 128
label	No	String	Asset tag Minimum: 1 Maximum: 64
server_group	No	String	Asset server group Minimum: 1 Maximum: 64
agent_upgradable	No	Boolean	Whether the agent can be upgraded
limit	No	Integer	Number of records displayed on each page. The default value is 10. Minimum: 0 Maximum: 200 Default: 10
offset	No	Integer	Offset, which specifies the start position of the record to be returned. The value must be a number no less than 0. The default value is 0. Minimum: 0 Maximum: 2000000 Default: 0

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
x-auth-token	Yes	String	User token. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is a token. Minimum: 1 Maximum: 32768
region	No	String	region id Minimum: 0 Maximum: 128

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 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 Minimum: 1 Maximum: 32
agent_status	String	Agent status. Its value can be: not_ installed online offline install_failed installing Minimum: 1 Maximum: 32
install_result_code	String	Installation result. Its value can be: 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 are no servers with an online agent in the current VPC. install_exception invalid_param install_failed package_unavailable os_type_not_support: Incorrect OS type os_arch_not_support: Incorrect OS architecture Minimum: 1 Maximum: 32
version	String	HSS edition. Its value can be: hss.version.null: none hss.version.basic: basic edition hss.version.enterprise: enterprise edition hss.version.premium: premium edition hss.version.wtp: WTP edition hss.version.container.enterprise: container edition Minimum: 1 Maximum: 32
protect_status	String	Protection status. Its value can be: closed opened Minimum: 1 Maximum: 32
os_image	String	System disk image Minimum: 0 Maximum: 128
os_type	String	OS type. Its value can be: Linux Windows Minimum: 0 Maximum: 128
os_bit	String	OS bit version Minimum: 0 Maximum: 128
detect_result	String	Server scan result. Its value can be: undetected clean risk scanning Minimum: 1 Maximum: 32
expire_time	Long	Expiration time of the trial version. (The value -1 indicates that the quota is non-trial version. If the value is not -1, the value indicates the expiration time of the trial version.) Minimum: 0 Maximum: 4824695185000
charging_mode	String	Billing mode. Its value can be: packet_cycle: yearly/monthly on_demand: pay-per-use Minimum: 1 Maximum: 32
resource_id	String	Cloud service resource instance ID (UUID) Minimum: 0 Maximum: 128
outside_host	Boolean	Whether a server is a non-Huawei 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	Vulnerability Minimum: 0 Maximum: 2097152
baseline	Integer	Baseline risks Minimum: 0 Maximum: 2097152
intrusion	Integer	Intrusion risk Minimum: 0 Maximum: 2097152
asset_value	String	Asset importance. Its value can be: important common test Minimum: 0 Maximum: 128
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 Minimum: 1 Maximum: 32
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: The disk space is insufficient. failed_to_replace_file: Failed to replace the file. Minimum: 1 Maximum: 32
upgradable	Boolean	Whether the agent of the server can be upgraded
open_time	Long	Time when the protection is enabled. This is a timestamp. The default unit is milliseconds. Minimum: 0 Maximum: 4824695185000
protect_interrupt	Boolean	Whether protection is interrupted

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