Updated on 2024-05-13 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

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

Total number of vulnerability risks, including Linux software vulnerabilities, Windows system vulnerabilities, Web-CMS vulnerabilities, 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

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

SDK Sample Code

The SDK sample code is as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.hss.v5.region.HssRegion;
import com.huaweicloud.sdk.hss.v5.*;
import com.huaweicloud.sdk.hss.v5.model.*;


public class ListHostStatusSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");

        ICredential auth = new BasicCredentials()
                .withAk(ak)
                .withSk(sk);

        HssClient client = HssClient.newBuilder()
                .withCredential(auth)
                .withRegion(HssRegion.valueOf("<YOUR REGION>"))
                .build();
        ListHostStatusRequest request = new ListHostStatusRequest();
        request.withEnterpriseProjectId("<enterprise_project_id>");
        request.withVersion("<version>");
        request.withAgentStatus("<agent_status>");
        request.withDetectResult("<detect_result>");
        request.withHostName("<host_name>");
        request.withHostId("<host_id>");
        request.withHostStatus("<host_status>");
        request.withOsType("<os_type>");
        request.withPrivateIp("<private_ip>");
        request.withPublicIp("<public_ip>");
        request.withIpAddr("<ip_addr>");
        request.withProtectStatus("<protect_status>");
        request.withGroupId("<group_id>");
        request.withGroupName("<group_name>");
        request.withHasIntrusion(<has_intrusion>);
        request.withPolicyGroupId("<policy_group_id>");
        request.withPolicyGroupName("<policy_group_name>");
        request.withChargingMode("<charging_mode>");
        request.withRefresh(<refresh>);
        request.withAboveVersion(<above_version>);
        request.withOutsideHost(<outside_host>);
        request.withAssetValue("<asset_value>");
        request.withLabel("<label>");
        request.withServerGroup("<server_group>");
        request.withAgentUpgradable(<agent_upgradable>);
        request.withLimit(<limit>);
        request.withOffset(<offset>);
        try {
            ListHostStatusResponse response = client.listHostStatus(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# coding: utf-8

from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkhss.v5.region.hss_region import HssRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkhss.v5 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = __import__('os').getenv("CLOUD_SDK_AK")
    sk = __import__('os').getenv("CLOUD_SDK_SK")

    credentials = BasicCredentials(ak, sk) \

    client = HssClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(HssRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ListHostStatusRequest()
        request.enterprise_project_id = "<enterprise_project_id>"
        request.version = "<version>"
        request.agent_status = "<agent_status>"
        request.detect_result = "<detect_result>"
        request.host_name = "<host_name>"
        request.host_id = "<host_id>"
        request.host_status = "<host_status>"
        request.os_type = "<os_type>"
        request.private_ip = "<private_ip>"
        request.public_ip = "<public_ip>"
        request.ip_addr = "<ip_addr>"
        request.protect_status = "<protect_status>"
        request.group_id = "<group_id>"
        request.group_name = "<group_name>"
        request.has_intrusion = <HasIntrusion>
        request.policy_group_id = "<policy_group_id>"
        request.policy_group_name = "<policy_group_name>"
        request.charging_mode = "<charging_mode>"
        request.refresh = <Refresh>
        request.above_version = <AboveVersion>
        request.outside_host = <OutsideHost>
        request.asset_value = "<asset_value>"
        request.label = "<label>"
        request.server_group = "<server_group>"
        request.agent_upgradable = <AgentUpgradable>
        request.limit = <limit>
        request.offset = <offset>
        response = client.list_host_status(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    hss "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/hss/v5"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/hss/v5/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/hss/v5/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")

    auth := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        Build()

    client := hss.NewHssClient(
        hss.HssClientBuilder().
            WithRegion(region.ValueOf("<YOUR REGION>")).
            WithCredential(auth).
            Build())

    request := &model.ListHostStatusRequest{}
	enterpriseProjectIdRequest:= "<enterprise_project_id>"
	request.EnterpriseProjectId = &enterpriseProjectIdRequest
	versionRequest:= "<version>"
	request.Version = &versionRequest
	agentStatusRequest:= "<agent_status>"
	request.AgentStatus = &agentStatusRequest
	detectResultRequest:= "<detect_result>"
	request.DetectResult = &detectResultRequest
	hostNameRequest:= "<host_name>"
	request.HostName = &hostNameRequest
	hostIdRequest:= "<host_id>"
	request.HostId = &hostIdRequest
	hostStatusRequest:= "<host_status>"
	request.HostStatus = &hostStatusRequest
	osTypeRequest:= "<os_type>"
	request.OsType = &osTypeRequest
	privateIpRequest:= "<private_ip>"
	request.PrivateIp = &privateIpRequest
	publicIpRequest:= "<public_ip>"
	request.PublicIp = &publicIpRequest
	ipAddrRequest:= "<ip_addr>"
	request.IpAddr = &ipAddrRequest
	protectStatusRequest:= "<protect_status>"
	request.ProtectStatus = &protectStatusRequest
	groupIdRequest:= "<group_id>"
	request.GroupId = &groupIdRequest
	groupNameRequest:= "<group_name>"
	request.GroupName = &groupNameRequest
	hasIntrusionRequest:= <has_intrusion>
	request.HasIntrusion = &hasIntrusionRequest
	policyGroupIdRequest:= "<policy_group_id>"
	request.PolicyGroupId = &policyGroupIdRequest
	policyGroupNameRequest:= "<policy_group_name>"
	request.PolicyGroupName = &policyGroupNameRequest
	chargingModeRequest:= "<charging_mode>"
	request.ChargingMode = &chargingModeRequest
	refreshRequest:= <refresh>
	request.Refresh = &refreshRequest
	aboveVersionRequest:= <above_version>
	request.AboveVersion = &aboveVersionRequest
	outsideHostRequest:= <outside_host>
	request.OutsideHost = &outsideHostRequest
	assetValueRequest:= "<asset_value>"
	request.AssetValue = &assetValueRequest
	labelRequest:= "<label>"
	request.Label = &labelRequest
	serverGroupRequest:= "<server_group>"
	request.ServerGroup = &serverGroupRequest
	agentUpgradableRequest:= <agent_upgradable>
	request.AgentUpgradable = &agentUpgradableRequest
	limitRequest:= int32(<limit>)
	request.Limit = &limitRequest
	offsetRequest:= int32(<offset>)
	request.Offset = &offsetRequest
	response, err := client.ListHostStatus(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

200

Cloud server list

Error Codes

See Error Codes.