api reference · api calling public cloud apis comply with the restful api design principles....

Workspace

API Reference

Issue 02

Date 2018-03-30

HUAWEI TECHNOLOGIES CO., LTD.

Copyright © Huawei Technologies Co., Ltd. 2018. All rights reserved.No part of this document may be reproduced or transmitted in any form or by any means without prior writtenconsent of Huawei Technologies Co., Ltd. Trademarks and Permissions

and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.All other trademarks and trade names mentioned in this document are the property of their respectiveholders. NoticeThe purchased products, services and features are stipulated by the contract made between Huawei and thecustomer. All or part of the products, services and features described in this document may not be within thepurchase scope or the usage scope. Unless otherwise specified in the contract, all statements, information,and recommendations in this document are provided "AS IS" without warranties, guarantees orrepresentations of any kind, either express or implied.

The information in this document is subject to change without notice. Every effort has been made in thepreparation of this document to ensure accuracy of the contents, but all statements, information, andrecommendations in this document do not constitute a warranty of any kind, express or implied.

Huawei Technologies Co., Ltd.Address: Huawei Industrial Base

Bantian, LonggangShenzhen 518129People's Republic of China

Website: http://e.huawei.com

Issue 02 (2018-03-30) Huawei Proprietary and ConfidentialCopyright © Huawei Technologies Co., Ltd.

i

http://e.huawei.com

Contents

1 API Calling..................................................................................................................................... 11.1 Service Usage................................................................................................................................................................. 11.2 Request Methods............................................................................................................................................................ 21.3 Request Authentication Methods....................................................................................................................................21.4 Token Authentication......................................................................................................................................................21.5 AK/SK Authentication................................................................................................................................................... 31.5.1 AK and SK Generation................................................................................................................................................31.5.2 Request Signing Procedure..........................................................................................................................................41.5.3 Sample Code................................................................................................................................................................41.6 Obtaining a Project ID..................................................................................................................................................12

2 Common Message Headers....................................................................................................... 132.1 Common Request Headers........................................................................................................................................... 132.2 Common Response Headers.........................................................................................................................................15

3 Desktops........................................................................................................................................163.1 Creating Desktops.........................................................................................................................................................163.2 Deleting Desktops.........................................................................................................................................................223.3 Restarting Desktops......................................................................................................................................................233.4 Starting Desktops..........................................................................................................................................................243.5 Shutting Down Desktops.............................................................................................................................................. 263.6 Querying the Desktop List............................................................................................................................................273.7 Querying Desktop Details............................................................................................................................................ 303.8 Querying the Desktop Detail List.................................................................................................................................363.9 Modifying Desktop Attributes......................................................................................................................................443.10 Modifying Desktop Specifications............................................................................................................................. 45

4 Workspace.....................................................................................................................................484.1 Applying for Workspace...............................................................................................................................................484.2 Querying Workspace Details........................................................................................................................................ 534.3 Modifying Workspace Attributes................................................................................................................................. 574.4 Canceling Workspace................................................................................................................................................... 59

5 Policies...........................................................................................................................................615.1 Querying Policies......................................................................................................................................................... 615.2 Modifying Policies....................................................................................................................................................... 67

WorkspaceAPI Reference Contents


ii

6 Product Packages......................................................................................................................... 766.1 Querying the Product List.............................................................................................................................................76

7 Desktop Users.............................................................................................................................. 797.1 Querying the Desktop User List................................................................................................................................... 797.2 Querying Desktop User Login Records........................................................................................................................82

A Appendix......................................................................................................................................87A.1 Asynchronous Job Query.............................................................................................................................................87A.2 Error Code Description................................................................................................................................................90A.3 LITE_AD Sensitive Accounts..................................................................................................................................... 93A.4 Reference Table for Connection Failure Causes..........................................................................................................94A.5 Workspace Monitoring Metrics................................................................................................................................... 95

B Change History............................................................................................................................97

WorkspaceAPI Reference Contents


iii

1 API Calling

Public cloud APIs comply with the RESTful API design principles. REST-based Web servicesare organized into resources. Each resource is identified by one or more Uniform ResourceIdentifiers (URIs). An application accesses a resource based on the resource's UnifiedResource Locator (URL). A URL is usually in the following format: https://Endpoint/uri. Inthe URL, uri indicates the resource path, that is, the API access path.

Public cloud APIs use HTTPS as the transmission protocol. Requests/Responses aretransmitted by using JSON messages, with media type represented by Application/json.

API requests sent by third-party applications to the public cloud service must be authenticatedusing signatures.

This chapter describes the overall method of using signatures and provides sample codes todetail how to use the default signer to sign requests and how to use an HTTP client to sendrequests.

1.1 Service UsagePublic cloud services provide RESTful APIs.

Representational State Transfer (REST) allocates Uniform Resource Identifiers (URIs) todispersed resources so that resources can be located. Applications on clients use UniformResource Locators (URLs) to obtain resources.

The URL is in the following format: https://Endpoint/uri

Table 1-1 describes the parameters in a URL.

Table 1-1 Parameter description

Parameter Description

Endpoint Specifies the URL that is the entry point for a web service. Obtainthe value from Regions and Endpoints.

URI Specifies the API access path for performing a specified operation.Obtain the value from the URI of the API, for example, v3/auth/tokens.

WorkspaceAPI Reference 1 API Calling


1

http://developer.huaweicloud.com/en-us/endpoint

1.2 Request MethodsThe HTTP protocol defines request methods, such as GET, PUT, POST, and DELETE, toindicate the desired action to be performed on the identified resource. RESTful APIs providedby public cloud services support the following methods.

Table 1-2 HTTP methods

Method Description

GET The GET method requests a representation of the specified resource.

PUT The PUT method requests that the enclosed entity be stored under thesupplied URI.

POST The POST method requests that the server accept the entity enclosed in therequest as a new subordinate of the web resource identified by the URI.

DELETE The DELETE method deletes the specified resource, for example, anobject.

1.3 Request Authentication MethodsYou can use either of the following two authentication methods to call APIs:

l Token authentication: Requests are authenticated using Tokens.

l AK/SK authentication: Requests are encrypted using the access key (AK) and secret key(SK) to provide higher security.

1.4 Token Authentication

Scenarios

If you use a token for authentication, you must obtain the user's token and add X-Auth-Tokento the request message header of the service API when making an API call.

This section describes how to make an API call for token authentication.

Make an API Call1. Send POST https://Endpoint of IAM/v3/auth/tokens to obtain the endpoint of IAM and

the region name in the message body.

See Regions and Endpoints.

If the service region name is ALL, replace Endpoint of IAM with the endpoint of cn-north-1.

An example request message is as follows:



2


NOTE

Replace the items in italic in the following example with actual ones. For details, see the Identityand Access Management API Reference.

{ "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "password", "domain": { "name": "domainname" } } } }, "scope": { "project": { "id": "0215ef11e49d4743be23dd97a1561e91" //This ID is used as an example. } } }}

2. Obtain the token. For details, see section "Obtaining the User Token" in the Identity andAccess Management API Reference.

3. Make a call to a service API, add X-Auth-Token to the message header, and set thevalue of X-Auth-Token to the token obtained in step 2.

1.5 AK/SK AuthenticationWhen you use API Gateway to send requests to underlying services, the requests are signedusing the AK and SK.

NOTE

AK: indicates the ID of the access key. AK is used together with SK to obtain an encrypted signature fora request.

SK: indicates the secret access key together used with the access key ID to sign requests. AK and SKcan be used together to identify a request sender to prevent the request from being modified.

When the AK/SK of a user under a domain is used, add X-Domain-Id to the header and set itto the user's domain ID.

1.5.1 AK and SK Generation1. Log in to the management console.2. Click the username and select Basic Information from the drop-down list.3. On the displayed page, click Manage my credentials.

4. Click Access Credentials.5. Click Add Access Key to switch to the Add Access Key page.6. Enter the password used for the current login.7. Enter the authentication code received in the email or mobile phone.



3

NOTE

For users created in Identity and Access Management (IAM), if no email address or mobile phoneis filled during the user creation, you only need to authenticate the login password.

8. Click OK to download the access key.

NOTE

To prevent the access key from being leaked, keep it secure.

1.5.2 Request Signing Procedure

Preparations1. Download the API Gateway signature tool.

Download path: http://esdk.huawei.com/ilink/esdk/download/HW_4567062. Extract the package.3. Create a Java project, and reference the extracted JAR to the dependency path.

Sign a Request1. Create a request com.cloud.sdk.DefaultRequest (JAVA) used for signing.2. Set the target API URL, HTTPS method, and content of request

com.cloud.sdk.DefaultRequest (JAVA).3. Sign request com.cloud.sdk.DefaultRequest (JAVA).

a. Call SignerFactory.getSigner(String serviceName, String regionName) to obtaina signing tool.

b. Call Signer.sign(Request<?> request, Credentials credentials) to sign the requestcreated in step 1.The following code shows the details://Select an algorithm for request signing.Signer signer = SignerFactory.getSigner(serviceName, region);//Sign the request. The request will change after the signing.signer.sign(request, new BasicCredentials(this.ak, this.sk));

4. Convert the request signed in the previous step to a new request that can be used to makean API call and copy the header of the signed request to the new request.For example, if Apache HttpClient is used, convert DefaultRequest to HttpRequestBaseand copy the header of the signed DefaultRequest to HttpRequestBase.For details, see descriptions of AccessServiceImpl.java in section Sample Code.

1.5.3 Sample CodeThe following three types of code show how to sign a request and how to use an HTTP clientto send an HTTPS request:

AccessService: indicates the abstract class that converts the GET, POST, PUT, and DELETEmethods in to the access method.

Demo: indicates the execution entry used to simulate GET, POST, PUT, and DELETE requestsending.

AccessServiceImpl: indicates the implementation of the access method. Code required forAPI gateway communication is in the access method.



4

http://esdk.huawei.com/ilink/esdk/download/HW_456706

For details about region and serviceName in the following code, see Regions andEndpoints.

AccessService.java:

package com.cloud.apigateway.sdk.demo;

import java.io.InputStream;import java.net.URL;import java.util.Map;

import org.apache.http.HttpResponse;

import com.cloud.sdk.http.HttpMethodName;

public abstract class AccessService { protected String serviceName = null; protected String region = null; protected String ak = null; protected String sk = null; public AccessService(String serviceName, String region, String ak, String sk) { this.region = region; this.serviceName = serviceName; this.ak = ak; this.sk = sk; } public abstract HttpResponse access(URL url, Map<String, String> header, InputStream content, Long contentLength, HttpMethodName httpMethod) throws Exception; public HttpResponse access(URL url, Map<String, String> header, HttpMethodName httpMethod) throws Exception { return this.access(url, header, null, 0l, httpMethod); } public HttpResponse access(URL url, InputStream content, Long contentLength, HttpMethodName httpMethod) throws Exception { return this.access(url, null, content, contentLength, httpMethod); } public HttpResponse access(URL url, HttpMethodName httpMethod) throws Exception { return this.access(url, null, null, 0l, httpMethod); } public abstract void close(); public String getServiceName() { return serviceName; } public void setServiceName(String serviceName) { this.serviceName = serviceName; } public String getRegion() { return region; } public void setRegion(String region) { this.region = region; }



5



public String getAk() { return ak; } public void setAk(String ak) { this.ak = ak; } public String getSk() { return sk; } public void setSk(String sk) { this.sk = sk; } }

AccessServiceImpl.java:


import java.io.IOException;import java.io.InputStream;import java.net.URISyntaxException;import java.net.URL;import java.util.HashMap;import java.util.Map;

import javax.net.ssl.SSLContext;

import org.apache.http.Header;import org.apache.http.HttpHeaders;import org.apache.http.HttpResponse;import org.apache.http.client.methods.HttpDelete;import org.apache.http.client.methods.HttpGet;import org.apache.http.client.methods.HttpHead;import org.apache.http.client.methods.HttpPatch;import org.apache.http.client.methods.HttpPost;import org.apache.http.client.methods.HttpPut;import org.apache.http.client.methods.HttpRequestBase;import org.apache.http.conn.ssl.AllowAllHostnameVerifier;import org.apache.http.conn.ssl.SSLConnectionSocketFactory;import org.apache.http.conn.ssl.SSLContexts;import org.apache.http.conn.ssl.TrustSelfSignedStrategy;import org.apache.http.entity.InputStreamEntity;import org.apache.http.impl.client.CloseableHttpClient;import org.apache.http.impl.client.HttpClients;

import com.cloud.sdk.DefaultRequest;import com.cloud.sdk.Request;import com.cloud.sdk.auth.credentials.BasicCredentials;import com.cloud.sdk.auth.signer.Signer;import com.cloud.sdk.auth.signer.SignerFactory;import com.cloud.sdk.http.HttpMethodName;

public class AccessServiceImpl extends AccessService {

private CloseableHttpClient client = null;

public AccessServiceImpl(String serviceName, String region, String ak, String sk) { super(serviceName, region, ak, sk); }

/** {@inheritDoc} */



6

public HttpResponse access(URL url, Map<String, String> headers, InputStream content, Long contentLength, HttpMethodName httpMethod) throws Exception {

// Make a request for signing. Request request = new DefaultRequest(this.serviceName); try { // Set the request address. request.setEndpoint(url.toURI());

String urlString = url.toString();

String parameters = null;

if (urlString.contains("?")) { parameters = urlString.substring(urlString.indexOf("?") + 1); Map parametersmap = new HashMap<String, String>(); if (null != parameters && !"".equals(parameters)) { String[] parameterarray = parameters.split("&"); for (String p : parameterarray) { String key = p.split("=")[0]; String value = p.split("=")[1]; parametersmap.put(key, value); } request.setParameters(parametersmap); } }

} catch (URISyntaxException e) { // It is recommended to add logs in this place. e.printStackTrace(); } // Set the request method. request.setHttpMethod(httpMethod); if (headers != null) { // Add request header information if required. request.setHeaders(headers); } // Configure the request content. request.setContent(content);

// Select an algorithm for request signing. Signer signer = SignerFactory.getSigner(serviceName, region); // Sign the request, and the request will change after the signing. signer.sign(request, new BasicCredentials(this.ak, this.sk));

// Make a request that can be sent by the HTTP client. HttpRequestBase httpRequestBase = createRequest(url, null, request.getContent(), contentLength, httpMethod); Map<String, String> requestHeaders = request.getHeaders(); // Put the header of the signed request to the new request. for (String key : requestHeaders.keySet()) { if (key.equalsIgnoreCase(HttpHeaders.CONTENT_LENGTH.toString())) { continue; } httpRequestBase.addHeader(key, requestHeaders.get(key)); }

HttpResponse response = null; SSLContext sslContext = SSLContexts.custom() .loadTrustMaterial(null, new TrustSelfSignedStrategy()) .useTLS().build(); SSLConnectionSocketFactory sslSocketFactory = new SSLConnectionSocketFactory( sslContext, new AllowAllHostnameVerifier());

client = HttpClients.custom().setSSLSocketFactory(sslSocketFactory) .build();



7

// Send the request, and a response will be returned. response = client.execute(httpRequestBase); return response; }

/** * Make a request that can be sent by the HTTP client. * * @param url * specifies the API access path. * @param header * specifies the header information to be added. * @param content * specifies the body content to be sent in the API call. * @param contentLength * specifies the length of the content. This parameter is optional. * @param httpMethod * specifies the HTTP method to be used. * @return specifies the request that can be sent by an HTTP client. */ private static HttpRequestBase createRequest(URL url, Header header, InputStream content, Long contentLength, HttpMethodName httpMethod) {

HttpRequestBase httpRequest; if (httpMethod == HttpMethodName.POST) { HttpPost postMethod = new HttpPost(url.toString());

if (content != null) { InputStreamEntity entity = new InputStreamEntity(content, contentLength); postMethod.setEntity(entity); } httpRequest = postMethod; } else if (httpMethod == HttpMethodName.PUT) { HttpPut putMethod = new HttpPut(url.toString()); httpRequest = putMethod;

if (content != null) { InputStreamEntity entity = new InputStreamEntity(content, contentLength); putMethod.setEntity(entity); } } else if (httpMethod == HttpMethodName.PATCH) { HttpPatch patchMethod = new HttpPatch(url.toString()); httpRequest = patchMethod;

if (content != null) { InputStreamEntity entity = new InputStreamEntity(content, contentLength); patchMethod.setEntity(entity); } } else if (httpMethod == HttpMethodName.GET) { httpRequest = new HttpGet(url.toString()); } else if (httpMethod == HttpMethodName.DELETE) { httpRequest = new HttpDelete(url.toString()); } else if (httpMethod == HttpMethodName.HEAD) { httpRequest = new HttpHead(url.toString()); } else { throw new RuntimeException("Unknown HTTP method name: " + httpMethod); }

httpRequest.addHeader(header); return httpRequest; }

@Override public void close() { try {



8

if (client != null) { client.close(); } } catch (IOException e) { // It is recommended to add logs in this place. e.printStackTrace(); } }

}

Demo.java:


import java.io.BufferedReader;import java.io.ByteArrayInputStream;import java.io.IOException;import java.io.InputStream;import java.io.InputStreamReader;import java.net.MalformedURLException;import java.net.URL;

import org.apache.http.HttpResponse;

import com.cloud.sdk.http.HttpMethodName;

public class Demo {

//replace real region private static final String region = "regionName";

//replace real service name private static final String serviceName = "serviceName";

public static void main(String[] args) {

//replace real AK String ak = "akString"; //replace real SK String sk = "skString";

// get method //replace real url String url = "urlString"; get(ak, sk, url);

// post method //replace real url String postUrl = "urlString"; //replace real body String postbody = "bodyString"; post(ak, sk, postUrl, postbody);

// put method //replace real body String putbody = "bodyString"; //replace real url String putUrl = "urlString"; put(ak, sk, putUrl, putbody);

// delete method //replace real url String deleteUrl = "urlString"; delete(ak, sk, deleteUrl); }

public static void put(String ak, String sk, String requestUrl,



9

String putBody) {

AccessService accessService = null; try { accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpMethod = HttpMethodName.PUT; InputStream content = new ByteArrayInputStream(putBody.getBytes()); HttpResponse response = accessService.access(url, content, (long) putBody.getBytes().length, httpMethod); System.out.println(response.getStatusLine().getStatusCode()); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); }

} public static void patch(String ak, String sk, String requestUrl, String putBody) {

AccessService accessService = null; try { accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpMethod = HttpMethodName.PATCH; InputStream content = new ByteArrayInputStream(putBody.getBytes()); HttpResponse response = accessService.access(url, content, (long) putBody.getBytes().length, httpMethod); System.out.println(convertStreamToString(response.getEntity() .getContent())); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); }

}

public static void delete(String ak, String sk, String requestUrl) {

AccessService accessService = null;

try { accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpMethod = HttpMethodName.DELETE;

HttpResponse response = accessService.access(url, httpMethod); System.out.println(convertStreamToString(response.getEntity() .getContent())); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); }

}

public static void get(String ak, String sk, String requestUrl) {

AccessService accessService = null;



10

try { accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpMethod = HttpMethodName.GET; HttpResponse response; response = accessService.access(url, httpMethod); System.out.println(convertStreamToString(response.getEntity() .getContent())); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); }

}

public static void post(String ak, String sk, String requestUrl, String postbody) {

AccessService accessService = new AccessServiceImpl(serviceName, region, ak, sk); URL url = null; try { url = new URL(requestUrl); } catch (MalformedURLException e) { e.printStackTrace(); } InputStream content = new ByteArrayInputStream(postbody.getBytes()); HttpMethodName httpMethod = HttpMethodName.POST; HttpResponse response;

try { response = accessService.access(url, content, (long) postbody.getBytes().length, httpMethod); System.out.println(convertStreamToString(response.getEntity() .getContent())); } catch (Exception e) { e.printStackTrace(); } finally { accessService.close(); } }

private static String convertStreamToString(InputStream is) { BufferedReader reader = new BufferedReader(new InputStreamReader(is)); StringBuilder sb = new StringBuilder();

String line = null; try { while ((line = reader.readLine()) != null) { sb.append(line + "\n"); } } catch (IOException e) { e.printStackTrace(); } finally { try { is.close(); } catch (IOException e) { e.printStackTrace(); } }

return sb.toString(); }

}



11

NOTE

1. Parameters URI, AK, SK, and HTTP METHOD are mandatory.

2. You can use the request.addHeader() method to add header information.

1.6 Obtaining a Project IDA project ID is required for some URLs when an API is called. It can be project_id ortenant_id because project_id has the same meaning as tenant_id in this document. Beforecalling an API, you need to obtain a project ID on the console. The steps are as follows:

1. Log in to the management console.2. Click the username and select Basic Information from the drop-down list.3. On the displayed page, click Manage my credentials.

On the displayed page, view the project ID in the project list.

Figure 1-1 Viewing project IDs



12

2 Common Message Headers

This chapter describes common request and response REST message headers.

2.1 Common Request Headers

Table 2-1 Common request headers

Parameter Description Mandatory Example Value

x-sdk-date Specifies the timewhen the request issent. The time is inYYYYMMDD'T'HHMMSS'Z' format.The value is thecurrent GMT time ofthe system.

NoThis field ismandatory forAK/SKauthentication.

20150907T101459Z

Authorization Specifies theauthenticationinformation.The value can beobtained from therequest signingresult.For details, seesection RequestSigning Procedure.


SDK-HMAC-SHA256Credential=ZIRRKMTWPTQFQI1WKNKB/20150907//ec2/sdk_request,SignedHeaders=content-type;host;x-sdk-date,Signature=55741b610f3c9fa3ae40b5a8021ebf7ebc2a28a603fc62d25cb3bfe6608e1994

WorkspaceAPI Reference 2 Common Message Headers


13


Host Specifies the serverdomain name andport number of theresources beingrequested. The valuecan be obtained fromthe URL of theservice API. Thevalue ishostname[:port]. Ifthe port number isnot specified, thedefault port is used.The default portnumber for https is443.


code.test.comorcode.test.com:443

Content-Type Specifies the requestbody MIME type.You are advised touse the default valueapplication/json.For interfaces usedto upload objects orimages, the value canvary depending onthe flow type.

Yes application/json

Content-Length Specifies the lengthof the request body.The unit is byte.

No 3495

X-Project-Id Specifies the projectID. Obtain theproject ID byfollowing theinstructions insection Obtaining aProject ID.This parameter ismandatory for arequest from a DeCor multi-project user.

NoThis field ismandatory forrequests thatuse AK/SKauthenticationin theDedicatedCloud (DeC)scenario ormulti-projectscenario.

e9993fc787d94b6c886cbaa340f9c0f4



14


X-Auth-Token Specifies the usertoken.For details abouthow to obtain thetoken, see section"Obtaining the UserToken" in theIdentity and AccessManagement APIReference. After therequest is processed,the value of X-Subject-Token inthe message headeris the token value.

NoThis field ismandatory fortokenauthentication.

The following is part of anexample token:MIIPAgYJKoZIhvcNAQc-CoIIO8zCCDu8CAQExDTALBglghkgBZQMEAgEwgg1QBgkqhkiG9w0BBwGggg1BBIINPXsidG9rZ.

NOTE

For details about other parameters in the message header, see the HTTP protocol documentation.

2.2 Common Response Headers

Table 2-2 Common response headers

Name Description Example Value

Content-Length Specifies the length of the response body.The unit is byte.

-

Date Specifies the GMT time when a requestresponse is returned.

Wed, 27 Dec 201606:49:46 GMT

Content-Type Specifies the response body MIME type. application/json



15

3 Desktops

ConceptA desktop uses the cloud computing technology to run securely on the cloud in hosting mode.Users can access the desktops for office work anytime and anywhere without time, location,terminal, and application restrictions.

3.1 Creating Desktops

FunctionThis interface is used to create and assign desktops to users. After a desktop is created, userscan log in to it. If this asynchronous interface is successfully invoked, the Workspacebackground receives the application request. If you want to check whether the desktop issuccessfully created, query the task execution status using the asynchronous job queryinterface. For details, see Asynchronous Job Query.

URIl URI format

POST /v1.0/{project_id}/desktopsl URI parameter description

Parameter Mandatory Type Description

project_id Yes string Specifies the user ID.

Requestl Request body parameter description

WorkspaceAPI Reference 3 Desktops


16


desktops Yes List datastructure [1]

Specifies the list of parameters usedfor creating desktops. The currentdesktops only support one record.Calling an interface once only createsone desktop.

email_notification

No boolean Specifies whether to send an email tonotify the desktop user after adesktop is created. The default valueis true. This parameter is valid onlywhen domain_type is set toLOCAL_AD during Workspaceapplication. If domain_type isLITE_AD, it is invalid because anemail must be sent to notify thedesktop user of changing the loginpassword when the desktop is createdfor the first time. Possible values are:l true: specifies that the system

sends an email to the desktopuser.

l false: specifies that the systemdoes not send an email to thedesktop user.

[1] desktops field data structure description

Name Mandatory Type Description

user_name Yes string Specifies the workspace users. After adesktop is created, users can log in to it.The username can contain only letters,digits, hyphens (-), and underscores (_).When the domain type is LITE_AD, theusername must start with a lowercase oruppercase letter and can contain 1 to 20characters. When the domain type isLOCAL_AD, the username can start witha lowercase or uppercase letter or a digitand can contain 1 to 20 characters.

user_email Yes string Specifies the valid email address. Thesystem sends a notification email to theemail address after the requested desktopis created.

product_id Yes string Specifies the product package ID.



17


image_id No string Specifies the image ID. This parameterapplies to scenarios where private imagesare used to create desktops and workswith product_id.

root_volume Yes Dictionarydatastructure [3]

Specifies the system disk configuration ofthe desktop.

data_volumes

No List datastructure [4]

Specifies the data disk configuration ofthe desktop.

computer_name

Yes string Specifies the computer name, which canbe viewed on the OS information page.The computer name must be unique.The computer name must contain 1 to 15characters and can contain only letters,digits, hyphens (-), and underscores (_). Itmust start with a letter.

user_group No string Specifies the group to which a desktopuser belongs.ADMINISTRATORS: administratorgroup. Administrators have completeaccess to the desktop and can make anydesired changes except for forbiddenoperations.USERS: user group. Users in this groupcan use most software and change systemsettings that do not affect other users.

security_groups

No List datastructure [2]

Specifies the security group used by thedesktop. If this is not available, use thespecified security group in the desktopproxy by default.

nics No List datastructure [5]

Specifies the NICs corresponding to thedesktop. If this is not specified, the defaultNIC is used.

availability_zone

No string Specifies the availability zone. Desktopsare created in the specified availabilityzone. If it is not specified, a ramdomavailability zone is used. Informationabout availability zones can be obtainedfrom Regions and Endpoints.



18



ou_name No string The parameter is valid only whendomain_type is set to LOCAL_AD. Youdo not need to set it when domain_type isset to LITE_AD. Enter a maximum of 5levels and levels from each other using aslash (/). Only letters, digits, spaces (notbefore or after a slash), and specialcharacters including -_/$!@&*?. areallowed, for example, ab/cd/ef.

[2] security_groups field data structure description


id Yes string Specifies the security group ID used bythe desktop.

[3] root_volume field data structure description


type Yes string Specifies the system disk type of the desktop. Thedisk type must match the one provided by thesystem.SATA: SATA diskSSD: SSD disk

size Yes integer Specifies the system disk size (GB). The valueranges from 80 to 32768 and must be greater thanor equal to the minimum size of the system disk inthe image, that is, the value of the min_diskattribute.

[4] data_volumes field data structure description


type Yes string Specifies the data disk type of the desktop. The disktype must match the one provided by the system.SATA: SATA diskSSD: SSD disk

size Yes integer Specifies the data disk space (GB). The valueranges from 100 to 32768.



19

[5] nics field data structure description


subnet_id Yes string Specifies the subnet ID corresponding tothe NIC. If this field is specified, thesubnet_id is mandatory.

ip_address No string Specifies the IP address, which isautomatically assigned if this field isblank or a null string.

l Request exampleWhen the domain type is LITE_AD:POST /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktopsRequest Body:{ "desktops": [{ "user_name": "test", "user_group": "USERS", "user_email": "[email protected]", "product_id": "workspace.c2.large.windows", "image_id": "66b9760c-02f0-4e3f-9946-4315cf299dc5", "computer_name": "test", "security_groups": [{ "id": "631e70c6-c788-4522-8a26-9ef0f98c546a" }], "root_volume": { "type": "SATA", "size": 80 }, "data_volumes": [{ "type": "SATA", "size": 100 }], "nics": [{ "subnet_id": "c962adaa-55b2-42ef-8e40-fd812221a96d" }, { "subnet_id": "ebb535f7-5730-496c-b26a-601ddfffd2fe", "ip_address": "192.168.0.65" }], "availability_zone": "az01" }]}When the domain type is LOCAL_AD:POST /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktopsRequest Body: { "desktops": [{ "user_name": "test", "user_group": "USERS", "user_email": "[email protected]", "product_id": "workspace.c2.large.windows", "image_id": "66b9760c-02f0-4e3f-9946-4315cf299dc5", "computer_name": "test", "security_groups": [{ "id": "631e70c6-c788-4522-8a26-9ef0f98c546a" }], "root_volume": { "type": "SATA", "size": 80



20

}, "data_volumes": [{ "type": "SATA", "size": 100 }], "nics": [{ "subnet_id": "c962adaa-55b2-42ef-8e40-fd812221a96d" }, { "subnet_id": "ebb535f7-5730-496c-b26a-601ddfffd2fe", "ip_address": "192.168.0.65" }], "availability_zone": "az01", "ou_name": "abc" }], "email_notification": false}

Responsel Description

Name Type Description

job_id string Specifies the ID of a desktop creation job. Userscan use this ID to query the execution status ofjobs.

l Response exampleSTATUS CODE 200{ "job_id": "a25e3d3f-8a8e-4789-bd3f-a04e230640fd"}

Returned Valuesl Normal

200l Abnormal

Returned Value Description

400 Bad Request The request syntax is incorrect and cannot beunderstood by the server.

401 Unauthorized Authentication fails.

403 Forbidden You are not authorized to perform theoperation.

404 Not Found The requested resource is not found.

405 Method Not Allowed The method specified in the request is notallowed.

500 Internal Server Error Internal service error. For details about errorcodes, see Error Code Description.

503 Service Unavailable The service is unavailable.



21

3.2 Deleting Desktops

Function

This interface is used to delete a desktop. A deleted desktop cannot be restored.

URIl URI format

DELETE /v1.0/{project_id}/desktops/{desktop_id}

l URI parameter description



desktop_id Yes string Specifies the desktop ID.

l Optional parameters


delete_users No string After a desktop is deleted, if thecurrent user does not have otherdesktops, the user can bedeleted. Possible values are asfollows:l true: Delete the user.l false: Do not delete the user.The default value is false.

Requestl Request exampleDELETE /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops/bae51750-0089-41a1-9b18-5c777978ff6d?delete_users=true

Responsel Response exampleSTATUS CODE 204


204

l Abnormal



22









3.3 Restarting Desktops

Function

This interface is used to restart a desktop.

URIl URI format

POST /v1.0/{project_id}/desktops/{desktop_id}/actionl URI parameter description

Parameter

Mandatory Type Description




Parameter


reboot Yes Dictionary datastructure [1]

Specifies the operation of restartingthe desktop.

[1] reboot field data structure description



23


type Yes string Specifies the restart mode:l SOFT: soft restartl HARD: hard restart

l Request examplePOST /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops/bae51750-0089-41a1-9b18-5c777978ff6d/action Request Body: { "reboot": { "type": "SOFT" } }



202

l Abnormal




403 Forbidden You are not authorized to perform the operation.


405 Method Not Allowed The method specified in the request is not allowed.

500 Internal Server Error Internal service error. For details about error codes, seeError Code Description.


3.4 Starting Desktops

Function

This interface is used to start a desktop.



24

URIl URI format

POST /v1.0/{project_id}/desktops/{desktop_id}/action






Parameter


os-start Yes Emptystructure

Specifies the operation of starting the desktop.The data structure is null.

l Request examplePOST /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops/bae51750-0089-41a1-9b18-5c777978ff6d/action Request Body: { "os-start": null }



202

l Abnormal








25





3.5 Shutting Down Desktops

FunctionThis interface is used to shut down a desktop.

URIl URI format

POST /v1.0/{project_id}/desktops/{desktop_id}/actionl URI parameter description

Parameter





Parameter


os-stop Yes Emptystructure

Specifies the operation of shutting down thedesktop. The data structure is null.

l Request examplePOST /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops/bae51750-0089-41a1-9b18-5c777978ff6d/action Request Body: { "os-stop": null }

Responsel Response example



26

STATUS CODE 202


202l Abnormal


400 Bad Request The request syntax is incorrect and cannot be understoodby the server.







3.6 Querying the Desktop List

Function

This interface is used to query the desktop list of the users.

URIl URI format

GET /v1.0/{project_id}/desktopsl URI parameter description



The following table lists the optional parameters for querying the desktop list.


status No string Specifies the desktop status. The value canbe ACTIVE, SHUTOFF, or ERROR.

desktop_ip No string Specifies the desktop IP address.



27


user_name No string Specifies the desktop users.

computer_name No string Specifies the computer name, which can beviewed on the OS information page.

marker No string Starts from the next record of the desktopID specified by marker during query bypage.

limit No integer Specifies the limits on the number ofdesktops that will be returned during queryby page. If this parameter is not specified,all desktops that meet the search criteriaare returned.

Requestl Request exampleGET /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops?limit=10&status=ACTIVE



desktops List data structure [1] Specifies the desktop informationlist.



desktop_id string Specifies the desktop ID.

computer_name string Specifies the computer name, which can beviewed on the OS information page.

created string Specifies the time when the desktop is created.The format is 2016-08-20T21:11:09.000Z.NOTE

The time is in the Coordinated Universal Time (UTC)format.

ip_address string Specifies the desktop IP address (IP address of auser).

user_name string Specifies the desktop users.



28


user_group string Specifies the group to which a desktop userbelongs.ADMINISTRATORS: administrator group.Administrators have complete access to thedesktop and can make any desired changesexcept for forbidden operations.USERS: user group. Users in this group can usemost software and change system settings thatdo not affect other users.

l Response exampleSTATUS CODE 200 { "desktops": [ { "desktop_id": "f41fb23a-376e-475d-bcaa-8e9f827aad62", "computer_name": "hyqdesk101", "created": "2016-10-08T06:44:57.000Z", "ip_address": "192.168.0.139", "user_name": "hyqdesk1", "user_group": "USERS" }, { "desktop_id": "b94a88e9-b67d-40d3-a3be-d207826ffdf2", "computer_name": "huangyq301", "created": "2016-10-06T11:39:22.000Z", "ip_address": "192.168.0.34", "user_name": "huangyq3", "user_group": "ADMINISTRATORS" } ] }


200

l Abnormal










29



3.7 Querying Desktop Details

Function

This interface is used to query desktop details.

URIl URI format

GET /v1.0/{project_id}/desktops/{desktop_id}





Requestl Request exampleGET /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops/89738b45-8a1f-46f9-8e5d-006589b0b956



desktop Dictionary datastructure [1]

Specifies the desktop details.

[1] desktop field data structure description



computer_name string Specifies the computer name, which can be viewedon the OS information page.

status string Specifies the desktop status.



30



The time is in the UTC format.

addresses Dictionary datastructure [2]

Specifies the desktop IP address (for user's login).

flavor Dictionary datastructure [3]

Specifies the desktop specifications.

security_groups List data structure[4]

Specifies the list of security groups to which thedesktop belongs.

metadata Dictionary datastructure [5]

Specifies the metadata of the desktop.


user_group string Specifies the group to which a desktop userbelongs.ADMINISTRATORS: administrator group.Administrators have complete access to thedesktop and can make any desired changes exceptfor forbidden operations.USERS: user group. Users in this group can usemost software and change system settings that donot affect other users.

login_status string Specifies the login status of the desktop.l UNREGISTER: specifies that the desktop is

not registered (a desktop is automaticallyregistered after being started up). After adesktop is shut down, it is in the unregisteredstate.

l REGISTERED: specifies that the desktop isregistered and is waiting for user connections.

l CONNECTED: specifies that a user hassuccessfully logged in to the desktop and isusing the desktop.

l DISCONNECTED: specifies that the desktopis disconnected from the client because theclient window is closed or the network betweenthe client and desktop is interrupted.

product_id string Specifies the product package ID.

root_volume Dictionary datastructure [8]

Specifies the desktop system disk information.

data_volumes List data structure[9]

Specifies the desktop data disk information.



31


availability_zone

string Specifies the availability zone.

ou_name string Specifies the OU name.

[2] addresses field data structure description


Virtual PrivateCloud (VPC) ID

List data structure [6] Specifies the ID of the VPC used by thedesktop. The VPC name is a variable.The value in the data structure is the list ofassigned private IP addresses in the VPC.

[3] flavor field data structure description


id string Specifies the ID of the desktopspecifications.

links List data structure [7] Specifies the relevant and marked shortcutlink of the desktop specifications.



id string Specifies the security group ID used by the desktop.

[5] metadata field data structure description


__openstack_region_name string Specifies the name of the availability zone (AZ)where the desktop is located.

charging_mode string Specifies the reserved field.

image_name string Specifies the name of the image used to createthe desktop.

metering.cloudServiceType string Specifies the cloud service type.

metering.image_id string Specifies the image ID.



32


metering.imagetype string Specifies the image type.l gold: public imagel private: private imagel market: market image

metering.resourcespeccode string Specifies the desktop resource code.

metering.resourcetype string Specifies the desktop resource type.

os_bit string Specifies the number of bits in the operatingsystem. The value can be 32 or 64.

os_type string Specifies the operating system type: Linux,Windows, or others.

vpc_id string Specifies the ID of the VPC where the desktop islocated.

op_svc_lockaction string Specifies the current operation type of thedesktop:l 0: Being configuredl 1: Deletingl 2: Modifying specificationsl 3: Reinstalling the operating systeml 4: Exportingl 5: Operating system installation failure

metering.billing string Specifies the reserved field.

desktop_gpu_type string Specifies the GPU type.

desktop_os_version string Specifies the OS version.

[6] VPC ID field data structure description


addr string Specifies the IP address.

version integer Specifies the type of the IP address. Thevalue can be 4 or 6.l 4: IPv4 addressesl 6: IPv6 addresses

OS-EXT-IPS-MAC:mac_addr

string Specifies the MAC address. This is anextended attribute.

OS-EXT-IPS:type string Specifies the IP address assignment method.This is an extended attribute.



33

[7] links field data structure description


rel string Specifies the shortcut link marker name.

href string Provides the shortcut link.



type string Specifies the system disk type of thedesktop.SATA: SATA diskSSD: SSD disk

size integer Specifies the system disk size, expressed inGB.

querying



type string Specifies the data disk type of the desktop.SATA: SATA diskSSD: SSD disk

size integer Specifies the data disk size, expressed inGB.

l Response exampleSTATUS CODE 200 { "desktop": { "desktop_id": "b94a88e9-b67d-40d3-a3be-d207826ffdf2", "computer_name": "huangyq301", "status": "SHUTOFF", "created": "2016-10-06T11:39:22.000Z", "login_status": "UNREGISTER", "user_name": "huangyq3", "user_group": "ADMINISTRATORS", "security_groups": [ { "id": "7293f9ba-91f4-466e-ac45-6550f46ea87e" } ], "flavor": { "id": "computev2-2", "links": [ {



34

"rel": "bookmark", "hrel": "https://compute.region.eu-de.otc- tsi.de/60e0e898dc52459fb8e01cd0eca09e5a/flavors/computev2-2" } ] }, "metadata": { "metering.image_id": "fc14e223-84b5-48fe-90d6-853b462a1778", "metering.imagetype": "private", "metering.resourcespeccode": "c2.large.win", "metering.cloudServiceType": "sys.service.type.ec2", "image_name": "workspace-user-template-0927", "metering.resourcetype": "1", "os_bit": "64", "vpc_id": "d8b3a219-8e0b-4435-ab47-1a8930c00037", "os_type": "Windows", "charging_mode": "0", "desktop_gpu_type": "M60-1Q(1GB)", "desktop_os_version": "Windows Server 2016 64bit with windows 10 experience" }, "addresses": { "d8b3a219-8e0b-4435-ab47-1a8930c00037": [ { "addr": "172.16.0.9", "version": 4, "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:1e:04:cb", "OS-EXT-IPS:type": "fixed" } ], "bf00c6a1-2bca-4601-9a3e-597b08e9224d": [ { "addr": "192.168.0.34", "version": 4, "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:c7:b7:05", "OS-EXT-IPS:type": "fixed" } ] }, "product_id": "workspace.c2.large.windows", "root_volume": { "type": "SATA", "size": 80 }, "data_volumes": [ { "type": "SSD", "size": 100 }, { "type": "SATA", "size": 100 } ], "availability_zone": "az01", "ou_name": "abc" } }


200l Abnormal



35









3.8 Querying the Desktop Detail List

Function

This interface is used to query the desktop detail list.

URIl URI format

GET /v1.0/{project_id}/desktops/detail



project_id Yes string Specifies the userID.

The following table lists the optional parameters for querying the desktop detail list.

Parameter Mandatory

Type Description

status No string Specifies the desktop status. Thevalue can be ACTIVE, SHUTOFF,or ERROR.

desktop_ip No string Specifies the desktop IP address.

user_name No string Specifies the desktop users.

computer_name

No string Specifies the computer name, whichcan be viewed on the OSinformation page.



36

Parameter Mandatory

Type Description

marker No string Starts from the next record of thedesktop ID specified by markerduring query by page.

limit No integer Specifies the limits on the number ofdesktops that will be returned duringquery by page. If this parameter isnot specified, all desktops that meetthe search criteria are returned.

Requestl Request example

GET /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops/detail?limit=10&status=ACTIVE



desktops List data structure [1] Specifies the desktop detaillist.




computer_name string Specifies the desktop name (in the operatingsystem).

status string Specifies the desktop status.



addresses Dictionary datastructure [1]

Specifies the desktop IP address (for user'slogin).

flavor Dictionary datastructure [2]

Specifies the details of the desktopspecifications.

security_groups List data structure[3]

Specifies the list of security groups to whichthe desktop belongs.



37


metadata Dictionary datastructure [4]

Specifies the desktop metadata.


user_group string Specifies the group to which a desktop userbelongs.ADMINISTRATORS: administrator group.Administrators have complete access to thedesktop and can make any desired changesexcept for forbidden operations.USERS: user group. Users in this group canuse most software and change system settingsthat do not affect other users.

login_status string Specifies the login status of the desktop.l UNREGISTER: specifies that the desktop

is not registered (a desktop is automaticallyregistered after being started up). After adesktop is shut down, it is in theunregistered state.

l REGISTERED: specifies that the desktopis registered and is waiting for userconnections.

l CONNECTED: specifies that a user hassuccessfully logged in to the desktop and isusing the desktop.

l DISCONNECTED: specifies that thedesktop is disconnected from the clientbecause the client window is closed or thenetwork between the client and desktop isinterrupted.


root_volume Dictionary datastructure [7]

Specifies the desktop system disk information.

data_volumes List data structure[8]

Specifies the desktop data disk information.

availability_zone string Specifies the availability zone.

ou_name string Specifies the OU name.

[2] addresses field data structure description



38


Virtual PrivateCloud (VPC)ID

List data structure [5] Specifies the ID of the VPC used by thedesktop. The VPC name is a variable.The value in the data structure is the list ofassigned private IP addresses in the VPC.

[3] flavor field data structure description


id string Specifies the ID of the desktopspecifications.

links List data structure [6] Specifies the relevant and marked shortcutlink of the desktop specifications.



id string Specifies the security group ID used by thedesktop.

[5] metadata field data structure description


__openstack_region_name string Specifies the name of the AZ where thedesktop is located.

charging_mode string Specifies the reserved field.

image_name string Specifies the name of the image used tocreate the desktop.

metering.cloudServiceType string Specifies the cloud service type.

metering.image_id string Specifies the image ID.

metering.imagetype string Specifies the image type.l gold: public imagel private: private imagel market: market image

metering.resourcespeccode string Specifies the desktop resource code.

metering.resourcetype string Specifies the desktop resource type.



39


os_bit string Specifies the number of bits in theoperating system. The value can be 32 or64.

os_type string Specifies the operating system type:Linux, Windows, or others.

vpc_id string Specifies the ID of the VPC where thedesktop is located.

op_svc_lockaction string Specifies the current operation type of thedesktop:l 0: Being configuredl 1: Deletingl 2: Modifying specificationsl 3: Reinstalling the operating systeml 4: Exportingl 5: Operating system installation failure

metering.billing string Specifies the reserved field.

desktop_gpu_type string Specifies the GPU type.

desktop_os_version string Specifies the OS version.

[6] VPC ID field data structure description


addr string Specifies the IP address.

version integer Specifies the type of the IP address. Thevalue can be 4 or 6.l 4: IPv4 addressesl 6: IPv6 addresses

OS-EXT-IPS-MAC:mac_addr string Specifies the MAC address. This is anextended attribute.

OS-EXT-IPS:type string Specifies the IP address assignment method.This is an extended attribute.

[7] links field data structure description


rel string Specifies the shortcut link marker name.



40


href string Provides the shortcut link.



type string Specifies the system disk type of thedesktop.SATA: SATA diskSSD: SSD disk

size integer Specifies the system disk size, expressed inGB.



type string Specifies the data disk type of the desktop.SATA: SATA diskSSD: SSD disk

size integer Specifies the data disk size, expressed inGB.

l Response exampleSTATUS CODE 200

{ "desktops": [{ "desktop_id": "f77db5cd-c020-47d4-bbbe-9b979a38d18c", "computer_name": "cm01", "status": "ACTIVE", "created": "2016-11-14T14:41:25.000Z", "login_status": "REGISTERED", "user_name": "cm", "user_group": "USERS", "security_groups": [{ "id": "46946f87-ccf7-4be2-ac1d-8b6a18deb77b" }], "flavor": { "id": "computev2-2", "links": [{ "rel": "bookmark", "hrel": "https://compute.region.eu-de.otc-tsi.de/b99add77e7924466852c793e041a7d6a/flavors/computev2-2" }] }, "metadata": { "metering.image_id": "3a6886dc-fede-4cc9-bc19-39a3f4a9c31e", "metering.imagetype": "private", "metering.resourcespeccode": "c2.large.win",



41

"metering.cloudServiceType": "sys.service.type.ec2", "image_name": "workspace-user-template-test", "metering.resourcetype": "1", "os_bit": "64", "vpc_id": "bd44b40c-4491-4d76-8ffb-0d86c094eacc", "os_type": "Windows", "charging_mode": "0", "desktop_gpu_type": "M60-1Q(1GB)", "desktop_os_version": "Windows Server 2016 64bit with windows 10 experience" }, "addresses": { "aa60ef37-e2b1-4a25-b2f7-077592c060fa": [{ "addr": "192.168.0.22", "version": 4, "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:81:e6:ad", "OS-EXT-IPS:type": "fixed" }], "bd44b40c-4491-4d76-8ffb-0d86c094eacc": [{ "addr": "172.16.0.25", "version": 4, "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:a7:1c:ca", "OS-EXT-IPS:type": "fixed" } ] }, "product_id": "workspace.c2.large.windows", "root_volume": { "type": "SATA", "size": 80 }, "data_volumes": [{ "type": "SATA", "size": 100 }], "availability_zone": "az01", "ou_name": "abc" }, { "desktop_id": "7dbc9fbb-447a-4180-9f86-70951646d8a5", "computer_name": "chen01", "status": "SHUTOFF", "created": "2016-11-11T06:59:41.000Z", "login_status": "UNREGISTER", "user_name": "chen", "user_group": "ADMINISTRATORS", "security_groups": [{ "id": "46946f87-ccf7-4be2-ac1d-8b6a18deb77b" }], "flavor": { "id": "computev2-4", "links": [{ "rel": "bookmark", "hrel": "https://compute.region.eu-de.otc-tsi.de/b99add77e7924466852c793e041a7d6a/flavors/computev2-4" }] }, "metadata": { "metering.image_id": "9a07cffa-7294-49f6-a795-f3db306a4b5a", "metering.imagetype": "private", "metering.resourcespeccode": "c2.2xlarge.win", "metering.cloudServiceType": "sys.service.type.ec2", "image_name": "workspace-user-template0809", "metering.resourcetype": "1", "os_bit": "64", "vpc_id": "bd44b40c-4491-4d76-8ffb-0d86c094eacc", "os_type": "Windows", "charging_mode": "0", "desktop_gpu_type": "M60-1Q(1GB)",



42

"desktop_os_version": "Windows Server 2016 64bit with windows 10 experience" }, "addresses": { "aa60ef37-e2b1-4a25-b2f7-077592c060fa": [{ "addr": "192.168.0.20", "version": 4, "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:09:7b:c4", "OS-EXT-IPS:type": "fixed" }], "bd44b40c-4491-4d76-8ffb-0d86c094eacc": [{ "addr": "172.16.0.23", "version": 4, "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:2b:da:23", "OS-EXT-IPS:type": "fixed" }] }, "product_id": "workspace.c2.2xlarge.windows", "root_volume": { "type": "SATA", "size": 80 }, "data_volumes": [{ "type": "SATA", "size": 100 }], "availability_zone": "az01", "ou_name": null }]}


200l Abnormal











43

3.9 Modifying Desktop Attributes

Function

This interface is used to modify desktop attributes.

URIl URI format

PUT /v1.0/{project_id}/desktops/{desktop_id}l URI parameter description






desktop No Dictionarydata structure[1]

Specifies desktop attributes.

[1] desktop field data structure description


computer_name string Specifies the computer name, which canbe viewed on the OS information page.The name must be unique. It mustcontain 1 to 15 characters and cancontain only letters, digits, hyphens (-),and underscores (_). In addition, it muststart with a letter.NOTE

The desktop will restart to make themodification take effect.

l Request examplePUT /v1.0/92c84e5bce3d48d7ab5714a44901eb08/desktops/3c2dba15-15db-4204-9f86-f0a5b05cf610Request Body: {



44

"desktop": { "computer_name": "a01" }}


STATUS CODE 204


204l Abnormal









3.10 Modifying Desktop Specifications

Function

This interface is used to modify the specifications of a desktop.

URIl URI format

POST /v1.0/{project_id}/desktops/{desktop_id}/resizel URI parameter description





45


desktop_id Yes string Specifies thedesktop ID.


Parameter Mandatory

Type Description

product_id Yes string Specifies the ID of thenew package.Specifications of thenew package must bedifferent from those ofthe original package.For the packageinformation, seeQuerying the ProductList.

l Request example

POST /v1.0/d2ce97927a1846608223ca1e20c7b73e/desktops/d7deecd2-e9ff-4ee7-8684-f607a2c7b34a/resizeRequest Body: { "product_id": "workspace.c2.large.windows" }



job_id string Specifies the ID of a modifying desktopspecifications job. Users can use this ID to querythe execution status of jobs.

l Response example

STATUS CODE 200{ "job_id": "ff80808260fca2e50160fddbe0600026"}STATUS CODE 500{ "error_code": "WKS.0408", "error_msg": "The operating status of the desktop does not support specifications change."}



46


200l Abnormal











47

4 Workspace

Concept

Workspace is the cloud hosting service for Windows desktop computer users.

4.1 Applying for Workspace

Function

This interface is used to apply for Workspace. If this asynchronous interface is successfullyinvoked, the Workspace background receives the application request. If you want to checkwhether you have successfully applied for Workspace, query the task execution status usingthe asynchronous job query interface. For details, see Asynchronous Job Query.

URIl URI format

POST /v1.0/{project_id}/workspaces






ad_domains

Yes Dictionarydata structure[1]

Specifies the domain information usedby Workspace.

vpc_id Yes string Specifies the unique VPC ID.

WorkspaceAPI Reference 4 Workspace


48


subnet_ids Yes List datastructure [2]

Specifies the subnet ID set.

access_mode

Yes string Specifies the access mode. Possiblevalues are:l INTERNET: indicates the Internet

access mode.l DEDICATED: indicates the

DirectConnect access mode.l BOTH: indicates both modes.

availability_zone

No string Specifies the availability zone.Desktops are created in the specifiedavailability zone. If it is not specified,a ramdom availability zone is used.Information about availability zonescan be obtained from Regions andEndpoints.

[1] ad_domains field data structure description

Name Mandatory

Type Description

domain_type Yes string Specifies the domain type. Possible valuesare:l LITE_AD: indicates the lightweight AD

that is deployed on the cloud.l LOCAL_AD: indicates the local AD,

namely, the user's existing AD.NOTE

When the domain type is LOCAL_AD, ensurethat the selected VPC network can connect tothe network to which LOCAL_AD belongs.



49



Name Mandatory

Type Description

domain_name Yes string Specifies the domain name.When the domain type is LITE_AD, domainnames must comply with the following rules:l Contains 4 to 63 characters.l Contains only letters, digits, hyphens (-),

and periods (.)l Cannot start or end with a hyphen (-) or a

period (.). A period (.) and a hyphen (-)cannot be neighbors.

l Contains at least one period (.). The lengthbefore the first period (.) must be within15 characters. At least two characters mustbe reserved after the last period (.) and thecharacters must contain at least one letter,for example, v-Desk1.xxx.com.

When the domain type is LOCAL_AD, thedomain name must exist and the length cannotexceed 255 characters.

domain_admin_account

Yes string Specifies the domain administrator account.When the domain type is LITE_AD, thedomain administrator account must complywith the following rules:l Contains only letters, digits, hyphens (-),

and underscores (_). It must start with aletter.

l Cannot be the sensitive accounts listed inLITE_AD Sensitive Accounts.

When the domain type is LOCAL_AD, theaccount must be an existing domainadministrator account on the AD server.



50

Name Mandatory

Type Description

domain_password

Yes string Specifies the password of a domainadministrator account.When the domain type is LITE_AD, thepassword must comply with the followingrules:l Consists of at least four types of the

following: uppercase letters, lowercaseletters, digits, and special characters (~!@#$%^&*_-+=`|(){}[]:;"'<>,.?/). It beginswith a letter and contains 8 to 64characters.

l Cannot be the same as the domainadministrator account or in the reverseorder of it.

l Cannot contain more than two consecutiveidentical characters (for example, 111 isnot allowed).

l Weak passwords can be added based onsite requirements. This document does notlist those weak passwords. For details,contact the administrator.

When the domain type is LOCAL_AD, thepassword must be the password of an existingdomain administrator account on the ADserver.

active_domain_ip

No string Specifies the IP address of the active domaincontroller. This parameter is mandatory whenthe domain type is LOCAL_AD.

standby_domain_ip

No string Specifies the IP address of the standbydomain controller. This parameter is optionalwhen the domain type is LOCAL_AD.

active_dns_ip No string Specifies the IP address of the active DNS.This parameter is mandatory when the domaintype is LOCAL_AD.

standby_dns_ip

No string Specifies the IP address of the standby DNS.This parameter is optional when the domaintype is LOCAL_AD.

[2] subnet_ids field data structure description



51

Name Mandatory

Type Description

subnet_id Yes string Specifies the subnet ID.

l Request examplePOST /v1.0/fb2e5ec048384c8f9469d22db0037908/workspacesLITE_AD request example:Request Body:{ "ad_domains":{ "domain_type":"LITE_AD", "domain_name":"testapi.litead.com", "domain_admin_account":"vdsadmin", "domain_password":"Testabc!23" }, "vpc_id":"e8f985fa-5161-4cb8-bf5a-155058ea58c9", "subnet_ids":[ { "subnet_id":"067b30a9-1b73-4804-a808-699c5f6c4e09" }, { "subnet_id":"47c39964-4a32-4fb9-acc8-fac4355848d0" } ], "access_mode":"INTERNET", "availability_zone": "az01"}LOCAL_AD request example:{ "ad_domains": { "domain_type": "LOCAL_AD", "domain_name": "devdesktop.test.com", "domain_admin_account": "vdsadmin", "domain_password": "Testabc123!", "active_domain_ip": "10.0.0.9", "active_dns_ip": "10.0.0.9" }, "vpc_id": "bd92e362-4806-46c7-99c2-6a8a30afbc4b", "subnet_ids": [{ "subnet_id": "d8863831-af9b-4585-b954-b7f5121ab4d2" }], "access_mode": "BOTH", "availability_zone": "az01"}



job_id string Specifies the job ID for applying forWorkspace. Users can use this ID to query thejob execution status.

l Response exampleSTATUS CODE 200{ "job_id": "0000000058fd65560159004bd2490005"}



52


200

l Abnormal









4.2 Querying Workspace Details

Function

This interface is used to query Workspace details.

URIl URI format

GET /v1.0/{project_id}/workspaces




Requestl Request exampleGET /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/workspaces




53


ad_domains Dictionarydata structure[1]

Specifies the domain information used byWorkspace.

vpc_id string Specifies the unique VPC ID.

vpc_name string Specifies the VPC name.

dedicated_access_address

string Specifies the DirectConnect access address.This parameter has a value when the accessmode is DEDICATED or BOTH.

internet_access_address

string Specifies the Internet access address.

status string Specifies the Workspace status. Possiblevalues are:l PREPARING: indicates that Workspace

is in the process of preparation for thesubscription.

l SUBSCRIBING: indicates thatWorkspace is being subscribed.

l SUBSCRIBED: indicates thatWorkspace has been subscribed.

l SUBSCRIPTION_FAILED: indicatesthat the subscription has failed.

l DEREGISTERING: indicates that theaccount is being deregistered.

l DEREGISTRATION_FAILED:indicates that the deregistration hasfailed.

access_mode string Specifies the access mode. Possible valuesare:l INTERNET: indicates the Internet

access mode.l DEDICATED: indicates the

DirectConnect access mode.l BOTH: indicates both modes.

subnet_ids List datastructure [2]

Specifies the subnet ID.




54


domain_type string Specifies the domain type. Possible values are:l LITE_AD: indicates the lightweight AD

that is deployed on the cloud.l LOCAL_AD: indicates the local AD,

namely, the user's existing AD.

domain_name string Specifies the domain name.


string Specifies the domain administrator account.

active_domain_ip string Specifies the IP address of the active domaincontroller. This parameter has a value when thedomain type is LOCAL_AD.

standby_domain_ip string Specifies the IP address of the standby domaincontroller. This parameter has a value when thedomain type is LOCAL_AD.

active_dns_ip string Specifies the IP address of the active DNS.This parameter has a value when the domaintype is LOCAL_AD.

standby_dns_ip string Specifies the IP address of the standby DNS.This parameter has a value when the domaintype is LOCAL_AD.

[2] subnet_ids field data structure description


subnet_id string Specifies the subnet ID.

l Response exampleWhen the domain type is LITE_AD:STATUS CODE 200 { "ad_domains": { "domain_type": "LITE_AD", "domain_name": "test.com", "domain_admin_account": "vdsadmin", "active_domain_ip": null, "standby_domain_ip": null, "active_dns_ip": null, "standby_dns_ip": null }, "vpc_id": "dbecb512-34d1-4d7d-90f1-6d3feb76263d", "vpc_name": "test", "dedicated_access_address": "https://192.168.0.4", "internet_access_address": "https://10.154.55.185", "status": "SUBSCRIBED", "access_mode": "DEDICATED", "subnet_ids": [



55

{ "subnet_id": "a4bde8e5-b8b7-453c-839b-3c5a3a49772f" } ]}When the domain type is LOCAL_AD:STATUS CODE 200 { "ad_domains": { "domain_type": "LOCAL_AD", "domain_name": "test.com", "domain_admin_account": "vdsadmin", "active_domain_ip": "172.16.0.4", "standby_domain_ip": "172.16.0.5", "active_dns_ip": "172.16.0.4", "standby_dns_ip": "172.16.0.5" }, "vpc_id": "dbecb512-34d1-4d7d-90f1-6d3feb76263d", "vpc_name": "test", "dedicated_access_address": "null", "internet_access_address": "https://10.154.55.185", "status": "SUBSCRIBED", "access_mode": "INTERNET", "subnet_ids": [ { "subnet_id": "a4bde8e5-b8b7-453c-839b-3c5a3a49772f" } ]}


200l Abnormal











56

4.3 Modifying Workspace Attributes

FunctionThis interface is used to modify Workspace attributes. The attributes can be modified onlyafter Workspace is subscribed.

URIl URI format

PUT /v1.0/{project_id}/workspacesl URI parameter description




Name Mandatory

Type Description

ad_domains No Dictionary datastructure[1]

Specifies the domain information usedby Workspace.


Name Mandatory

Type Description

domain_type Yes string Specifies the domain type. Possible valuesare:l LITE_AD: indicates the lightweight

AD that is deployed on the cloud.l LOCAL_AD: indicates the local AD,

namely, the user's existing AD.


No string This field is optional when the domaintype is LOCAL_AD. The new value mustbe an existing domain user on the ADserver.



57

Name Mandatory

Type Description

old_domain_password

No string Specifies the old password of the domainadministrator account. This field ismandatory when the domain type isLITE_AD.

domain_password No string Specifies the new password of the domainadministrator account.When the domain type is LITE_AD andthe value is not blank, the new passwordmust comply with the following rules:l Consists of at least four types of the

following: uppercase letters, lowercaseletters, digits, and special characters (~!@#$%^&*_-+=`|(){}[]:;"'<>,.?/). Itbegins with a letter and contains 8 to 64characters.

l Cannot be the domain administratoraccount or in the reverse order of it.

l The password cannot contain morethan two consecutive identicalcharacters (for example, 111 is notallowed).

l The password cannot contain huawei(case-insensitive).

l Weak passwords can be added based onsite requirements. This document doesnot list those weak passwords. Fordetails, contact the administrator.

When the domain type is LOCAL_ADand the value is not blank, the newpassword must comply with the followingrule:l Must be the password of the domain

administrator account.

l Request exampleWhen the domain type is LITE_AD:PUT /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/workspacesRequest Body:{ "ad_domains": { "domain_type": "LITE_AD", "old_domain_password": "oldpassword", "domain_password": "newpassword" } }When the domain type is LOCAL_AD:PUT /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/workspacesRequest Body:



58

{ "ad_domains": { "domain_type": "LOCAL_AD", "domain_admin_account": "domainuser", "domain_password": "newpassword" } }


STATUS CODE 204


204

l Abnormal









4.4 Canceling Workspace

Function

This interface is used to cancel Workspace. Ensure that the desktop of the current user isdeleted before you cancel Workspace. The desktop cannot be resumed after you cancelWorkspace.

URIl URI format

DELETE /v1.0/{project_id}/workspaces




59



Requestl Request exampleDELETE /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/workspaces



job_id string Specifies the job ID for cancelingWorkspace. Users can use this ID toquery the job execution status.

l Response exampleSTATUS CODE 202{ "job_id": "0000000059071dbc01591661d3990019"}


202

l Abnormal











60

5 Policies

ConceptUsers log in to the cloud desktop through the HDP protocol, which supports such functions asUSB port redirection and printer redirection. Relevant policies enable administrators tocontrol the data transmission and peripheral access rights between users and desktops.

5.1 Querying Policies

FunctionThis interface is used to query the policies supported by Workspace.

URIl URI format

GET /v1.0/{project_id}/policiesl URI parameter description



Requestl Request example

GET /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/policies

Responsel Elements

WorkspaceAPI Reference 5 Policies


61


policies Dictionarydata structure[1]

Specifies the policy information.

[1] policies field data structure description


usb_port_redirection Dictionary datastructure [2]

Specifies USB port redirection.

printer_redirection Dictionary datastructure [4]

Specifies printer redirection.

file_redirection Dictionary datastructure [6]

Specifies file redirection.

clipboard_redirection string Specifies clipboard redirection. Possible valuesare:l DISABLED: indicates that clipboard

redirection is disabled.l SERVER_TO_CLIENT_ENABLED:

indicates that clipboard redirection from theserver to the client is enabled.

l CLIENT_TO_SERVER_ENABLED:indicates that clipboard redirection from theclient to the server is enabled.

l TWO_WAY_ENABLED: indicates thattwo-way clipboard redirection is enabled.

hdp_plus Dictionary datastructure [8]

Specifies the desktop protocol display level.

[2] usb_port_redirection field data structure description


enable boolean Specifies whether to enable USB portredirection. Possible values are:l false: indicates that USB port redirection is

disabled.l true: indicates that USB port redirection is

enabled.

options Dictionary datastructure [3]

Controls USB port redirection.



62

[3] options field data structure description


usb_image_enable boolean Specifies whether to enable image devices(such as scanners). Possible values are:l false: indicates that image devices are

disabled.l true: indicates that image devices are

enabled.

usb_video_enable boolean Specifies whether to enable video devices(such as cameras). Possible values are:l false: indicates that video devices are

disabled.l true: indicates that video devices are

enabled.

usb_printer_enable boolean Specifies whether to enable print devices (suchas printers). Possible values are:l false: indicates that print devices are

disabled.l true: indicates that print devices are

enabled.

usb_storage_enable boolean Specifies whether to enable storage devices(such as USB flash drives). Possible valuesare:l false: indicates that storage devices are

disabled.l true: indicates that storage devices are

enabled.

usb_smart_card_enable

boolean Specifies whether to enable smartcard devices(such as USB keys). Possible values are:l false: indicates that smartcard devices are

disabled.l true: indicates that smartcard devices are

enabled.

[4] printer_redirection field data structure description



63


enable boolean Specifies whether to enable printer redirection.Possible values are:l false: indicates that printer redirection is

disabled.l true: indicates that printer redirection is

enabled.


Controls printer redirection.



sync_client_default_printer_enable

boolean Specifies whether to enable thesynchronization of the default client printer.Possible values are:l false: indicates that the synchronization of

the default client printer is disabled.l true: indicates that the synchronization of

the default client printer is enabled.

universal_printer_driver

string Specifies the universal printer driver. Possiblevalues are:l Defaultl HDP XPSDrv Driverl Universal Printing PCL 5l Universal Printing PCL 6l Universal Printing PS

[6] file_redirection field data structure description


redirection_mode string Specifies file redirection. The values are asfollows:l DISABLED: indicates that file redirection

is disabled.l READ_ONLY: indicates that files are

read-only.l READ_AND_WRITE: indicates that files

are readable and writable.



64



Controls file redirection.



fixed_drive_enable boolean Specifies whether to enable fixed drives (suchas local disks). Possible values are:l false: indicates that fixed drives are

disabled.l true: indicates that fixed drives are

enabled.

removable_drive_enable

boolean Specifies whether to enable removable drives(such as USB flash drives). Possible valuesare:l false: indicates that removable drives are

disabled.l true: indicates that removable drives are

enabled.

cd_rom_drive_enable boolean Specifies whether to enable the CD/DVD-ROM drive. Possible values are:l false: indicates that the CD/DVD-ROM

drive is disabled.l true: indicates that the CD/DVD-ROM

drive is enabled.

network_drive_enable boolean Specifies whether to enable the network drive.Possible values are:l false: indicates that the network drive is

disabled.l true: indicates that the network drive is

enabled.

[8] hdp_plus field data structure description


hdp_plus_enable boolean Specifies whether to enable HDP Plus.Possible values are:l false: indicates that HDP Plus is disabled.l true: indicates that HDP Plus is enabled.



65


display_level string Specifies the display level. Possible values are:l SMOOTHNESS_FIRST: indicates

smoothness first.l QUALITY_FIRST: indicates quality first.


Controls the HDP Plus and display level.



bandwidth integer Specifies the bandwidth (Kbit/s). The valueranges from 1000 to 25,000.

frame_rate integer Specifies the frame rate (fps). The value rangesfrom 15 to 30.

video_frame_rate integer Specifies the video frame rate (fps). The valueranges from 15 to 50.

smoothing_factor integer Specifies the smoothing factor. The valueranges from 0 to 60.

lossy_compression_quality

integer Specifies the lossy compression quality. Thevalue ranges from 70 to 90.

l Response exampleSTATUS CODE 200 { "policies": { "usb_port_redirection": { "enable": true, "options": { "usb_image_enable": false, "usb_video_enable": true, "usb_printer_enable": false, "usb_storage_enable": true, "usb_smart_card_enable": false } }, "printer_redirection": { "enable": true, "options": { "sync_client_default_printer_enable": false, "universal_printer_driver": "Universal Printing PCL 6" } }, "file_redirection": { "redirection_mode": "READ_AND_WRITE", "options": { "fixed_drive_enable": true, "removable_drive_enable": false, "cd_rom_drive_enable": true, "network_drive_enable": true



66

} }, "clipboard_redirection": "TWO_WAY_ENABLED", "hdp_plus": { "hdp_plus_enable": false, "display_level": "QUALITY_FIRST", "options": { "bandwidth": 24315, "frame_rate": 18, "video_frame_rate": 20, "smoothing_factor": 58, "lossy_compression_quality": 88 } } }}


200

l Abnormal









5.2 Modifying Policies

Function

This interface is used to modify policy information.

URIl URI format

PUT /v1.0/{project_id}/policies




67

Parameter Mandatory

Type Description



Parameter Mandatory

Type Description

policies Yes Dictionarydata structure[1]

Specifies the policy information.

[1] policies field data structure

Parameter Mandatory

Type Description

usb_port_redirection No Dictionarydata structure[2]

Specifies USB port redirection.

printer_redirection No Dictionarydata structure[4]

Specifies printer redirection.

file_redirection No Dictionarydata structure[6]

Specifies file redirection.

clipboard_redirection No string Specifies the clipboard redirection.Possible values are:l DISABLED: indicates that

clipboard redirection isdisabled.

l SERVER_TO_CLIENT_ENABLED: indicates that clipboardredirection from the server tothe client is enabled.

l CLIENT_TO_SERVER_ENABLED: indicates that clipboardredirection from the client tothe server is enabled.

l TWO_WAY_ENABLED:indicates that two-wayclipboard redirection isenabled.



68

Parameter Mandatory

Type Description

hdp_plus No Dictionarydata structure[8]

Specifies the desktop protocoldisplay level.

[2] usb_port_redirection field data structure

Parameter Mandatory

Type Description

enable No boolean Specifies whether to enable USBport redirection. Possible valuesare:l false: indicates that USB port

redirection is disabled.l true: indicates that USB port

redirection is enabled.

options No Dictionarydata structure[3]

Controls USB port redirection.When this is enabled, the fields inoptions can be changed.

[3] options field data structure

Parameter Mandatory

Type Description

usb_image_enable No boolean Specifies whether to enable imagedevices (such as scanners).Possible values are:l false: indicates that image

devices are disabled.l true: indicates that image

devices are enabled.

usb_video_enable No boolean Specifies whether to enable videodevices (such as cameras).Possible values are:l false: indicates that video

devices are disabled.l true: indicates that video




69

Parameter Mandatory

Type Description

usb_printer_enable No boolean Specifies whether to enable printdevices (such as printers). Possiblevalues are:l false: indicates that print

devices are disabled.l true: indicates that print


usb_storage_enable No boolean Specifies whether to enablestorage devices (such as USBflash drives). Possible values are:l false: indicates that storage

devices are disabled.l true: indicates that storage


usb_smart_card_enable

No boolean Specifies whether to enablesmartcard devices (such as USBkeys). Possible values are:l false: indicates that smartcard

devices are disabled.l true: indicates that smartcard


[4] printer_redirection field data structure

Parameter Mandatory

Type Description

enable No boolean Specifies whether to enable printerredirection. Possible values are:l false: indicates that printer

redirection is disabled.l true: indicates that printer

redirection is enabled.


Controls printer redirection. Whenthis is enabled, the values of allthe fields in options can bechanged.




70

Parameter Mandatory

Type Description

sync_client_default_printer_enable

No boolean Specifies whether to enable thesynchronization of the defaultclient printer. Possible values are:l false: indicates that the

synchronization of the defaultclient printer is disabled.

l true: indicates that thesynchronization of the defaultclient printer is enabled.

universal_printer_driver

No string Specifies the universal printerdriver. Possible values are:l Defaultl HDP XPSDrv Driverl Universal Printing PCL 5l Universal Printing PCL 6l Universal Printing PS

[6] file_redirection field data structure

Parameter Mandatory

Type Description

redirection_mode No string Specifies file redirection. Possiblevalues are:l DISABLED: indicates that file

redirection is disabled.l READ_ONLY: indicates that

files are read-only.l READ_AND_WRITE:

indicates that files are readableand writable.


Controls file redirection. Whenthis is in read-only or read andwrite mode, the values of all thefields in options can be changed.




71

Parameter Mandatory

Type Description

fixed_drive_enable No boolean Specifies whether to enable fixeddrives (such as local disks).Possible values are:l false: indicates that fixed

drives are disabled.l true: indicates that fixed drives

are enabled.

removable_drive_enable

No boolean Specifies whether to enableremovable drives (such as USBflash drives). Possible values are:l false: indicates that removable

drives are disabled.l true: indicates that removable

drives are enabled.

cd_rom_drive_enable No boolean Specifies whether to enable theCD/DVD-ROM drive. Possiblevalues are:l false: indicates that the CD/

DVD-ROM drive is disabled.l true: indicates that the CD/

DVD-ROM drive is enabled.

network_drive_enable No boolean Specifies whether to enable thenetwork drive. Possible values are:l false: indicates that the

network drive is disabled.l true: indicates that the network

drive is enabled.

[8] hdp_plus field data structure

Parameter Mandatory

Type Description

hdp_plus_enable No boolean Specifies whether to enable HDPPlus. Possible values are:l false: indicates that HDP Plus

is disabled.l true: indicates that HDP Plus is

enabled.



72

Parameter Mandatory

Type Description

display_level No string Specifies the display level.Possible values are:l SMOOTHNESS_FIRST:

indicates smoothness first.l QUALITY_FIRST: indicates

quality first.


Controls the HDP Plus and displaylevel. When hdp_plus_enable isenabled, the value oflossy_compression_quality canbe changed. Alternatively, all ofthe field values in options can bechanged.


Parameter Mandatory

Type Description

bandwidth No integer Specifies the bandwidth (Kbit/s).The value ranges from 1000 to25,000.

frame_rate No integer Specifies the frame rate (fps). Thevalue ranges from 15 to 30.

video_frame_rate No integer Specifies the video frame rate(fps). The value ranges from 15 to50.

smoothing_factor No integer Specifies the smoothing factor.The value ranges from 0 to 60.

lossy_compression_quality

No integer Specifies the lossy compressionquality. The value ranges from 70to 90.

l Request examplePUT /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/policiesRequest Body: { "policies": { "usb_port_redirection": { "enable": false, "options": { "usb_image_enable": false, "usb_video_enable": true, "usb_printer_enable": false, "usb_storage_enable": true,



73

"usb_smart_card_enable": false } }, "printer_redirection": { "enable": true, "options": { "sync_client_default_printer_enable": false, "universal_printer_driver": "Universal Printing PCL 6" } }, "file_redirection": { "redirection_mode": "READ_AND_WRITE", "options": { "fixed_drive_enable": true, "removable_drive_enable": false, "cd_rom_drive_enable": true, "network_drive_enable": true } }, "clipboard_redirection": "TWO_WAY_ENABLED", "hdp_plus": { "hdp_plus_enable": false, "display_level": "QUALITY_FIRST", "options": { "bandwidth": 24315, "frame_rate": 18, "video_frame_rate": 20, "smoothing_factor": 58, "lossy_compression_quality": 88 } } }}


STATUS CODE 204


204

l Abnormal










74





75

6 Product Packages

Concept

A product package contains hardware and software. The hardware includes the CPU, memory,and GPU. The software refers to the one preinstalled on the desktop. You can select theproduct package to create desktops based on site requirements.

6.1 Querying the Product List

Function

This interface is used to query the product packages supported by Workspace.

URIl URI format

GET /v1.0/{project_id}/productsl URI parameter description



l Retrieval parameter description


availability_zone

No string Specifies an AZ. You can obtainthe AZ information from Regionsand Endpoints.

Requestl Request exampleGET /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/products?availability_zone=ab-cd

WorkspaceAPI Reference 6 Product Packages


76



Responsel Elements


products List datastructure [1]

Specifies the product packages supported byWorkspace.

[1] products field data structure description



flavor_id string Specifies the specification ID.

type string Specifies the product type.l BASE: indicates the basic product package.

Except the operating system, no othercommercial software is installed on theproduct image. In the private imagescenario, you can use this package only.

l ADVANCED: indicates the advancedproduct package. Some commercialsoftware is installed on the product image.

os_type string Specifies the OS type of the product package,for example, Windows Server 2008 R2.

descriptions string Specifies the detailed product packageinformation.

l Response exampleSTATUS CODE 200 { "products": [{ "product_id": "workspace.c2.large.windows", "flavor_id": "computev2-2", "type": "BASE", "os_type": "Windows Server 2008 R2", "descriptions": "CPU:2vCPUs,Memory:4GB,Operating System:Windows Server 2008 R2 64bit with windows 7 experience" }, { "product_id": "workspace.c2.large.windows.1", "flavor_id": "computev2-2", "type": "BASE", "os_type": "Windows Server 2016", "descriptions": "CPU:2vCPUs,Memory:4GB,Operating System:Windows Server 2016 64bit with windows 10 experience" }, { "product_id": "workspace.g1.2xlarge.windows", "flavor_id": "g1.2xlarge", "type": "BASE", "os_type": "Windows Server 2008 R2", "descriptions": "CPU:8vCPUs,Memory:16GB,Operating System:Windows



77

Server 2008 R2 64bit with windows 7 experience,GPU:M60-1Q(1GB)" }]}


200l Abnormal











78

7 Desktop Users

Concept

After the Workspace service is enabled, the Workspace user can create and assign desktops todesktop users.

NOTE

Desktop user indicates the actual user of a desktop.

7.1 Querying the Desktop User List

Function

This interface is used to query the list of users with allocated desktops.

URIl URI format

GET /v1.0/{project_id}/desktop-users


Name Mandatory

Type Description


The following table lists the optional parameters for querying the desktop user list.

Name Mandatory

Type Description

user_name No string Specifies the desktop username.

user_email No string Specifies the desktop user email.

WorkspaceAPI Reference 7 Desktop Users


79

Name Mandatory

Type Description

marker No string Starts from the next record of the desktopusername specified by marker during query bypage.

limit No integer Specifies the limits on the number of userswho will be returned during query by page. Ifthe parameter is not specified, all users whomeet the search criteria are returned.

l Request exampleGET /v1.0/92c84e5bce3d48d7ab5714a44901eb08/desktop-users?user_name=wjj&[email protected]&marker=wjj0001a&limit=10



users List data structure [1] Specifies the user list.

[1] users field data structure description


user_name string Specifies the desktopusername.

user_email string Specifies the desktop useremail.

ad_domains Dictionary data structure[2]

Specifies the user domaininformation.



domain_name string Specifies the user domain, forexample, vdesktop.test.com.



80


domain_type string Specifies the domain type.Possible values are:l LITE_AD: indicates the

lightweight AD that isdeployed on the cloud.

l LOCAL_AD: indicates thelocal AD, namely, theuser's existing AD.

l Response exampleSTATUS CODE 200 { "users": [ { "user_name": "a01", "user_email": "[email protected]", "ad_domains": { "domain_name": "abc.com", "domain_type": "LITE_AD" } }, { "user_name": "a02", "user_email": "[email protected]", "ad_domains": { "domain_name": "abc.com", "domain_type": "LITE_AD" } } ] }


200l Abnormal









81




7.2 Querying Desktop User Login Records

Function

This interface is used to query desktop user login records.

URIl URI format

GET /v1.0/{project_id}/desktop-users/login-records




The following table lists the optional parameters for querying desktop user login records.

Name Mandatory

Type Description

start_time No string Specifies the start time of the loginrecord query. If this parameter isspecified, the returned result setcontains login records generatedafter the start time. The format is2016-08-20T21:11Z.NOTE


end_time No string Specifies the end time of the loginrecord query. If this parameter isspecified, the returned result setcontains login records generatedbefore the end time. The format is2016-08-20T21:11Z.NOTE


user_name No string Specifies the username for loggingin to the desktop.



82

Name Mandatory

Type Description

computer_name No string Specifies the computer name,which can be viewed on the OSinformation page.

terminal_type No string Specifies the terminal system typefor logging in to the desktop, forexample, Windows 7 andWindows 10.

offset No integer Specifies the offset of thespecified information list queryand the default value is 0.

limit No integer Specifies the limits on the numberof users who will be returnedduring query by page. The defaultvalue is 20.

l Request exampleGET /v1.0/92c84e5bce3d48d7ab5714a44901eb08/desktop-users/login-records?start_time=2016-12-09T08:06Z&end_time=2016-12-09T08:33Z&user_name=wjj&computer_name=wjj&terminal_type=Windows 7&offset=1&limit=3



records List data structure [1] Specifies the user loginrecords.

[1] records field data structure description


computer_name string Specifies the computername, which can be viewedon the OS information page.

user_name string Specifies the loginusername.

terminal_mac string Specifies the terminal MACaddress.

terminal_name string Specifies the terminal name.

terminal_ip string Specifies the terminal IPaddress.



83


client_version string Specifies the client softwareversion used when you login to the desktop.

terminal_type string Specifies the terminalsystem type for logging in tothe desktop, for example,Windows 7 and Windows10.

agent_version string Specifies the AccessAgentversion.

desktop_ip string Specifies the IP address ofthe desktop.

connection_start_time string Specifies the start time ofthe connection. Theconnection is establishedbetween the server and theclient software when theclient software obtains thedesktop IP address usingTicket. The format is2016-08-20T21:11:09.000Z.NOTE


connection_setup_time string Specifies the time when theconnection between theclient software and thedesktop is formallyestablished. The format is2016-08-20T21:11:09.000Z.NOTE


connection_end_time string Specifies the time when theconnection between theclient software and thedesktop is disconnected. Theformat is2016-08-20T21:11:09.000Z.NOTE




84


is_reconnect boolean Specifies whether thereconnection occurs duringthe login process. Possiblevalues are:l true: indicates that a

reconnection occurs.l false: indicates that the

reconnection does notoccur.

connection_failure_reason string Specifies the cause for aconnection failure. Thisparameter has a value whenthe connection fails. Theformat is 400200:Thedesktop is being prepared.NOTE

For details, see ReferenceTable for Connection FailureCauses.

l Response exampleSTATUS CODE 200 { "records": [ { "computer_name": "[email protected]", "user_name": "[email protected]", "terminal_mac": "28-6e-d4-f8-cb-1b", "terminal_name": "TEST01D02", "terminal_ip": "10.75.229.214", "client_version": "1.6.00004", "terminal_type": "Windows 10 ", "agent_version": "1.6.00005.0", "desktop_ip": "172.16.0.20", "connection_start_time": "2016-12-09T07:28:07.000Z", "connection_setup_time": "2016-12-09T07:28:17.000Z", "connection_end_time": "2016-12-09T08:29:37.000Z", "is_reconnect": false, "connection_failure_reason": null }, { "computer_name": "[email protected]", "user_name": "[email protected]", "terminal_mac": "28-6e-d4-f8-cb-1b", "terminal_name": "TEST01D02", "terminal_ip": "10.75.229.214", "client_version": "1.6.00004", "terminal_type": "Windows 10 ", "agent_version": "1.6.00005.0", "desktop_ip": null, "connection_start_time": "2016-12-09T06:56:21.000Z", "connection_setup_time": null, "connection_end_time": null, "is_reconnect": false, "connection_failure_reason": "400200:The desktop is being prepared." }



85

]}


200l Abnormal











86

A Appendix

A.1 Asynchronous Job Query

FunctionThis interface is used to query the execution status of an asynchronous job, for example,creating a desktop.

URIl URI format

GET /v1.0/{project_id}/workspace-jobs/{job_id}l URI parameter description



job_id Yes string Specifies the asynchronous jobID.

Requestl Request exampleGET /v1.0/ac234de25c6741d2b1273da49eea1b9e/workspace-jobs/ae379d45-bb34-4613-9bda-467addca8f81

Responsel Elements

WorkspaceAPI Reference A Appendix


87


status string Specifies the job status. Possible values are:l SUCCESS: indicates that the job is successful.l RUNNING: indicates that the job is running.l FAILED: indicates that the job fails.l INIT: indicates that the job is being initialized.

job_id string Specifies the job ID.

job_type string Specifies the job type. Possible values are:l createDesktops: creates a desktop job.l applyWorkspace: applies for Workspace.l cancelWorkspace: cancels Workspace.

begin_time string Specifies the begin time.

end_time string Specifies the end time.

error_code string Specifies the error code of a failed job.

fail_reason string Specifies the cause of a failed job.

message string Specifies the error message returned when a faultoccurs.

code string Specifies the error code returned when a faultoccurs.For error codes and their corresponding meanings,see Error Code Description.

sub_jobs_total integer Specifies the number of sub-jobs. When there is nosub-job, the value is 0. When job_type isapplyWorkspace , cancelWorkspace, orresizeDesktop, there is no sub-job.

sub_jobs List datastructure [2]

Specifies the execution information about sub-jobs.The list is empty when there is no sub-job.

[2] sub_jobs field data structure description


status string Specifies the job status. Possible values are:l SUCCESS: indicates that the job is successful.l RUNNING: indicates that the job is running.l FAILED: indicates that the job fails.l INIT: indicates that the job is being initialized.

entities Dictionary datastructure [3]

Specifies the operation object of a job. If the job typeis createDesktops, its value is desktop_id.



88


job_id string Specifies the job ID.

job_type string Specifies the job type.

begin_time string Specifies the begin time.

end_time string Specifies the end time.

error_code string Specifies the error code of a failed job.

fail_reason string Specifies the cause of a failed job.

message string Specifies the error message returned when a faultoccurs.

code string Specifies the error code returned when a faultoccurs.For error codes and their corresponding meanings,see Error Code Description.

[3] entities field data structure description



l Response exampleSTATUS CODE 200Create a desktop.{ "job_id": "0000000057793178015779a77ac3002d", "job_type": "createDesktops", "begin_time": "2016-09-30T05:53:21.000Z", "end_time": "2016-09-30T06:07:21.000Z", "status": "SUCCESS", "error_code": null, "fail_reason": null, "sub_jobs_total": 1, "sub_jobs": [{ "job_id": "7a9e0959b98742e2b39dae9cb7f193cf", "job_type": "createDesktops", "begin_time": "2016-09-30T05:53:21.000Z", "end_time": "2016-09-30T06:07:21.000Z", "status": "SUCCESS", "error_code": null, "fail_reason": null, "message": null, "entities": { "desktop_id": "6db9da2a-70de-4511-8a13-a2358a03ab2b" } }] }Apply for Workspace.{ "job_id": "0000000058fd65560159004bd2490005", "job_type": "applyWorkspace",



89

"begin_time": "2016-12-15T02:24:46.000Z", "end_time": null, "status": "RUNNING", "error_code": null, "fail_reason": null, "sub_jobs_total": 0, "sub_jobs": []}Cancel Workspace.{ "job_id": "0000000058fd6556015900630f0b0008", "job_type": "cancelWorkspace", "begin_time": "2016-12-15T02:50:09.000Z", "end_time": "2016-12-15T02:53:55.000Z", "status": "SUCCESS", "error_code": null, "fail_reason": null, "sub_jobs_total": 0, "sub_jobs": []}


200l Abnormal









A.2 Error Code Description

FunctionIf the returned status code of a Workspace API is 400, the request parameters are incorrect. Ifthe returned status code of a Workspace API is 500, an internal service error occurs. In thecase that either of the status codes is returned, the customized error information will bereturned. This section describes the meaning of each error code.

Response Body FormatSTATUS CODE 400 {



90

"error_code": "WKS.0001", "error_msg": "Invalid request parameter. Sysdisk size is invalid."}

Error Code Description

Module Error Code Description

Public WKS.0001 Invalid request parameter.

WKS.0002 Internal error.

WKS.0003 Database operation error.

WKS.0004 Failed to invoke the ITA interface.

WKS.0005 Failed to invoke the ECS interface.

WKS.0006 Failed to invoke the VPC interface.

WKS.0007 Failed to invoke the OpenStack interface.

WKS.0008 Failed to invoke the SMN interface.

WKS.0009 Failed to invoke the IAM interface.

WKS.0010 Nonexistent resource.

WKS.0011 The user has not applied for Workspace.

WKS.0020 The request URL contains invalid characters.

WKS.0021 You cannot perform this operation because theinfrastructure servers are being backed up.

WKS.0022 You cannot perform this operation because theinfrastructure servers are being restored.

WKS.0023 You cannot perform this operation because theinfrastructure servers failed to be restored.

WKS.0024 Failed to invoke the IMS interface.

Desktopprovisioning

WKS.0101 The ECS service failed to execute the ECS creationjob.

WKS.0102 The ECS task timed out.

WKS.0103 Failed to create or check the user.

WKS.0104 Failed to import the desktop to FusionAccess.

WKS.0105 Provisioning failed.

WKS.0106 Insufficient quota.

WKS.0107 Failed to execute the child task.

WKS.0108 The IP address does not exist on the subnet.

WKS.0109 The IP address is in use.



91


WKS.0110 Invalid subnet.

WKS.0111 Insufficient IP addresses on the subnet.

WKS.0112 The license is invalid or the number of licensesreaches the upper limit.

WKS.0113 Failed to verify the computer name existence in thedomain.

WKS.0114 The computer name already exists in the domain.

WKS.0115 The specified OU does not exist.

Workspaceservice

WKS.0201 Only properties of Workspace that is applied forsuccessfully can be modified.

WKS.0202 Failed to modify domain configuration.

WKS.0203 Failed to change the domain password.

WKS.0204 The new password does not comply with passwordpolicies. Please check the password length,complexity, and historical password requirements.

WKS.0205 Desktops are being created, and the Workspaceproperties cannot be modified.

WKS.0206 The user has applied or is applying for Workspace.

WKS.0207 A user cannot cancel Workspace in the current servicestatus.

WKS.0208 Failed to configure the infrastructure server.

WKS.0209 Failed to configure LITE_AD.

WKS.0210 The infrastructure server is unreachable.

WKS.0211 Workspace cannot be canceled because desktops exist.

WKS.0212 An exception occurs during the application ofWorkspace. Please contact the O&M personnel.

WKS.0213 Failed to create the infrastructure server.

WKS.0214 Weak password. Enter a strong password.

Productpackage

WKS.0300 Failed to obtain the package information.

WKS.0301 The product package does not exist.

Desktopmanagement

WKS.0401 Abnormal desktop status.

WKS.0402 The desktop is being deleted and cannot be modified.

WKS.0403 The desktop fails to be deleted and cannot bemodified.



92


WKS.0404 Failed to modify desktop attributes.

WKS.0405 The desktop cannot be modified because it is notstarted.

WKS.0406 The desktop cannot be modified because it is beingstarted, shut down, or restarted.

WKS.0407 This operation cannot be performed because disks arebeing added.

WKS.0408 The operating status of the desktop does not supportspecifications change.

WKS.0409 This operation is not allowed because desktopspecifications are being changed.

A.3 LITE_AD Sensitive AccountsDuring Workspace application, if the domain type is LITE_AD, the following sensitiveaccounts cannot be set as the domain administrator account:

USER

USERS

GUEST

GUESTS

KRBTGT

DNSADMINS

IIS_IUSRS

DNSADMINS

REPLICATOR

DOMAINUSERS

DOMAINADMINS

DOMAINGUESTS

SCHEMAADMINS

ADMINISTRATOR

PRINTOPERATORS

ADMINISTRATORS

CERTPUBLISHERS

DNSUPDATEPROXY



93

DOMAINCOMPUTERS

EVENTLOGREADERS

BACKUPOPERATORS

SERVEROPERATORS

ACCOUNTOPERATORS

RASANDIASSERVERS

ENTERPRISEADMINS

DOMAINCONTROLLERS

REMOTEDESKTOPUSERS

DISTRIBUTEDCOMUSERS

PERFORMANCELOGUSERS

CRYPTOGRAPHICOPERATORS

PERFORMANCEMONITORUSERS

A.4 Reference Table for Connection Failure Causes

Table A-1 Reference table for connection failure causes

Error Code Connection Failure Cause

400200 The desktop is being prepared.

400201 Pre-connection failed.

400202 Another user has logged in to the desktop.

400205 Abnormal state of desktop.

400208 Connection timeout.

400210 Failed to obtain key information.

400211 Preempted by new connections.

400212 The desktop is in maintenance.

400213 Calling the desktop's authentication interface failed.

28104009 Another user is connecting through HDP.

28104004 Pre-connection fails due to timeout.

28104005 Failed to log off in the assigned time.

28104006 Another user is connecting through RDP.

28104007 Failed to obtain the monitoring port.



94

Error Code Connection Failure Cause

28104011 Signature verification failed.

28104012 Timestamp check failed.

28104013 Login failed. The username, domain, or password may be wrong.

28104015 Connection is being processed. Please try again later.

A.5 Workspace Monitoring Metrics

Function Description

This section describes monitoring metrics reported by Workspace to Cloud Eye Service aswell as their namespaces and dimensions. You can use APIs provided by CES to query themonitoring metrics generated for Workspace.

Namespace

SYS.Workspace

Monitoring Metrics

Metric Name Description ValueRange

Remark

cpu_util CPUusage

Measures the CPU usage ofa measurement object (unit:%).

0% to100%

Measurementobject:Infrastructure server

mem_util Memoryusage

Measures the memoryusage of a measurementobject (unit: %).

0% to100%


disk_util_inband

Diskusage

Measures the disk usage ofa measurement object (unit:%).

0% to100%


iops IOPS Measures the number of I/Ooperations per second on ameasurement object.

≥ 0counts


bytes_in Networkinputthroughput

Measures incomingnetwork traffic of ameasurement object persecond (unit: bytes/s).

≥ 0bytes/s


bytes_out Networkoutputthroughput

Measures outgoing networktraffic of a measurementobject per second (unit:bytes/s).

≥ 0bytes/s




95

DimensionsKey Value

instance_id ID of an infrastructure server instance



96

B Change History

Release Date What's New

2018-03-30 This is the second official release.Modified the following contents:l Revised the value range of data disk size and the example value

of data disks in Creating Desktops.l Revised the example value of data disks in Querying Desktop

Details and Querying the Desktop Detail List.

2018-01-31 This issue is the first official release.

WorkspaceAPI Reference B Change History


97

api reference · api calling public cloud apis comply with the restful api design principles....

Documents