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
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
project_id |
Yes |
String |
Project ID. Minimum: 1 Maximum: 256 |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
enterprise_project_id |
No |
String |
Enterprise project ID. To query all enterprise projects, set this parameter to all_granted_eps. Default: 0 Minimum: 1 Maximum: 256 |
version |
No |
String |
HSS edition. Its value can be:
Minimum: 1 Maximum: 64 |
agent_status |
No |
String |
Agent status. Its value can be:
Minimum: 1 Maximum: 20 |
detect_result |
No |
String |
Detection result. Its value can be:
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:
Minimum: 1 Maximum: 32 |
os_type |
No |
String |
OS type. Its value can be:
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:
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:
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:
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 on each page Minimum: 0 Maximum: 200 Default: 10 |
offset |
No |
Integer |
Offset, which specifies the start position of the record to be returned. Minimum: 0 Maximum: 2000000 Default: 0 |
Request 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
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 |
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:
Minimum: 1 Maximum: 32 |
agent_status |
String |
Agent status. Its value can be:
Minimum: 1 Maximum: 32 |
install_result_code |
String |
Installation result. Its value can be:
Minimum: 1 Maximum: 32 |
version |
String |
HSS edition. Its value can be:
Minimum: 1 Maximum: 32 |
protect_status |
String |
Protection status. Its value can be:
Minimum: 1 Maximum: 32 |
os_image |
String |
System disk image Minimum: 0 Maximum: 128 |
os_type |
String |
OS type. Its value can be:
Minimum: 0 Maximum: 128 |
os_bit |
String |
OS bit version Minimum: 0 Maximum: 128 |
detect_result |
String |
Server scan result. Its value can be:
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:
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 vulnerabilities, including Linux, Windows, Web-CMS, 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:
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:
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:
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 57 |
# coding: utf-8 import os 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 = os.environ["CLOUD_SDK_AK"] sk = os.environ["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.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot