# 查询桌面列表 - ListDesktops
#### 功能介绍
该接口用于查询桌面虚拟机列表。
#### 调试
您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/Workspace/doc?api=ListDesktops)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
#### 授权信息
账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。
- 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-workspace/workspace_09_0128.html)。
- 如果使用身份策略授权，需具备如下身份策略权限。
  
  | 授权项                     | 访问级别 | 资源类型（\*为必须） | 条件键                                                                                                                                                                                                                                                                                                                                                                                                                                                      | 别名 | 依赖的授权项 |
  |:---|:---|:---|:---|:---|:---|
  | workspace:desktops:list | List | desktop \*  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -  | -      |
  | workspace:desktops:list | List | -           | - g:RequestTag/\<tag-key\>   - g:TagKeys   - g:EnterpriseProjectId    | -  | -      |
     
  
 
#### URI
GET /v2/{project_id}/desktops
表1路径参数 
| 参数         | 是否必选 | 参数类型   | 描述    |
|:---|:---|:---|:---|
| project_id | 是    | String | 项目ID。 |
   
表2Query参数 
| 参数                    | 是否必选 | 参数类型             | 描述                                                                                                                                                                                                                                                                                                                                                                                    |
|:---|:---|:---|:---|
| user_name             | 否    | Array of strings | 桌面所属用户，支持根据用户名模糊查询。                                                                                                                                                                                                                                                                                                                                                                   |
| computer_name         | 否    | String           | 桌面名。                                                                                                                                                                                                                                                                                                                                                                                  |
| desktop_ip            | 否    | String           | 桌面IP地址。                                                                                                                                                                                                                                                                                                                                                                               |
| offset                | 否    | Integer          | 用于分页查询，查询的起始记录序号，从0开始。                                                                                                                                                                                                                                                                                                                                                                |
| limit                 | 否    | Integer          | 用于分页查询，取值范围0-1000，默认值1000。                                                                                                                                                                                                                                                                                                                                                            |
| domain_status         | 否    | Integer          | 加域状态。\|- 1 正常。 2 脱域。 3 未上报。                                                                                                                                                                                                                                                           |
| pool_id               | 否    | String           | 桌面池ID,多个桌面池ID用逗号隔开。                                                                                                                                                                                                                                                                                                                                                                   |
| enterprise_project_id | 否    | String           | 企业项目ID。                                                                                                                                                                                                                                                                                                                                                                               |
| desktop_type          | 否    | String           | 桌面类型，为空时查所有桌面。查询多个类型时用,隔开。 - DEDICATED：普通桌面，包括专享桌面、专属桌面等。   - SHARED: 多用户共享桌面。    |
| is_share_desktop      | 否    | Boolean          | 是否为协同桌面。                                                                                                                                                                                                                                                                                                                                                                              |
| subnet_id             | 否    | String           | 桌面的子网ID。                                                                                                                                                                                                                                                                                                                                                                              |
| status                | 否    | String           | 桌面的运行状态。                                                                                                                                                                                                                                                                                                                                                                              |
| desktop_id            | 否    | Array of strings | 桌面id，当前最多支持100个桌面id进行查询。                                                                                                                                                                                                                                                                                                                                                              |
| tag                   | 否    | String           | 桌面的标签。样例： - key1=value1。   - key1=value1，key2=value2。                             |
   
#### 请求参数
无
#### 响应参数
**状态码：200**
表3响应Body参数 
| 参数          | 参数类型                                                                            | 描述    |
|:---|:---|:---|
| total_count | Integer                                                                         | 总数。   |
| desktops    | Array of [SimpleDesktopInfo] objects | 桌面信息。 |
   
 表4SimpleDesktopInfo 
| 参数                    | 参数类型                                                                                        | 描述                                                                                                                          |
|:---|:---|:---|
| domain_id             | String                                                                                      | domainId。                                                                                                                   |
| project_id            | String                                                                                      | 项目id。                                                                                                                       |
| desktop_id            | String                                                                                      | 桌面ID。                                                                                                                       |
| computer_name         | String                                                                                      | 桌面名。                                                                                                                        |
| os_host_name          | String                                                                                      | 系统计算机名。                                                                                                                     |
| created               | String                                                                                      | 创建时间。                                                                                                                       |
| ip_address            | String                                                                                      | 桌面ip地址。                                                                                                                     |
| user_name             | String                                                                                      | 用户名。                                                                                                                        |
| attach_user_infos     | Array of [AttachInstancesUserInfo] objects | 桌面已分配的用户信息列表。                                                                                                               |
| user_group            | String                                                                                      | 权限组。                                                                                                                        |
| sid                   | String                                                                                      | 桌面的SID信息。                                                                                                                   |
| ou_name               | String                                                                                      | ou名称。                                                                                                                       |
| enterprise_project_id | String                                                                                      | 企业项目ID。                                                                                                                     |
| tags                  | Array of [Tag] objects                                         | 标签列表。                                                                                                                       |
| in_maintenance_mode   | Boolean                                                                                     | 是否处于管理员维护模式。                                                                                                                |
| share_resource_sku    | String                                                                                      | 桌面协同资源SKU码。                                                                                                                 |
| desktop_type          | String                                                                                      | 桌面类型。                                                                                                                       |
| desktop_detail_type   | String                                                                                      | 桌面详细类型                                                                                                                      |
| subnet_id             | String                                                                                      | 桌面的子网ID。                                                                                                                    |
| bill_resource_id      | String                                                                                      | 桌面计费资源ID。                                                                                                                   |
| status                | String                                                                                      | 桌面的运行状态。                                                                                                                    |
| task_status           | String                                                                                      | 桌面的任务状态。                                                                                                                    |
| availability_zone     | String                                                                                      | 所属的可用区。                                                                                                                     |
| connect_status        | String                                                                                      | 桌面的连接状态                                                                                                                     |
| pool_id               | String                                                                                      | 桌面池id。                                                                                                                      |
| domain_status         | Integer                                                                                     | 加域状态。\|- 1 正常。 2 脱域。 3 未上报。 |
   
 表5AttachInstancesUserInfo 
| 参数         | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|:---|:---|:---|
| user_id    | String | 当type字段为USER时，填写用户id；当type字段为GROUP时，填写用户组id，后端服务会校验组id是否存在；                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| user_name  | String | 桌面分配对象的名称，当type类型USER时填写用户名字；当type类型GROUP时填写用户组名称。 - 当type类型USER时：桌面所属的用户，当桌面分配成功后此用户可以登录该桌面。只允许输入大写字母、小写字母、数字、中划线（-）和下划线（_）。域类型为LITE_AD时，使用小写字母或者大写字母开头，长度范围为\[1-20\]。当域类型为LOCAL_AD时，用户名可以使用小写字母或者大写字母或者数字开头，长度范围为\[1-64\]。Windows桌面用户最长支持20个字符，Linux桌面用户最长支持64个字符。后端服务会校验用户名是否存在，并且用户名不能与机器名重复。   - 当type类型GROUP时：只能为中文、字母、数字及特殊符号-_。                                                                                 |
| domain     | String | 用户所属域。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| user_group | String | 桌面用户所属的用户组。 - sudo：Linux管理员组。   - default：Linux默认用户组。   - administrators：Windows管理员组。管理员拥有对该桌面的完全访问权，可以做任何需要的更改（禁用操作除外）。   - users：Windows标准用户组。标准用户可以使用大多数软件，并可以更改不影响其他用户的系统设置。    |
| type       | String | 对象类型，可选值为，默认值为USER： - USER：用户。   - GROUP：用户组。                                                                                                                                                                                                                                                                                                                                                                           |
   
 表6Tag 
| 参数    | 参数类型   | 描述                                                                                                   |
|:---|:---|:---|
| key   | String | 标签的键，不能为空，最大长度128个unicode字符。大小写字母，数字，可以包含中划线"-"，下划线"_"，不能包含以下字符"=","\*","\<","\>","\\",",","\|","/"。 |
| value | String | 标签的值，最大长度43个unicode字符。大小写字母，数字，可以包含中划线"-"，下划线"_"，不能包含以下字符"=","\*","\<","\>","\\",",","\|","/"。       |
   
**状态码：400**
表7响应Body参数 
| 参数                            | 参数类型   | 描述                                                           |
|:---|:---|:---|
| error_code                    | String | 错误码，失败时返回。                                                   |
| error_msg                     | String | 错误描述。                                                        |
| error_detail                  | String | 错误详情。                                                        |
| encoded_authorization_message | String | 加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。 |
   
**状态码：401**
表8响应Body参数 
| 参数                            | 参数类型   | 描述                                                           |
|:---|:---|:---|
| error_code                    | String | 错误码，失败时返回。                                                   |
| error_msg                     | String | 错误描述。                                                        |
| error_detail                  | String | 错误详情。                                                        |
| encoded_authorization_message | String | 加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。 |
   
**状态码：403**
表9响应Body参数 
| 参数                            | 参数类型   | 描述                                                           |
|:---|:---|:---|
| error_code                    | String | 错误码，失败时返回。                                                   |
| error_msg                     | String | 错误描述。                                                        |
| error_detail                  | String | 错误详情。                                                        |
| encoded_authorization_message | String | 加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。 |
   
**状态码：404**
表10响应Body参数 
| 参数                            | 参数类型   | 描述                                                           |
|:---|:---|:---|
| error_code                    | String | 错误码，失败时返回。                                                   |
| error_msg                     | String | 错误描述。                                                        |
| error_detail                  | String | 错误详情。                                                        |
| encoded_authorization_message | String | 加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。 |
   
**状态码：500**
表11响应Body参数 
| 参数                            | 参数类型   | 描述                                                           |
|:---|:---|:---|
| error_code                    | String | 错误码，失败时返回。                                                   |
| error_msg                     | String | 错误描述。                                                        |
| error_detail                  | String | 错误详情。                                                        |
| encoded_authorization_message | String | 加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。 |
   
#### 请求示例
```
/v2/bcae3e673fd04716a3b9dacdf58ca336/desktops
```
#### 响应示例
**状态码：200**
查询云桌面列表响应。
```
{
  "total_count" : 2,
  "desktops" : [ {
    "desktop_id" : "a6f6e2d1-cc62-46f3-865b-9ae6ae0afde0",
    "computer_name" : "ZRYUAN107",
    "created" : "2022-02-23 04:02:07",
    "ip_address" : "10.0.9.25",
    "user_name" : "zryuan1",
    "user_group" : "administrators",
    "sid" : "3db90102-d11d-4d13-9a96-104696d3c6a3",
    "in_maintenance_mode" : false,
    "share_resource_sku" : "workspace.collaborativedesktop.6party.standard"
  }, {
    "desktop_id" : "248077ea-bb64-4e58-b5e8-6b686600920e",
    "computer_name" : "CHENYC01",
    "created" : "2022-02-22 12:14:59",
    "ip_address" : "10.0.9.103",
    "user_name" : "chenyc",
    "user_group" : "administrators",
    "sid" : "352cf09d-ee15-4ef1-aa49-8d673972b4e6",
    "in_maintenance_mode" : true,
    "share_resource_sku" : "workspace.collaborativedesktop.6party.standard"
  } ]
}
```
#### 状态码
| 状态码 | 描述                      |
|:---|:---|
| 200 | 查询云桌面列表响应。              |
| 400 | 由于包含语法错误，当前请求无法被服务器理解。  |
| 401 | 鉴权失败。                   |
| 403 | 没有操作权限。                 |
| 404 | 找不到资源。                  |
| 500 | 服务内部错误，具体返回错误码请参见错误码说明。 |
   
#### 错误码
请参见[错误码](https://support.huaweicloud.com/api-workspace/ErrorCode.html)。