/ DOCS
nav-img
Advanced

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.

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

enterprise_project_id

No

String

Enterprise project ID. To query all enterprise projects, set this parameter to all_granted_eps.

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

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

has_intrusion

No

Boolean

Alarms exist.

policy_group_id

No

String

Policy group ID

policy_group_name

No

String

Policy group name

charging_mode

No

String

Billing mode. Its value can be:

  • 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

Cloud server or not

asset_value

No

String

Asset importance. Its value can be:

  • important

  • common

  • test

label

No

String

Asset tag

server_group

No

String

Asset server group

agent_upgradable

No

Boolean

Whether the agent can be upgraded

limit

No

Integer

Number of records on each page

offset

No

Integer

Offset, which specifies the start position of the record to be returned.

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.

region

No

String

Region ID

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

total_num

Integer

Total number of records

data_list

Array of Host objects

Query on the cloud server status and list

Table 5 Host

Parameter

Type

Description

host_name

String

Server name

host_id

String

Server ID

agent_id

String

Agent ID

private_ip

String

Private IP address

public_ip

String

Elastic IP address

enterprise_project_id

String

Enterprise project ID

enterprise_project_name

String

Enterprise project name

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. 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

version

String

HSS edition. Its value can be:

  • 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

Protection status. Its value can be:

  • closed

  • opened

os_image

String

System disk image

os_type

String

OS type. Its value can be:

  • Linux

  • Windows

os_bit

String

OS bit version

detect_result

String

Server scan result. Its value can be:

  • undetected

  • clean

  • risk

  • scanning

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.)

charging_mode

String

Billing mode. Its value can be:

  • on_demand: pay-per-use

resource_id

String

Cloud service resource instance ID (UUID)

outside_host

Boolean

Whether a server is on-premises

group_id

String

Server group ID

group_name

String

Server group name

policy_group_id

String

Policy group ID

policy_group_name

String

Policy group name

asset

Integer

Asset risk

vulnerability

Integer

Total number of vulnerabilities, including Linux, Windows, Web-CMS, and application vulnerabilities.

baseline

Integer

Total number of baseline risks, including configuration risks and weak passwords.

intrusion

Integer

Total intrusion risks

asset_value

String

Asset importance. Its value can be:

  • important

  • common

  • test

labels

Array of strings

Tag list

agent_create_time

Long

Agent installation time, which is a timestamp. The default unit is milliseconds.

agent_update_time

Long

Time when the agent status is changed. This is a timestamp. The default unit is milliseconds.

agent_version

String

Agent version

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: The disk space is insufficient.

  • failed_to_replace_file: Failed to replace the file.

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.

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

Request succeeded.

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

Status Codes

Status Code

Description

200

Request succeeded.

Error Codes

Parent topic: Server Management
Предыдущая статья
Server Management
Следующая статья
Changing the Protection Status
Была ли эта статья полезна?
Поддержка Юридические документы
© 2025 Cloud.ru