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 |
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 |
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:
Default Value N/A |
agent_status |
No |
String |
Definition Agent status. Constraints N/A Range The agent statuses are divided into two types:
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:
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 Server ID. 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:
Default Value N/A |
os_type |
No |
String |
Definition OS type. Constraints N/A Range The options are as follows:
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 |
Server public IP address |
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:
Default Value N/A |
group_id |
No |
String |
Server group ID |
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 |
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
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
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:
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 |
Parameter description: Number of records displayed on each page. Constraints: N/A Options: Value range: 10-200 Default value: 10 |
Request 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
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 |
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:
|
agent_status |
String |
Definition Agent status. Range The options are as follows:
|
install_result_code |
String |
Definition Installation result. Range The options are as follows:
|
version |
String |
Definition Enabled HSS edition. Range The options are as follows:
|
protect_status |
String |
Definition Protection status. Range The options are as follows:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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 } ] }
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 |
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"); String projectId = "{project_id}"; ICredential auth = new BasicCredentials() .withProjectId(projectId) .withAk(ak) .withSk(sk); HssClient client = HssClient.newBuilder() .withCredential(auth) .withRegion(HssRegion.valueOf("<YOUR REGION>")) .build(); ListHostStatusRequest request = new ListHostStatusRequest(); 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 |
# 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"] projectId = "{project_id}" credentials = BasicCredentials(ak, sk, projectId) client = HssClient.new_builder() \ .with_credentials(credentials) \ .with_region(HssRegion.value_of("<YOUR REGION>")) \ .build() try: request = ListHostStatusRequest() 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 |
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") projectId := "{project_id}" auth := basic.NewCredentialsBuilder(). WithAk(ak). WithSk(sk). WithProjectId(projectId). Build() client := hss.NewHssClient( hss.HssClientBuilder(). WithRegion(region.ValueOf("<YOUR REGION>")). WithCredential(auth). Build()) request := &model.ListHostStatusRequest{} 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 |
Request succeeded. |
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