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

Querying ECSs

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

Status Codes

Status Code

Description

200

Cloud server list

Error Codes

See Error Codes.