Help Center/ Workspace/ API Reference/ Workspace Application Streaming APIs/ Server Management/ Querying Specified Servers

Updated on 2026-05-21 GMT+08:00

Querying Specified Servers

Function

Queries whether the data of this API in the specified server is the same as that queried by list.

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:get

Read

server *

g:ResourceTag/<tag-key>

g:EnterpriseProjectId

-

-

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
workspace:server:get	Read	server *	g:ResourceTag/<tag-key> g:EnterpriseProjectId	-	-

URI

GET /v1/{project_id}/app-servers/{server_id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Unique ID of a project
server_id	Yes	String	Unique ID of a server.

Request Parameters

**Table 2** 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 3** Response body parameters
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. charging_mode Cloud server billing mode. 0: pay-per-use (postpaid) 1: yearly/monthly (prepaid) 2: spot price metering.order_id metering.product_id vpc_id EcmResStatus metering.image_id metering.imagetype metering.resourcespeccode image_name os_bit lockCheckEndpoint lockSource lockSourceId lockScene virtual_env_type metering.resourcetype os_type cascaded.instance_extrainfo __support_agent_list 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. vpc_id EcmResStatus metering.image_id metering.imagetype metering.resourcespeccode image_name os_bit lockCheckEndpoint lockSource lockSourceId lockScene virtual_env_type metering.resourcetype os_type cascaded.instance_extrainfo __support_agent_list 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.
addresses	Map<String,Array<ServerAddress>>	Server IP Address List.
root_volume	VolumeDetail object	System disk information.
data_volumes	Array of VolumeDetail objects	Data Volume Information.
security_groups	Array of ServerSecurityGroup objects	Server Security Group.

**Table 4** 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 5** FlavorLink
Parameter	Type	Description
rel	String	Shortcut link marker name.
hrel	String	Specifies the corresponding shortcut link.

**Table 6** 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 7** 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 8** 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 9** TmsTag
Parameter	Type	Description
key	String	Key. The value can contain a maximum of 128 Unicode characters. It can contain UTF-8 letters, digits, spaces, and the following characters: _ . : = + - @ The value cannot start or end with a space.
value	String	Value. The value can contain a maximum of 255 Unicode characters. It can contain UTF-8 letters, digits, spaces, and the following characters: _ . : = + - @

**Table 10** ServerAddress
Parameter	Type	Description
addr	String	IP address information.
version	String	IP address type: 4: IPv4 6: IPv6
OS-EXT-IPS-MAC:mac_addr	String	MAC address.
OS-EXT-IPS:port_id	String	ID of the port bound to the IP address.
OS-EXT-IPS:type	String	IP address assignment mode. The value is a case-insensitive string. fixed: private IP address floating: floating IP address

**Table 11** VolumeDetail
Parameter	Type	Description
encrypt_flag	String	Whether the disk is encrypted. 1 indicates yes and 0 indicates no.
kms_key	String	Key that is transferred when the disk is encrypted.
key_alias	String	Key that is transferred when the disk is encrypted.
type	String	ECS data disk type, which must be the same as that available in the system. Options: SATA SSD
size	Integer	Disk capacity (GB).
kms_grant_id	String	Authorization ID when the disk is encrypted.
device	String	Mount directory.
id	String	Unique ID of the disk table.
volume_id	String	Disk ID.
cluster_id	String	ID of the dedicated distributed storage pool.

**Table 12** ServerSecurityGroup
Parameter	Type	Description
id	String	Security group ID.
name	String	Security group name.

Status code: 400

**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: 401

**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: 403

**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: 404

**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: 405

**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: 500

**Table 18** 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 19** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Example Requests

None

Example Responses

Status code: 200

Response to a successful request.

{
  "id" : "222xx-xxxsdfsadf-xxx",
  "name" : "Testing server",
  "machine_name" : "testy-xxxxx01-china.test.com",
  "description" : "Test server.",
  "server_group_id" : "11111xx-xxxsdfsadf-xxxxxxx",
  "flavor" : {
    "id" : "asdfjkl-2131f-xxx-123123",
    "links" : [ {
      "rel" : "",
      "hrel" : ""
    } ]
  },
  "status" : "UNREGISTER",
  "create_time" : "2022-03-07T10:40:43.858Z",
  "update_time" : "2022-03-07T10:40:43.858Z",
  "image_id" : "xxx-xxx-xxx-xx",
  "availability_zone" : "",
  "domain" : "china.test.com",
  "ou_name" : "wksappusers",
  "sid" : "cc5279d6-xxxx-xx-xxx-b87a97cf02af",
  "instance_id" : "cc5279d6-xxxx-xx-xxx-b87a97cf02af",
  "os_version" : "",
  "os_type" : "Windows",
  "order_id" : "sdf2312-dfxxxx-sdfasdf-xxss",
  "maintain_status" : false,
  "scaling_auto_create" : false,
  "job_id" : "437415807337627690",
  "job_type" : "CREATE_SERVER",
  "job_status" : "WAITING",
  "job_time" : "2022-03-07T10:40:43.858Z",
  "resource_pool_id" : "cc5279d6-xxxx-xx-xxx-b87a97cf02af",
  "resource_pool_type" : "public",
  "host_id" : "cc5279d6-xxxx-xx-xxx-b87a97cf02af",
  "server_group_name" : "APS test server group",
  "product_info" : {
    "product_id" : "workspace.appstream.general.2xlarge.4",
    "flavor_id" : "c3.large.4",
    "type" : "BASE",
    "architecture" : "x86",
    "cpu" : 2,
    "cpu_desc" : "Application Streaming General-Purpose | 4 vCPUs | 8 GB memory",
    "memory" : 4096,
    "is_gpu" : false,
    "system_disk_type" : "SAS",
    "system_disk_size" : 80,
    "gpu_desc" : "GPU graphics acceleration",
    "descriptions" : "GPU graphics-accelerated DG4 | 32-core 128 GB memory 32 GB GPU memory | P02",
    "charge_mode" : 1,
    "contain_data_disk" : false,
    "resource_type" : "hws.resource.type.xxxx.vm",
    "cloud_service_type" : "hws.service.type.xxxxx",
    "volume_product_type" : "workspace",
    "sessions" : 2,
    "status" : "string",
    "cond_operation_az" : "cn-north-5a(normal),cn-north-5b(abandon),cn-north-5c(sellout)",
    "sub_product_list" : [ "xxx", "xxxx" ],
    "domain_ids" : [ "xxx", "xxxx" ],
    "package_type" : "general",
    "expire_time" : "2022-03-07T10:40:43Z",
    "support_gpu_type" : "A40"
  },
  "metadata" : {
    "charging_mode" : 0
  },
  "session_count" : 10,
  "vm_status" : "BUILD",
  "task_status" : "scheduling",
  "freeze" : [ {
    "effect" : 1,
    "scene" : "ARREAR"
  } ],
  "host_address" : [ {
    "addr" : "127.*.*.1",
    "version" : 4,
    "OS-EXT-IPS-MAC:mac_addr" : "C8-XX-XX-XX-XX-57",
    "OS-EXT-IPS:type" : "fixed",
    "OS-EXT-IPS:port_id" : "4b5fe243-2f5f-4c68-9eb2-8af3a5366666",
    "vpc_id" : "3bb2b656-0b79-4975-b870-a407f19038bb",
    "subnet_id" : "0785eeba-bfbb-4da3-94f9-d311c792e875",
    "tenant_type" : "tenant"
  } ],
  "enterprise_project_id" : "0",
  "tags" : [ {
    "key" : "demo01",
    "value" : "01"
  } ],
  "addresses" : {
    "additionalProp1" : [ {
      "addr" : "127.*.*.1",
      "version" : 4,
      "OS-EXT-IPS-MAC:mac_addr" : "C8-XX-XX-XX-XX-57",
      "OS-EXT-IPS:type" : "fixed",
      "OS-EXT-IPS:port_id" : "4b5fe243-2f5f-4c68-9eb2-8af3a5366666"
    } ],
    "additionalProp2" : [ {
      "addr" : "127.*.*.1",
      "version" : 4,
      "OS-EXT-IPS-MAC:mac_addr" : "C8-XX-XX-XX-XX-57",
      "OS-EXT-IPS:type" : "fixed",
      "OS-EXT-IPS:port_id" : "4b5fe243-2f5f-4c68-9eb2-8af3a5366666"
    } ],
    "additionalProp3" : [ {
      "addr" : "127.*.*.1",
      "version" : 4,
      "OS-EXT-IPS-MAC:mac_addr" : "C8-XX-XX-XX-XX-57",
      "OS-EXT-IPS:type" : "fixed",
      "OS-EXT-IPS:port_id" : "4b5fe243-2f5f-4c68-9eb2-8af3a5366666"
    } ]
  },
  "root_volume" : {
    "encrypt_flag" : 0,
    "kms_key" : "HJSADFHJKQWERVSADFSADF...",
    "key_alias" : "ADDJFKLJEWKLRJWKR4...",
    "type" : "SSD",
    "size" : 10,
    "kms_grant_id" : "adf123-123fgasdfxxxx-123sadasdf",
    "device" : "\tmp\test",
    "id" : "sdfasdf123-123asdfxxxxxxx-213adf",
    "volume_id" : "3213-df1234adsfxxxxxx-asdfsadf",
    "cluster_id" : "c950ee97-587c-4f24-8a74-3367e3da570f"
  },
  "data_volumes" : [ {
    "encrypt_flag" : 0,
    "kms_key" : "HJSADFHJKQWERVSADFSADF...",
    "key_alias" : "ADDJFKLJEWKLRJWKR4...",
    "type" : "SSD",
    "size" : 10,
    "kms_grant_id" : "adf123-123fgasdfxxxx-123sadasdf",
    "device" : "\tmp\test",
    "id" : "sdfasdf123-123asdfxxxxxxx-213adf",
    "volume_id" : "3213-df1234adsfxxxxxx-asdfsadf",
    "cluster_id" : "c950ee97-587c-4f24-8a74-3367e3da570f"
  } ],
  "security_groups" : [ {
    "id" : "30789daf-e1c7-40ae-a3bc-11c84a8e5bb8",
    "name" : ""
  } ]
}

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

Previous topic: Updating Virtual Session IP Configurations on the Server in Batches

Next topic: Deleting a Server

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

For any further questions, feel free to contact us through the chatbot.

Chatbot