Help Center/ CodeArts Deploy/ API Reference/ APIs/ Managing Host Clusters/ Querying a Host Cluster List (Recommended)
Updated on 2025-05-27 GMT+08:00

Querying a Host Cluster List (Recommended)

Function

This API is used to query a host cluster list by specified criteria.

Calling Method

For details, see Calling APIs.

URI

GET /v1/resources/host-groups

Table 1 Query Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Parameter description:

Project ID. For details, see [Obtaining a Project ID] (CloudDeploy_api_0014.xml).

Constraints:

N/A

Value range:

The value consists of 32 characters. Only letters and digits are allowed.

Default value:

N/A

name

No

String

Parameter description:

Keyword in the host cluster name.

Constraints:

N/A

Value range:

The value consists of 3-128 characters. Only letters, digits, hyphens (-), underscores (_), and periods (.) are allowed.

Default value:

N/A

os

No

String

Parameter description:

OS of the host cluster.

Constraints:

N/A

Value range:

  • Windows: Windows OS.

  • Linux: Linux OS.

Default value:

N/A

page_index

No

Integer

Parameter description:

Page number for pagination query.

Constraints:

N/A

Value range:

1-2,147,483,647

Default value:

1

page_size

No

Integer

Parameter description:

Number of items displayed on each page.

Constraints:

N/A

Value range:

1-1,000

Default value:

1,000

sort_field

No

String

Parameter description:

Sorting field query.

Constraints:

N/A

Value range:

  • nick_name: Nickname.

  • name: Host cluster name.

Default value:

N/A

sort_type

No

String

Parameter description:

Sorting order.

Constraints:

N/A

Value range:

  • desc: Descending order.

  • asc: Ascending order.

Default value:

desc

is_proxy_mode

No

Integer

Parameter description:

Whether the host cluster is in the proxy mode.

Constraints:

N/A

Value range:

  • 0: Non-proxy mode host cluster.

  • 1: Proxy mode host cluster.

Default value:

N/A

slave_cluster_id

No

String

Parameter description:

Transfer default to query host clusters using the official resource pool. Transfer a self-hosted resource pool ID to query host clusters using the self-hosted resource pool.

Constraints:

N/A

Value range:

The value consists of 32 characters. Only letters and digits are allowed. Or default is transferred to query the host clusters using the official resource pool.

Default value:

N/A

Request Parameters

Table 2 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.

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

status

String

Parameter description:

Request success or failure status.

Value range:

  • success: Request succeeded

  • failed: Request failed

total

Integer

Parameter description:

Number of host clusters.

Value range:

0-1,000

result

Array of HostClusterInfo objects

Parameter description:

Host cluster list.

Constraints:

The number of host clusters cannot exceed 1,000.

Table 4 HostClusterInfo

Parameter

Type

Description

id

String

Parameter description:

Host cluster ID.

Value range:

The value consists of 32 characters. Only letters and digits are allowed.

host_count

Integer

Parameter description:

Number of hosts in a cluster.

Value range:

0-200

name

String

Parameter description:

Host cluster name.

Value range:

The value consists of 3-128 characters. Only letters, digits, hyphens (-), underscores (_), and periods (.) are allowed.

project_id

String

Parameter description:

Project ID. For details, see [Obtaining a Project ID] (CloudDeploy_api_0014.xml).

Value range:

The value consists of 32 characters. Only letters and digits are allowed.

os

String

Parameter description:

OS of the host cluster.

Value range:

  • Windows: Windows OS.

  • Linux: Linux OS.

slave_cluster_id

String

Parameter description:

Self-hosted resource pool ID.

Value range:

The value consists of 32 characters. Only letters and digits are allowed.

description

String

Parameter description:

Host cluster description.

Value range:

The value is a string of 0 to 500 characters.

permission

PermissionClusterDetail object

Parameter description:

Host cluster permission information.

Constraints:

N/A

nick_name

String

Parameter description:

User nickname.

Value range:

The value is a string of 1 to 30 characters.

env_count

Integer

Parameter description:

Number of environments associated with a host cluster.

Value range:

0-200

is_proxy_mode

Integer

Parameter description:

Whether the host cluster is in the proxy mode.

Constraints:

N/A.

Value range:

  • 0: Non-proxy mode host cluster.

  • 1: Proxy mode host cluster.

    Default value:

    N/A

Table 5 PermissionClusterDetail

Parameter

Type

Description

can_view

Boolean

Parameter description:

Whether a user has the view permission.

Value range:

  • true: With the view permission

  • false: Without the view permission

can_edit

Boolean

Parameter description:

Whether a user has the edit permission.

Value range:

  • true: With the edit permission

  • false: Without the edit permission

can_delete

Boolean

Parameter description:

Whether a user has the delete permission.

Value range:

  • true: With the delete permission

  • false: Without the delete permission

can_add_host

Boolean

Parameter description:

Whether a user has the permission to add hosts

Value range:

  • true: With the permission to add hosts

  • false: Without the permission to add hosts

can_manage

Boolean

Parameter description:

Whether a user has permission to manage the host cluster permission matrix

Value range:

  • true: With the permission to manage the host cluster permission matrix

  • false: Without the permission to manage the host cluster permission matrix

can_copy

Boolean

Parameter description:

Whether the user has permission to clone hosts.

Value range:

  • true: The user has permission to copy hosts.

  • false: The user does not have permission to copy hosts.

Example Requests

https://{endpoint}/v1/resources/host-groups?project_id=5d091b14d7f54a139db644092fdc415c&page_index=1&page_size=10&sort_field=name&sort_type=asc

Example Responses

Status code: 200

OK: The request is successful.

{
  "status" : "success",
  "total" : 1,
  "result" : [ {
    "name" : "testwyk",
    "description" : "11122211",
    "os" : "linux",
    "nick_name" : "A/B Side Account",
    "id" : "ab7647b0863c4e969c8949d38d591339",
    "project_id" : "6039d4480efc4dddb178abff98719913",
    "permission" : {
      "can_view" : true,
      "can_edit" : true,
      "can_delete" : true,
      "can_add_host" : true,
      "can_manage" : true,
      "can_copy" : true
    },
    "host_count" : 1,
    "env_count" : 1,
    "is_proxy_mode" : 1,
    "slave_cluster_id" : ""
  } ]
}

Status Codes

Status Code

Description

200

OK: The request is successful.

Error Codes

See Error Codes.