Help Center/ Workspace/ API Reference/ Workspace Application Streaming APIs/ Server Management/ Querying Servers
Updated on 2026-05-21 GMT+08:00
View PDF
Share

Querying Servers

Function

Queries servers.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    workspace:server:list

    List

    server *

    -

    -

    -

URI

GET /v1/{project_id}/app-servers

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Unique ID of a project
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

offset

No

Integer

Query offset. The default value is 0.

limit

No

Integer

Number of records to be queried. The value ranges from 1 to 100. The default value is 10.

server_group_id

No

String

Unique ID of a server group.

server_name

No

String

Server name. Fuzzy match is supported.

machine_name

No

String

Server name. Fuzzy match is supported.

ip_addr

No

String

IP address. Fuzzy match is supported.

server_id

No

String

Unique ID of a server.

maintain_status

No

String

Server maintenance status. Options:

true: in maintenance

false: not in maintenance

scaling_auto_create

No

String

Whether to enable creation through auto-scaling:

true: enable

false: disable

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

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 the user token.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

count

Integer

Total number.

items

Array of AppServer objects

The maximum number of records in the returned server list is the maximum number of records on each page.
Table 5 AppServer

Parameter

Type

Description

id

String

Unique ID of an APS instance.

name

String

Server.

machine_name

String

Computer Name.

description

String

Description.

server_group_id

String

Server group ID.

flavor

Flavor object

Server Specifications Details.

status

String

Instance statuses

  • UNREGISTER - Not ready

  • REGISTERED - Ready state

  • MAINTAINING: being maintained

  • FREEZE - Frozen

  • STOPPED - Stop

  • NONE - Abnormal status.

create_time

String

Time when the server is created.

update_time

String

Updated.

image_id

String

Image ID.

availability_zone

String

Server Availability Zone.

domain

String

Domain.

ou_name

String

Organization Name.

sid

String

SID of the instance.

instance_id

String

Instance ID.

os_version

String

Server System Version.

os_type

String

Specifies the OS type. Currently, only Windows is supported.

  • Linux

  • Windows

  • Other.

order_id

String

Order ID of a duration-based product.

maintain_status

Boolean

Server maintenance status.

  • true: in maintenance

  • false: not in maintenance

scaling_auto_create

Boolean

Instance automatically created by the service when an auto scaling policy is configured.

  • true: created through auto scaling

  • false: created not through auto scaling

job_id

String

ID of the job executed last time.

job_type

String

Type of the job that is executed last time.

job_status

String

Execution result of the last job.

job_time

String

Time when a job is executed last time.

resource_pool_id

String

Specifies the resource pool ID.

resource_pool_type

String

Resource pool type. Options:

  • private: private resource pool

  • public: working resource pool

host_id

String

Specifies the DeH ID.

server_group_name

String

ECS group name.

product_info

ProductInfo object

Product Details.

metadata

Map<String,String>

[ECS metadata.

  1. charging_mode

Cloud server billing mode.

0: pay-per-use (postpaid)

1: yearly/monthly (prepaid) 2: spot price

  1. metering.order_id

  2. metering.product_id

  3. vpc_id

  4. EcmResStatus

  5. metering.image_id

  6. metering.imagetype

  7. metering.resourcespeccode

  8. image_name

  9. os_bit

  10. lockCheckEndpoint

  11. lockSource

  12. lockSourceId

  13. lockScene

  14. virtual_env_type

  15. metering.resourcetype

  16. os_type

  17. cascaded.instance_extrainfo

  18. __support_agent_list

  19. agency_name

Order ID of a yearly/monthly cloud server.

Product ID of a yearly/monthly cloud server.

ID of the VPC where the cloud server is located.

Cloud server freezing status.

  • normal: The cloud server is not frozen.

  • freeze: The cloud server is frozen.

NOTE:
When a cloud server is frozen or unfrozen, this field is automatically added and mandatory.virtual_env_type cannot be added, deleted, or modified by users.When a cloud server is frozen or unfrozen, this field is automatically added and mandatory.virtual_env_type cannot be added, deleted, or modified by users.

Image ID corresponding to the cloud server OS.

Image type. Options:

  • gold: public image

  • private: private image

  • shared: shared image

Resource specifications of the cloud server.

Image name corresponding to the cloud server OS.

OS architecture, 32-bit or 64-bit.

Callback URL for checking whether ECS locking is valid.

  • If ECS locking is valid, the ECS is locked.

  • If ECS locking is invalid, the invalid locks are deleted.

Source service of ECS. Order locking (ORDER).

Source ID of an ECS lock. If lockSource is set to ORDER, lockSourceId is the order ID.

ECS lock type.

  • Pay-per-use is changed to yearly/monthly (TO_PERIOD_LOCK).

  • If a VM is created using an iOS image, the value of virtual_env_type is IsoImage.

  • If a VM is created using a non-iOS image, virtual_env_type is not added to the VM created in versions later than 19.5.0. VMs of earlier versions may return FusionCompute for virtual_env_type.

Resource type of the cloud server.

OS type. The value can be Linux or Windows.

Extended information about VMs in the system.

Whether cloud servers support Host Security Service (HSS) and host monitoring.

  • hss: HSS

  • ces: host monitoring

Agency name.

An agency is created by a tenant administrator on Identity and Access Management (IAM) to provide temporary credentials for ECSs to access cloud services.](tag:HW)

[ECS metadata.

  1. vpc_id

  2. EcmResStatus

  3. metering.image_id

  4. metering.imagetype

  5. metering.resourcespeccode

  6. image_name

  7. os_bit

  8. lockCheckEndpoint

  9. lockSource

  10. lockSourceId

  11. lockScene

  12. virtual_env_type

  13. metering.resourcetype

  14. os_type

  15. cascaded.instance_extrainfo

  16. __support_agent_list

  17. agency_name

ID of the VPC where the cloud server is located.

Cloud server freezing status.

  • normal: The cloud server is not frozen.

  • freeze: The cloud server is frozen.

Image ID corresponding to the cloud server OS.

Image type. Options:

  • gold: public image

  • private: private image

  • shared: shared image

Resource specifications of the cloud server.

Image name corresponding to the cloud server OS.

OS architecture, 32-bit or 64-bit.

Callback URL for checking whether ECS locking is valid.

  • If ECS locking is valid, the ECS is locked.

  • If ECS locking is invalid, the invalid locks are deleted.

Source service of ECS.

Source ID of an ECS lock.

ECS lock type.

  • If a VM is created using an iOS image, the value of virtual_env_type is IsoImage.

  • If a VM is created using a non-iOS image, virtual_env_type is not added to the VM created in versions later than 19.5.0. VMs of earlier versions may return FusionCompute for virtual_env_type.

Resource type of the cloud server.

OS type. The value can be Linux or Windows.

Extended information about VMs in the system.

Whether cloud servers support Host Security Service (HSS) and host monitoring.

  • hss: HSS

  • ces: host monitoring

Agency name.

An agency is created by a tenant administrator on Identity and Access Management (IAM) to provide temporary credentials for ECSs to access cloud services.](tag:HCS)

session_count

Integer

Sessions.

vm_status

String

Indicates the server status. If the current status is unstable, the value of this field may be null when a task is in progress.

task_status

String

Indicates the server task status. If the current status is stable, the value of this field may be null if no task is in progress.

freeze

Array of CbcFreezeInfo objects

Frozen information.

host_address

Array of EcsNetWork objects

VPC and subnet information.

enterprise_project_id

String

Enterprise project ID. This parameter is returned only for enterprise projects.

tags

Array of TmsTag objects

Tag information.
Table 6 Flavor

Parameter

Type

Description

id

String

Specifies the flavor ID of the server.

links

Array of FlavorLink objects

Specifies the shortcut link of the server flavor.
Table 7 FlavorLink

Parameter

Type

Description

rel

String

Shortcut link marker name.

hrel

String

Specifies the corresponding shortcut link.
Table 8 ProductInfo

Parameter

Type

Description

product_id

String

Product ID.

flavor_id

String

Specification ID.

type

String

Product type:

BASE: basic product package. The package image does not contain other commercial software products except the OS. Only this type of package can be used for private images.

ADVANCED: advanced product package. The package image contains some commercial software products.

architecture

String

Product architecture. Currently, only x86 is supported.

  • x86

  • arm.

cpu

String

CPU.

cpu_desc

String

CPU Description.

memory

String

Memory size, in MB.

is_gpu

Boolean

Specifies whether the flavor is of the GPU type.

system_disk_type

String

System disk type.

  • SSD: ultra-high I/O disk

  • SAS: high I/O disk

system_disk_size

String

System Volume Size.

gpu_desc

String

GPU Description.

descriptions

String

Description.

charge_mode

String

Package ID.

  • 1: Yearly/Monthly.

  • 0: indicates pay-per-use.

contain_data_disk

Boolean

Specifies whether data disks are included in the package charging.

resource_type

String

Resource type.

-hws.resource.type.workspace.volume: Workspace desktop disk

-hws.resource.type.workspace.desktop: Workspace desktop

-hws.resource.type.workspace.appstream: Workspace Application Streaming

-hws.resource.type.workspace.appstreamsession: Workspace Application Streaming multi-session

cloud_service_type

String

Cloud service type.

  • hws.service.type.vdi

  • hws.service.type.marketplace

volume_product_type

String

Disk type.

  • workspace

sessions

Integer

Maximum number of sessions supported by a package by default.

status

String

Status of a product package in sales mode. The value comes from cond:operation:status of the ECS.

If this parameter is not set, the product is in the normal state.

  • normal: normal commercial use

  • abandon: offline (not displayed)

  • sellout - sold out

  • obt - OBT

  • obt_sellout - OBT sold out

  • promotion: recommended (equivalent to normal, also for commercial use)

cond_operation_az

String

Status of a product package in an AZ. This parameter is used together with status.

NOTE:

  • This parameter takes effect AZ-wide. If an AZ is not configured in this parameter, the value of the parameter status is used by default. Otherwise, this parameter is used.

  • Format: az(xx). The value in parentheses is the flavor status of the AZ. If the parentheses are left blank, the configuration is invalid.

  • For example, a package is in commercial use in AZ 0 and AZ 3, sold out in AZ 1, in OBT in AZ 2, and out of service in other AZs. Then, configure parameters as follows:

  • status: abandon

  • "cond_operation_az": az0(normal), az1(sellout), az2(obt), az3(normal)

  • Note: This parameter is mandatory if the flavor status in an AZ is different from the configured status.

sub_product_list

Array of strings

Subproducts of DeHs.

domain_ids

Array of strings

Dedicated domainId of the product.

package_type

String

Package type:

  • general: general package

  • dedicated: dedicated host package

expire_time

String

Expiration time of the product package. The product will be gradually brought offline after the expiration time.

support_gpu_type

String

GPU types supported by the product package.

  • A30

  • A40

  • A100

  • RTX5000
Table 9 CbcFreezeInfo

Parameter

Type

Description

effect

Integer

Expected result of freezing or unfreezing the cloud service:

1: Resources are frozen but can be released. (After resources are frozen, the user can manually delete or release the resources and delete the data.)

2: Resources are frozen and cannot be released. (After resources are frozen, the user cannot manually delete or release the resources or delete the data. After the resources are unfrozen, the user can delete or modify their data.)

3: Resources are frozen and cannot be renewed. (After resources are frozen, they cannot be renewed until they are unfrozen.)

  • The parameter effect is used together with the parameter status (1: freezing; 0: unfreezing).

  • If this parameter is left empty, the default value is 1, when the cloud service APIs must be compatible with existing APIs.

  • Note: Cloud services restrict operations/APIs based on status and effect, not based on scene, which is used for tips and API error codes on the console.

scene

String

Updates a cloud service scenario. Options: ARREAR (default): Service is in arrears, including yearly/monthly resource expiration and pay-per-use billing failure. POLICE: Service is frozen due to public security. ILLEGAL: Service is frozen due to violation of laws and regulations. VERIFY: Service is frozen because the user has not completed real-name authentication. PARTNER: Service is frozen by partners (their customer resources).
Table 10 EcsNetWork

Parameter

Type

Description

addr

String

IP address.

version

Integer

IP address type.

4: IPV4

6: IPV6

OS-EXT-IPS-MAC:mac_addr

String

MAC address.

OS-EXT-IPS:type

String

IP address assignment method. The value is a case-insensitive string.

fixed: private IP address

floating: floating IP address

OS-EXT-IPS:port_id

String

ID of the port bound to the IP address.

vpc_id

String

VPC ID.

subnet_id

String

Subnet ID.

tenant_type

String

Tenant Type:

  • tenant: tenant

  • resource_tenant: resource tenant
Table 11 TmsTag

Parameter

Type

Description

key

String

Key. The value can contain a maximum of 128 Unicode characters.

  1. It can contain UTF-8 letters, digits, spaces, and the following characters: _ . : = + - @

  2. The value cannot start or end with a space.

value

String

Value. The value can contain a maximum of 255 Unicode characters.

  1. It can contain UTF-8 letters, digits, spaces, and the following characters: _ . : = + - @

Status code: 400

Table 12 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 401

Table 13 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 403

Table 14 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 404

Table 15 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 405

Table 16 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 500

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 503

Table 18 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Example Requests

GET /v1/a4da8115c9d8464ead3a38309130523f/app-servers?offset=0&limit=10

Example Responses

Status code: 200

Response to a successful request.

{
  "count" : 1,
  "items" : [ {
    "id" : "573548db-9a6f-4b31-a5cb-d7aa40975466",
    "name" : "APS-20230509102837-IVTU6S27OY",
    "machine_name" : "APS-PR6KRMAL00",
    "description" : "",
    "server_group_id" : "a0890780-7ef2-4aaf-b56d-b25fb53b717e",
    "flavor" : {
      "id" : "s2.large.2",
      "links" : [ {
        "rel" : "self"
      }, {
        "rel" : "bookmark"
      } ]
    },
    "status" : "REGISTERED",
    "create_time" : "2023-05-09T10:28:38.755Z",
    "update_time" : "2023-05-09T10:39:03.484Z",
    "image_id" : "ca8be629-112e-4865-b4fb-bbbca257f1d9",
    "availability_zone" : "cn-north-7a",
    "domain" : "wksapp***.huawei.com",
    "ou_name" : "",
    "sid" : "S-1-5-21-1213649063-4191095369-2401105760-1399",
    "instance_id" : "4fa75b74-56bc-4a6b-b965-f2f139e17b5e",
    "os_version" : "Windows Server 2019 Datacenter 64bit",
    "os_type" : "Windows",
    "order_id" : "",
    "maintain_status" : false,
    "scaling_auto_create" : false,
    "resource_pool_id" : "10dd1a4f-ff85-4953-aa0f-2a37f28b6beb",
    "resource_pool_type" : "private",
    "server_group_name" : "Nas",
    "product_info" : {
      "product_id" : "workspace.appstream.general.xlarge.2",
      "flavor_id" : "s2.large.2",
      "type" : "BASE",
      "architecture" : "x86",
      "cpu" : "2",
      "memory" : "4096",
      "is_gpu" : false,
      "system_disk_type" : "SAS",
      "system_disk_size" : "80",
      "descriptions" : "s2.large.2 Cloud Application General-Purpose | 2 vCPUs | 4 GB memory",
      "charge_mode" : "0",
      "contain_data_disk" : false,
      "resource_type" : "hws.resource.type.workspace.appstream",
      "cloud_service_type" : "hws.service.type.vdi",
      "volume_product_type" : "workspace",
      "sessions" : 1,
      "status" : "abandon"
    },
    "metadata" : {
      "charging_mode" : "0",
      "metering.resourcespeccode" : "s2.large.2.win",
      "metering.resourcetype" : "1"
    },
    "session_count" : 1,
    "vm_status" : "ACTIVE",
    "task_status" : "null",
    "freeze" : [ ],
    "host_address" : [ {
      "addr" : "192.*.*.145",
      "version" : 4,
      "OS-EXT-IPS-MAC:mac_addr" : "fa:16:**:**:75:06",
      "OS-EXT-IPS:type" : "FIXED",
      "OS-EXT-IPS:port_id" : "257f2ff5-fe85-4b9a-86c2-5dacb64ac78f",
      "vpc_id" : "59785ba5-e5d5-4836-b9de-19f22ac15175",
      "subnet_id" : "a5842cb4-5718-4b0a-8b27-3a3e9c74f977",
      "tenant_type" : "tenant"
    }, {
      "addr" : "10.*.*.79",
      "version" : 4,
      "OS-EXT-IPS-MAC:mac_addr" : "fa:16:**:**:02:88",
      "OS-EXT-IPS:type" : "FIXED",
      "OS-EXT-IPS:port_id" : "c6fc6fcc-c99e-4604-b0e0-04e48246c7cd",
      "vpc_id" : "82f75215-9ae6-4e69-882c-fe4088324839",
      "subnet_id" : "e851a83c-8696-48ea-b078-466fe9d361ae",
      "tenant_type" : "resource_tenant"
    } ]
  } ]
}

Status Codes

Status Code

Description

200

Response to a successful request.

400

The request cannot be understood by the server due to malformed syntax.

401

Authentication failed.

403

Permissions required.

404

No resources found.

405

The request method is not allowed.

500

An internal service error occurred. For details, see the error code description.

503

Service unavailable.

Error Codes

See Error Codes.

Parent topic: Server Management