Help Center> CodeArts Deploy> API Reference> APIs> Host Management> Querying a Host List (Recommended)

Updated on 2023-09-21 GMT+08:00

View PDF

Querying a Host List (Recommended)

Function

This API is used to query host list in a specified host cluster of a specified ID.

URI

GET /v1/resources/host-groups/{group_id}/hosts

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
group_id	Yes	String	Project ID. Minimum: 32 Maximum: 32

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
key_field	No	String	Fuzzy search information about the host name. Minimum: 1 Maximum: 256
environment_id	No	String	Environment ID. Minimum: 32 Maximum: 32
page_index	No	Integer	Page number. Minimum: 0
page_size	No	Integer	Number of items displayed on each page. The default value is 10. Minimum: 1 Maximum: 1000
sort_key	No	String	Sorting field: as_proxy\|host_name\|owner_name. If this parameter is left blank, the default sorting mode is used.
sort_dir	No	String	Sorting mode: DESC and ASC. The default value is DESC. Enumeration values: DESC ASC
as_proxy	No	Boolean	Whether a proxy host is used.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It can be obtained by calling an IAM API. The value of X-Subject-Token in the response header is the user token. Minimum: 0 Maximum: 20000

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
total	Integer	Host quantity. Minimum: 0 Maximum: 200
status	String	Request status.
result	Array of HostInfo objects	Host information list. Array Length: 0 - 200

**Table 5** HostInfo
Parameter	Type	Description
uuid	String	Host ID.
ip	String	Host IP address.
os	String	Host OS.
port	Integer	Port.
authorization	HostAuthorizationBody object	Log in to the host for authentication by password or key.
permission	PermissionHostDetailNew object	Host-related permission details.
host_name	String	Host name.
as_proxy	Boolean	Whether a proxy host is used.
group_id	String	Host cluster ID.
proxy_host_id	String	Proxy ID.
owner_id	String	Host owner ID.
owner_name	String	Host owner name.
proxy_host	HostInfo object	Proxy details.
connection_status	String	Connectivity status.
create_time	String	Creation time.
lastest_connection_time	String	Last connection time.
connection_result	String	Connectivity verification result.
nick_name	String	Host owner alias.
import_status	String	Import status.
env_count	Integer	Number of associated environments.

**Table 6** HostAuthorizationBody
Parameter	Type	Description
username	String	Username. The value can contain letters, digits, and hyphens (-). Minimum: 3 Maximum: 128
password	String	Password. When the authentication type is 0, the password is mandatory.
private_key	String	Key. When the authentication type is 1, the key is mandatory. Minimum: 1 Maximum: 5000
trusted_type	Integer	Authentication type. 0 indicates password authentication, and 1 indicates key authentication. Enumeration values: 0 1

**Table 7** PermissionHostDetailNew
Parameter	Type	Description
can_view	Boolean	Whether you have the view permission.
can_edit	Boolean	Whether you have the edit permission.
can_delete	Boolean	Whether you have the deletion permission.
can_add_host	Boolean	Whether you have the permission to add hosts.
can_copy	Boolean	Specifies whether the user has the permission to copy hosts.

Example Requests

https://{endpoint}/v1/resources/host-groups/317aea99cf2944fcacf88b34ef771843/hosts?page_index=1&page_size=10&sort_key=host_name&sort_dir=ASC&as_proxy=false

Example Responses

Status code: 200

OK: The request is successful.

{
  "result" : [ {
    "host_name" : "100.101.28.203",
    "ip" : "100.101.28.203",
    "port" : 22,
    "os" : "linux",
    "authorization" : {
      "username" : "root",
      "password" : null,
      "private_key" : null,
      "trusted_type" : 0
    },
    "permission" : {
      "can_view" : true,
      "can_edit" : true,
      "can_delete" : true,
      "can_add_host" : true,
      "can_copy" : true
    },
    "uuid" : "2cc913cc9a494f09b7320801ebacad02",
    "group_id" : "ab7647b0863c4e969c8949d38d591339",
    "as_proxy" : false,
    "proxy_host_id" : "",
    "owner_id" : "6baa7454109d47c192f22078fe6cda20",
    "owner_name" : "devcloud_devcloud_l00490255_01",
    "connection_status" : "success",
    "create_time" : "2021-04-15 11:01:51",
    "connection_result" : "Connection succeeded",
    "lastest_connection_time" : "2021-04-15 11:02:00",
    "nick_name" : "A-B Side Account",
    "proxy_host" : null,
    "import_status" : null,
    "env_count" : 1
  } ],
  "total" : 1,
  "status" : "success"
}