Querying ECSs_Server Management_API Description_API Reference

Function

This API is used to query ECSs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

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

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID, which is used to specify the project that an asset belongs to. After the project ID is configured, you can query assets in the project using the project ID. For details about how to obtain it, see Obtaining a Project ID. Constraints N/A Range The value can contain 1 to 256 characters. Default Value N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
enterprise_project_id	No	String	Definition Enterprise project ID, which is used to filter assets in different enterprise projects. For details, see Obtaining an Enterprise Project ID. To query assets in all enterprise projects, set this parameter to all_granted_eps. Constraints You need to set this parameter only after the enterprise project function is enabled. Range The value can contain 1 to 256 characters. Default Value 0: default enterprise project.
version	No	String	Definition Enabled HSS edition. Constraints N/A Range The options are as follows: hss.version.null: none 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 Default Value N/A
agent_status	No	String	Definition Agent status. Constraints N/A Range The agent statuses are divided into two types: installed The install statuses include the following: online. The agent has been installed and connected to the HSS cloud protection center. offline. The agent has been installed, but is disconnected from the HSS cloud protection center. install_failed. An error or problem occurred, leading to an installation failure. installing. The agent is being installed. not_installed The agent has not been installed on a server. To filter agents in all the states except online, set the filter to not_online (used as a query condition only). Default Value N/A
detect_result	No	String	Definition Check result. Constraints N/A Range The options are as follows: undetected: not checked clean: no risks detected risk: risks detected scanning: scan in progress Default Value N/A
host_name	No	String	Definition Server name. Constraints N/A Range The value contains 1 to 256 characters. Default Value N/A
host_id	No	String	Definition Unique ID of a server. Constraints N/A Range The value can contain 1 to 64 characters. Default Value N/A
host_status	No	String	Definition Server status. Constraints N/A Range The options are as follows: ACTIVE: running SHUTOFF: shut down BUILDING: creating ERROR: faulty Default Value N/A
os_type	No	String	Definition OS type. Constraints N/A Range The options are as follows: Linux Windows Default Value N/A
private_ip	No	String	Definition Server private IP address. Constraints N/A Range The value can contain 1 to 128 characters. Default Value N/A
public_ip	No	String	Definition Server EIP. Constraints N/A Range For IPv4, the value contains 7 to 15 characters. For IPv6, the value contains 15 to 39 characters. Default Value None
ip_addr	No	String	Definition EIP or private IP address. Constraints N/A Range The value can contain 1 to 128 characters. Default Value N/A
protect_status	No	String	Definition Protection status. Constraints N/A Range The options are as follows: closed opened protection_exception Default Value N/A
group_id	No	String	Definition Unique ID of a server group. Constraints N/A Range The value can contain 1 to 64 characters. Default Value N/A
group_name	No	String	Definition Server group name. Constraints N/A Range The value can contain 1 to 64 characters. Default Value N/A
vpc_id	No	String	Definition VPC ID. Constraints N/A Range The value can contain 1 to 128 characters. Default Value N/A
host_name_list	No	String	Definition Server name list. Constraints N/A Range A server name contains 1 to 64 characters. Number of server names to be queried. 1 to 60 names are allowed. Use commas (,) to separate them. Default Value N/A
host_id_list	No	String	Definition Server ID list. Constraints N/A Range A server ID contains 1 to 36 characters. Number of server IDs to be queried. 1 to 100 IDs are allowed. Use commas (,) to separate them. Default Value N/A
public_ip_list	No	String	Definition Server EIP list. Constraints N/A Range A server EIP contains 1 to 39 characters. Number of server EIPs to be queried. 1 to 100 EIPs are allowed. Use commas (,) to separate them. Default Value N/A
private_ip_list	No	String	Definition Server private IP address list. Constraints N/A Range A server private IP address contains 1 to 39 characters. Number of private IP addresses to be queried in batches. 1 to 100 IP addresses are allowed. Use commas (,) to separate them. Default Value N/A
has_intrusion	No	Boolean	Definition Whether there are alarms. Constraints N/A Range true or false Default Value N/A
has_vul	No	Boolean	Definition Whether there are vulnerabilities. Constraints N/A Range true or false Default Value N/A
has_baseline	No	Boolean	Definition Whether there are baseline risks. Constraints N/A Range true or false Default Value N/A
sort_key	No	String	Definition Sorting field. Constraints N/A Range Only risk_num is supported. Default Value N/A
sort_dir	No	String	Definition Sorting order. Constraints N/A Range asc: ascending desc: descending Default Value N/A
policy_group_id	No	String	Definition Policy group ID. Constraints N/A Range The value can contain 0 to 128 characters. Default Value N/A
policy_group_name	No	String	Definition Policy group name. Constraints N/A Range The value can contain 1 to 256 characters. Default Value N/A
charging_mode	No	String	Definition Billing mode. Constraints N/A Range packet_cycle: yearly/monthly on_demand: pay-per-use Default Value N/A
refresh	No	Boolean	Definition Whether to forcibly synchronize servers from ECS. Constraints N/A Range true or false Default Value N/A
get_common_login_locations	No	Boolean	Definition Whether to obtain the common login locations of a server. Constraints N/A Range true or false Default Value N/A
above_version	No	Boolean	Definition Whether to return all the versions later than the current version. Constraints N/A Range true or false Default Value N/A
outside_host	No	Boolean	Definition Whether a server is a Huawei Cloud server. Constraints N/A Range true or false Default Value N/A
asset_value	No	String	Definition Asset importance. Constraints N/A Range The options are as follows: important: important asset common: common asset test Default Value N/A
label	No	String	Definition Asset tag. Constraints N/A Range The value can contain 1 to 64 characters. Default Value N/A
server_group	No	String	Definition Server group of an asset. Constraints N/A Range The value can contain 1 to 64 characters. Default Value N/A
agent_upgradable	No	Boolean	Definition Whether the agent can be upgraded. Constraints N/A Range true or false Default Value N/A
install_mode	No	Boolean	Definition Whether the installation mode is enabled. Constraints N/A Range true or false Default Value N/A
binding_key	No	Boolean	Definition Whether a DEW key is bound. Constraints N/A Range true or false Default Value N/A
protect_interrupt	No	Boolean	Definition Whether the protection is interrupted. Constraints N/A Range true or false Default Value N/A
incluster	No	Boolean	Definition Whether a node is in a cluster. Constraints N/A Range true or false Default Value N/A
protect_degradation	No	Boolean	Definition Whether the protection is degraded. Constraints N/A Range true or false Default Value N/A
cluster_id	No	String	Definition Cluster ID. Constraints N/A Range The value can contain 1 to 64 characters. Default Value N/A
offset	No	Integer	Definition Offset, which specifies the start position of the record to be returned. Constraints N/A Range The value range is 0 to 2,000,000. Default Value The default value is 0.
limit	No	Integer	Definition Number of records displayed on each page. Constraints N/A Range Value range: 10-200 Default Value 10

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token, which contains user identity and permissions. The token can be used for identity authentication when an API is called. For details about how to obtain the token, see Obtaining a User Token. Constraints N/A Range The value can contain 1 to 32,768 characters. Default Value N/A
region	No	String	Definition Region ID, which is used to query assets in the required region. For details about how to obtain a region ID, see Obtaining a Region ID. Constraints N/A Range The value can contain 1 to 128 characters. Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
total_num	Integer	Definition Total number. Range Value range: 0 to 2,097,152
data_list	Array of Host objects	Definition Query the cloud server status list. Range N/A

**Table 5** Host
Parameter	Type	Description
host_name	String	Definition Server name. Range The value can contain 1 to 128 characters.
host_id	String	Definition Server ID. Range The value can contain 1 to 128 characters.
agent_id	String	Definition Agent ID Range The value can contain 1 to 128 characters.
private_ip	String	Definition Private IP address. Range The value can contain 1 to 128 characters.
public_ip	String	Definition EIP. Range The value can contain 1 to 128 characters.
enterprise_project_id	String	Definition Enterprise project ID. Range The value can contain 0 to 256 characters.
enterprise_project_name	String	Definition Enterprise project name. Range The value can contain 0 to 256 characters.
os_name	String	Definition System name. Range The value can contain 0 to 128 characters.
os_version	String	Definition System version. Range The value can contain 0 to 256 characters.
kernel_version	String	Definition Kernel version. Range The value can contain 0 to 256 characters.
host_status	String	Definition Server status. Range The options are as follows: ACTIVE: running SHUTOFF: shut down BUILDING: creating ERROR: faulty
agent_status	String	Definition Agent status. Range The options are as follows: installed not_installed online offline install_failed installing
install_result_code	String	Definition Installation result. Range The options are as follows: install_succeed: The installation is successful. network_access_timeout: Connection timed out. Network error. invalid_port: The port is invalid. 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: The installation is abnormal. invalid_param: Incorrect parameter. install_failed: Installation failed. package_unavailable: The installation package is invalid. os_type_not_support: Incorrect OS type. os_arch_not_support: Incorrect OS architecture.
version	String	Definition Enabled HSS edition. Range The options are as follows: hss.version.null: none 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
protect_status	String	Definition Protection status. Range The options are as follows: closed: not protected opened: protected protection_exception
os_image	String	Definition System image. Range The value can contain 0 to 128 characters.
os_type	String	Definition OS type. Range The options are as follows: Linux Windows
os_bit	String	Definition OS bit version. Range The value can contain 0 to 128 characters.
detect_result	String	Definition Cloud server security scan result. Range The options are as follows: undetected: not checked clean: no risks detected risk: risks detected scanning: scan in progress
expire_time	Long	Definition Trial edition expiration time. Range -1 to 4,824,695,185,000. (-1 indicates the quota of the non-trial edition. If the value is not -1, it indicates the expiration time of the trial edition.)
charging_mode	String	Definition Billing mode. Range The options are as follows: packet_cycle: yearly/monthly on_demand: pay-per-use
resource_id	String	Definition HSS quota ID (UUID). Range The value can contain 0 to 128 characters.
outside_host	Boolean	Definition Whether a server is a non-Huawei Cloud server. Range true or false
group_id	String	Definition Server group ID. Range The value can contain 0 to 128 characters.
group_name	String	Definition Server group name. Range The value can contain 0 to 128 characters.
policy_group_id	String	Definition Policy group ID. Range The value can contain 0 to 128 characters.
policy_group_name	String	Definition Policy group name. Range The value can contain 0 to 128 characters.
asset	Integer	Definition Asset risk. Range 0-2097152
vulnerability	Integer	Definition Total number of vulnerabilities, including Linux, Windows, Web-CMS, and application vulnerabilities. Range 0-2097152
baseline	Integer	Definition Total number of baseline risks, including configuration risks and weak passwords. Range 0-2097152
intrusion	Integer	Definition Total intrusion risks. Range 0-2097152
asset_value	String	Definition Asset importance. Range The options are as follows: important common test
labels	Array of strings	Definition Tag list. Range N/A
agent_create_time	Long	Definition Agent installation time, which is a timestamp. The default unit is milliseconds. Range 0-4824695185000
agent_update_time	Long	Definition Time when the agent status is changed. This is a timestamp. The default unit is milliseconds. Range 0-4824695185000
agent_version	String	Definition Agent version. Range The value can contain 0 to 32 characters.
upgrade_status	String	Definition Upgrade status. Range The options are as follows: 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: The upgrade is successful.
upgrade_result_code	String	Definition Upgrade failure cause. This parameter is displayed only when upgrade_status is upgrade_failed. Range The options are as follows: 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.
upgradable	Boolean	Definition Whether the agent of the server can be upgraded Range true or false
open_time	Long	Definition Time when the protection is enabled. This is a timestamp. The default unit is milliseconds. Range 0-4824695185000
protect_interrupt	Boolean	Definition Whether protection is interrupted. Range true or false
protect_degradation	Boolean	Definition Whether protection is degraded. Range true or false
host_sources	String	Definition Server source. Range The options are as follows: ecs: Huawei Cloud ECS. outside: non-Huawei Cloud servers. workspace: Huawei Cloud Workspace.
interrupt_reason	String	Definition Cause of protection interruption. Range The value can contain 1 to 32 characters.
degradation_reason	String	Definition Protection degradation cause. Range The value can contain 1 to 32 characters.
key_name	String	Definition Name of the used key pair. Range The value can contain 1 to 32 characters.
auto_open_version	String	Definition CCE server. Range The value can contain 1 to 32 characters.
install_progress	Integer	Definition Installation progress. Range 0-100
vpc_id	String	Definition vpc id Range The value can contain 0 to 128 characters.
common_login_area_codes	Array of integers	Definition Common server login location ID used for backend identification. Range N/A
cluster_name	String	Definition Cluster name. Range The value can contain 1 to 128 characters.
cluster_id	String	Definition Cluster ID. Range The value can contain 1 to 128 characters.

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

Request succeeded.

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

Status Codes

Status Code	Description
200	Request succeeded.

Error Codes

See Error Codes.

Querying ECSs