api reference · the public cloud service provides restful apis. representational state transfer...

Scalable File Service

API Reference

Issue 01

Date 2017-09-23

HUAWEI TECHNOLOGIES CO., LTD.

Issue 01 (2017-09-23) Huawei Proprietary and Confidential

Copyright © Huawei Technologies Co., Ltd.

i

Copyright © Huawei Technologies Co., Ltd. 2017. All rights reserved.

No part of this document may be reproduced or transmitted in any form or by any means without prior

written consent 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 respective

holders.

Notice

The purchased products, services and features are stipulated by the contract made between Huawei and

the customer. All or part of the products, services and features described in this document may not be

within the purchase 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 or

representations of any kind, either express or implied.

The information in this document is subject to change without notice. Every effort has been made in the

preparation of this document to ensure accuracy of the contents, but all statements, information, and

recommendations in this document do not constitute a warranty of any kind, express or implied.

Huawei Technologies Co., Ltd.

Address: Huawei Industrial Base

Bantian, Longgang

Shenzhen 518129

People's Republic of China

Website: http://www.huawei.com

Email: [email protected]

http://www.huawei.com/

mailto:[email protected]


API Reference Contents



ii

Contents

1 API Calling ..................................................................................................................................... 1

1.1 Service Usage ............................................................................................................................................................... 1

1.2 Making a Request ......................................................................................................................................................... 1

1.3 Request Authentication Methods .................................................................................................................................. 2

1.4 Token Authentication .................................................................................................................................................... 2

1.5 AK/SK Authentication .................................................................................................................................................. 3

1.5.1 AK and SK Generation .............................................................................................................................................. 3

1.5.2 Request Signing Procedure ........................................................................................................................................ 4

1.5.3 Sample Code .............................................................................................................................................................. 4

1.6 Obtaining a Project ID ................................................................................................................................................ 13

2 Common Message Headers ....................................................................................................... 15

2.1 Common Request Headers .......................................................................................................................................... 15

2.2 Common Response Headers ....................................................................................................................................... 16

3 File Sharing .................................................................................................................................. 17

3.1 Creating a Shared File System .................................................................................................................................... 17

3.2 Querying Details About All Shared File Systems ....................................................................................................... 22

3.3 Querying Details About a Shared File System ............................................................................................................ 27

3.4 Querying Export Locations of a Shared File System .................................................................................................. 31

3.5 Modifying a Shared File System................................................................................................................................. 33

3.6 Deleting a Shared File System .................................................................................................................................... 37

4 Share Access Rules ...................................................................................................................... 39

4.1 Adding a Share Access Rule ....................................................................................................................................... 39

4.2 Deleting a Share Access Rule ..................................................................................................................................... 42

4.3 Querying a Share Access Rule .................................................................................................................................... 44

5 Quota Management .................................................................................................................... 47

5.1 Querying a Quota ........................................................................................................................................................ 47

6 Capacity Expansion or Reduction ............................................................................................ 50

6.1 Expanding the Capacity of a Shared File System ....................................................................................................... 50

6.2 Reducing the Capacity a Shared File System ............................................................................................................. 52

A Change History ........................................................................................................................... 55


API Reference 1 API Calling



1

1 API Calling

API requests sent by third-party applications to the public cloud service must be authenticated

using signatures.

This chapter describes the overall method of using signatures and provides sample codes to

detail how to use the default signer to sign requests and how to use an HTTP client to send

requests.

1.1 Service Usage

The public cloud service provides RESTful APIs.

Representational State Transfer (REST) allocates Uniform Resource Identifiers (URIs) to

dispersed resources so that the resources can be located. Applications on clients use Uniform

Resource Locators (URLs) to obtain the 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. Obtain

this value from section Regions and Endpoints.

uri Specifies the API access path for performing a specified operation.

Obtain this value from the URI of the API, for example,

v3/auth/tokens.

1.2 Making a Request

The HTTP protocol defines request methods, such as GET, PUT, POST, DELETE, and

PATCH, to indicate the desired action to be performed on the identified resource. RESTful

APIs provided by services support the following methods.

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





2

Table 1-2 HTTPS 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 the

supplied URI.

POST The POST method requests that the server accept the entity enclosed in the

request as a new subordinate of the web resource identified by the URI.

DELETE The DELETE method deletes the specified resource, for example, an

object.

PATCH The PATCH method applies partial modifications to a resource.

If the resource does not exist, the PATCH method creates a resource.

1.3 Request Authentication Methods

You can use either of the following two authentication methods to call APIs:

Token authentication: Requests are authenticated using Tokens.

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-Token

to 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 Call

1. 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:

Replace the items in italic in the following example with actual ones. For details, see the Identity and

Access Management API Reference.

{

"auth": {

"identity": {






3

"methods": [

"password"

],

"password": {

"user": {

"name": "username",

"password": "password",

"domain": {

"name": "domainname"

}

}

}

},

"scope": {

"project": {

"name": "cn-north-1" //The region name "cn-north-1" is used as an example.

}

}

}

}

2. Obtain the token. For details, see section "Obtaining the User Token" in the Identity and

Access Management API Reference.

3. Make a call to a service API, add X-Auth-Token to the message header, and set the

value of X-Auth-Token to the token obtained in step 2.

1.5 AK/SK Authentication

When you use an API gateway to send requests to underlying services, the requests are signed

using the AK and SK.

AK: indicates the unique ID of the secret access key. AK is used together with SK to obtain an

encrypted signature for a request.

SK: indicates the secret access key used together with the access key ID to sign requests. AK and SK

can be used together to identify a request sender to prevent the request from being modified.

1.5.1 AK and SK Generation

1. Log in to the management console.

2. Click the username and choose My Credential from the drop-down list.

3. Click Access Credentials.

4. Click Add Access Key to switch to the Add Access Key page.

5. Enter the password used for the current login.

6. Enter the authentication code received in the email or mobile phone.

For users created in Identity and Access Management (IAM), if no email address or mobile phone is

filled during the user creation, you only need to authenticate the login password.

7. Click OK to download the access key.





4

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

1.5.2 Request Signing Procedure

Preparations

1. Download the API Gateway signature tool.

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

2. Extract the package.

3. Create a Java project, and reference the extracted JAR to the dependency path.

Sign a Request

1. 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

obtain a signing tool.

b. Call Signer.sign(Request<?> request, Credentials credentials) to sign the request

created 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 make

an API call and copy the header of the signed request to the new request.

For example, if Apache HttpClient is used, convert DefaultRequest to HttpRequestBase

and copy the header of the signed DefaultRequest to HttpRequestBase.

For details, see descriptions of AccessServiceImpl.java in section 1.5.3 Sample Code.

1.5.3 Sample Code

The following three types of codes show how to sign a request and how to use an HTTP client

to send an HTTPS request:

AccessService: indicates the abstract class that converts the GET, POST, PUT, and DELETE

methods into the access method.

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

sending.

AccessServiceImpl: indicates the implementation of the access method, which contains the

codes required for API gateway communication.

For details about region and serviceName in the following codes, see Regions and

Endpoints:

AccessService.java:

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







5

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;

}





6

public String getRegion() {

return region;

}

public void setRegion(String region) {

this.region = region;

}

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.net.URISyntaxException;


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.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;





7

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;


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} */

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.





8

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();

// 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,





9

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;



contentLength);

putMethod.setEntity(entity);

}

} else if (httpMethod == HttpMethodName.PATCH) {

HttpPatch patchMethod = new HttpPatch(url.toString());

httpRequest = patchMethod;



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 {

if (client != null) {

client.close();

}

} catch (IOException e) {

// It is recommended to add logs in this place.


}





10

}

}

Demo.java:


import java.io.BufferedReader;

import java.io.ByteArrayInputStream;

import java.io.IOException;


import java.io.InputStreamReader;

import java.net.MalformedURLException;




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





11

//replace real url

String deleteUrl = "urlString";

delete(ak, sk, deleteUrl);

}

public static void put(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.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) {


} finally {

accessService.close();

}

}

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

String putBody) {


try {



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()));



} finally {


}

}

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






12

try {



HttpMethodName httpMethod = HttpMethodName.DELETE;

HttpResponse response = accessService.access(url, httpMethod);


.getContent()));



} finally {


}

}

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


try {



HttpMethodName httpMethod = HttpMethodName.GET;

HttpResponse response;

response = accessService.access(url, httpMethod);


.getContent()));



} finally {


}

}

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) {


}

InputStream content = new ByteArrayInputStream(postbody.getBytes());

HttpMethodName httpMethod = HttpMethodName.POST;

HttpResponse response;

try {

response = accessService.access(url, content,

(long) postbody.getBytes().length, httpMethod);






13

.getContent()));



} finally {


}

}

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");

}



} finally {

try {

is.close();



}

}

return sb.toString();

}

}

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 ID

A project ID (which can be project_id or tenant_id because project_id has the same

meaning as tenant_id in this document) is required for some URLs when an API is called.

Therefore, you need to obtain a project ID on the console before calling an API. The steps are

as follows:

1. Log in to the management console.

2. Click the username and choose My Credential from the drop-down list.

On the Authentication Center page, view project IDs in the project list.





14

Figure 1-1 Viewing project IDs


API Reference 2 Common Message Headers



15

2 Common Message Headers

This chapter describes the 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 time

when the request is

sent. The time is in

YYYYMMDD'T'H

HMMSS'Z' format.

The value is the

current GMT time of

the system.

No

This parameter

is mandatory

for AK/SK

authentication.

20150907T101459Z

Authorization Specifies the

authentication

information.

The value can be

obtained from the

request signing

result.

For details, see

section 1.5.2 Request

Signing Procedure.

No

This parameter

is mandatory

for AK/SK

authentication.

SDK-HMAC-SHA256

Credential=ZIRRKMTWPT

QFQI1WKNKB/20150907//

ec2/sdk_request,

SignedHeaders=content-type

;host;x-sdk-date,

Signature=55741b610f3c9fa

3ae40b5a8021ebf7ebc2a28a

603fc62d25cb3bfe6608e199

4

Host Specifies the server

domain name and

port number of the

resources being

requested. The value

can be obtained from

the URL of the

service API. The value is

No

This parameter

is mandatory

for AK/SK

authentication.

code.test.com

or

code.test.com:443


API Reference 2 Common Message Headers



16

Parameter Description Mandatory Example Value

hostname[:port]. If

the port number is

not specified, the

default port is used.

The default port

number for https is

port 443.

Content-type Specifies the request

body MIME type.

Yes application/json

Content-Length Specifies the length

of the request body.

The unit is byte.

This parameter

is mandatory

for POST and

PUT requests

but must be left

blank for GET

requests.

3495

X-Project-Id Specifies the project

ID. This parameter is

used to obtain the

token for the project.

This parameter is

mandatory for a

request from a DeC

or multi-project user.

No e9993fc787d94b6c886cbaa3

40f9c0f4

X-Auth-Token Specifies the user

token.

No

This parameter

is mandatory

for token

authentication.

None

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

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

Date Specifies the time when a request response is returned.

Content-type Specifies the response body MIME type.


API Reference 3 File Sharing



17

3 File Sharing

Partial interfaces provided by Scalable File Service (SFS) are the same as those provided by

OpenStack Manila of the Mitaka version. For details about how to user them, visit the

community:

https://developer.openstack.org/api-ref/shared-file-systems

If description about an interface in this document differs from that in the community,

description in this document prevails.

3.1 Creating a Shared File System

Function

This interface is used to create a shared file system.

This interface is an asynchronous interface. If the return value is 200, the request sent by the interface is

successfully received. Later, you can query the status of the shared file system in the shared file system

details to identify whether the creation is complete and successful.

URI POST /v2/{tenant_id}/shares

Parameter description

Name Mandatory Type Description

tenant_id Yes string Specifies the tenant ID of the operator.

Request Parameter description


share Yes object Specifies the share object.





18

Description of field share

Name Mandatory

Type Description

share_prot

o

Yes string Specifies the protocol for sharing file

systems. The value is NFS.

size Yes integer Specifies the size of the shared file system in

GB.

name No string Specifies the name of the shared file system.

The value contains 0 to 255 characters.

descriptio

n

No string Describes the shared file system. The value

contains 0 to 255 characters.

snapshot_i

d

No string Specifies the UUID (0 to 36 characters) of

the source snapshot that was used to create

the shared file system. This parameter is

reserved, because snapshots are not

supported currently.

is_public No boolean (Since API v2.8) Specifies the level of

visibility for the shared file system. To make

the shared file system public, set it to true.

To make the shared file system private, set it

to false. The default value is false.

share_typ

e

No string Specifies the share type. This value

determines the storage service type for the

shared file system, such as high-performance

storage (composed of SSDs) or

large-capacity storage (composed of SATA

disks). Currently, only one service type is

supported and the parameter will be

automatically set to the supported one. Do

not manually set it, because the file service

will fail to be applied for if an unsupported

type is entered.

consistenc

y_group_i

d

No string (Since API v2.4) Specifies the UUID of the

consistency group in which the shared file

system will be created. The share type of

share_network_id of the consistency group

must be consistent with share_type.

availabilit

y_zone

No string Specifies the availability zone name. If this

parameter is left blank, the default

availability zone will be used. If the default

availability zone contains no storage

resources, the creation of the shared file

system fails. The value contains 0 to 255

characters.

metadata No object Sets that one or more metadata key and value





19

Name Mandatory

Type Description

pairs as a dictionary of strings. No key and

value pairs need to be re-defined for this

interface.

share_net

work_id


the share network to which the share service

belongs or will be created. This parameter is

reserved, because share network

management is not supported currently.

Example request

{

"share": {

"share_type": null,

"name": "test",

"snapshot_id": null,

"description": "test description",

"metadata": {

"key1": "value1",

"key2": "value2"

},

"share_proto": "NFS",

"share_network_id": null,

"size": 1,

"is_public": false

}

}

Response Parameter description




Name Mandatory

Type Description

id Yes string Specifies the UUID of the shared file

system.

status Yes string Specifies the status of the shared file system.

links Yes array Specifies the share links.

project_id Yes string Specifies the UUID of the project in which

the shared file system was created.





20

Name Mandatory

Type Description

share_prot

o

Yes string Specifies the protocol for sharing file

systems.

size Yes integer Specifies the size of the shared file system in

GB. The requested capacity of the shared

file system cannot be larger than the allowed

quota. To view the allowed quota, use the

interface for querying a quota.

name Yes string Specifies the name of the shared file system.

descriptio

n

Yes string Describes the shared file system.

share_type Yes string Specifies the storage service type assigned

for the shared file system, such as

high-performance storage (composed of

SSDs) and large-capacity storage (composed

of SATA disks).

is_public No boolean Specifies the visibility level of the shared

file system. To make the shared file system

visible to all tenants, set it to true. To make

the shared file system only visible to the

owning tenant, set it to false.

volume_ty

pe

No string Specifies the volume type.

snapshot_i

d


the source snapshot that was used to create

the shared file system. This parameter is



metadata No object Specifies that one or more metadata key and

value pairs as a dictionary of strings. It is the

used capacity of the shared file system. The

key is share_used and the value is a decimal

number in bytes. This key value is

automatically refreshed every 30 minutes.

share_net

work_id

Yes string Specifies the UUID of the share network.

This parameter is reserved, because share

network management is not supported

currently.

availabilit

y_zone

Yes string Specifies the availability zone.

export_loc

ation

No string Specifies the export location.

export_loc

ations No array Lists the export locations.





21

Name Mandatory

Type Description

host Yes string Specifies the host name of the shared file

system.

created_at Yes string Specifies the date and time stamp when the

shared file system was created.

Example response

{

"share": {

"status": "creating",

"project_id": "16e1ab15c35a457e9c2b2aa189f544e1",

"name": "share_London",

"share_type": "25747776-08e5-494f-ab40-a64b9d20d8f7",

"availability_zone": az1.dc1,

"created_at": "2015-09-18T10:25:24.533287",

"export_location": null,

"links": [

{

"href":

"http://172.18.198.54:8786/v1/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-

fbc3-4e4a-9993-9ea223f73264",

"rel": "self"

},

{

"href":

"http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/shares/011d21e2-fbc

3-4e4a-9993-9ea223f73264",

"rel": "bookmark"

}

],


"export_locations": [],


"host": null,

"volume_type": "default",


"is_public": true,

"metadata": {

"project": "my_app",

"aim": "doc"

},

"id": "011d21e2-fbc3-4e4a-9993-9ea223f73264",

"size": 1,

"description": "My custom share London"

}

}

When the client receives the system response, the shared file system is still being created. For this reason,

the share path cannot be queried immediately. You can use the interface to query the share path after the

creation is complete.





22

Return Value Normal

200

Abnormal

Return Value Description

400 Bad Request The server failed to process the request.

401 Unauthorized You must enter a username and password to

access the requested page.

403 Forbidden You are forbidden to access the requested page.

404 Not Found The requested page was not found.

405 Method Not Allowed You are not allowed to use the method specified in

the request.

406 Not Acceptable The response generated by the server cannot be

accepted by the client.

407 Proxy Authentication Required You must use the proxy server for authentication.

Then, the request can be processed.

408 Request Timeout The request timed out.

409 Conflict The request cannot be processed due to a conflict.

500 Internal Server Error Failed to complete the request because of an

internal service error.

501 Not Implemented Failed to complete the request because the server

does not support the requested function.

502 Bad Gateway Failed to complete the request because the request

is invalid.

503 Service Unavailable Failed to complete the request because the service

is unavailable.

504 Gateway Timeout A gateway timeout error occurred.

3.2 Querying Details About All Shared File Systems

Function

This interface is used to query the details about all shared file systems.

URI GET

/v2/{tenant_id}/shares/detail?all_tenants={all_tenants}&project_id={project_id}&status

={status}&limit={limit}&offset={offset}&sort_key={sort_key}&sort_dir={sort_dir}





23



tenant_id Yes string Specifies the tenant ID of the

operator.

all_tenants No (query

parameter) integer (Administrators only) Defines

whether to list shared file systems of

all tenants. To list shared file systems

of all tenants, set it to 1. To list

shared file systems of the current

tenant, set it to 0.

project_id No (query

parameter)

string Specifies the UUID of the project in

which the shared file system was

created. This parameter is used

together with all_tenants.

status No (query

parameter) string Filters shared file systems by status.

Possible values are creating, error,

available, deleting, error_deleting,

manage_starting, manage_error,

unmanage_starting,

unmanage_error, unmanaged,

extending, extending_error,

shrinking, shrinking_error, and

shrinking_possible_data_loss_error.

limit No (query

parameter)

integer Specifies the maximum number of

shared file systems that can be

returned.

offset No (query

parameter)

integer Specifies the offset to define the start

point of shared file system listing.

sort_key No (query

parameter)

string Specifies the keyword for sorting the

queried shared file systems. Possible

values are id, status, size, host,

share_proto, user_id, project_id,

created_at, updated_at,

display_name, name,

share_type_id, share_network_id,

and snapshot_id.

sort_dir No (query

parameter)

string Specifies the direction to sort shared

file systems. Possible values are asc

(ascending) and desc (descending).


None

Example request





24

None







availability_z

one

No string Specifies the availability zone.

share_networ

k_id

Yes string Specifies the UUID of the share

network. This parameter is

reserved, because share network

management is not supported

currently.

snapshot_id No string Specifies the UUID (0 to 36

characters) of the source snapshot

that was used to create the shared

file system. This parameter is



id Yes string Specifies the UUID of the shared

file system.

size Yes integer Specifies the size of the shared file

system in GB.

project_id Yes string Specifies the UUID of the project

in which the shared file system was

created.

metadata No object Sets that one or more metadata key

and value pairs as a dictionary of

strings.

consistency_g

roup_id

No string Specifies the UUID of the

consistency group. This parameter

is reserved, because consistency

groups are not supported currently.

status Yes string Specifies the status of the shared

file system.

description No string Describes the shared file system.

host Yes string Specifies the host name of the





25

shared file system.

created_at Yes string Specifies the date and time stamp

when the shared file system was

created.

share_proto Yes string Specifies the protocol for sharing

file systems.

volume_type No string Specifies the volume type.

name Yes string Specifies the name of the shared

file system.

share_type Yes string Specifies the protocol for sharing

file systems.

export_locatio

ns

No array Lists the export locations.

Currently, only a single export

location is supported. This

parameter exists only when

X-Openstack-Manila-Api-Version specified in the request header is

smaller than 2.8.

export_locatio

n

No string Specifies the export location. This


X-Openstack-Manila-Api-Version specified in the request header is

smaller than 2.8.

is_public No bool Specifies the visibility level of the

shared file system. To make the

shared file system visible to all

tenants, set it to true. To make the

shared file system only visible to

the owning tenant, set it to false.

Example response

{

"shares": [

{

"links": [

{

"href":

"https://100.133.170.97:8796/v2/61b01a94b84448cfac2424e46553d7e7/shares/54d0bac

6-45c8-471c-bf0d-16ffd81ef88a",

"rel": "self"

},

{

"href":

"https://100.133.170.97:8796/61b01a94b84448cfac2424e46553d7e7/shares/54d0bac6-4

5c8-471c-bf0d-16ffd81ef88a",

"rel": "bookmark"

}





26

],

"export_location": "sfs.dong.com:/share-e1c2d35e",

"availability_zone": "az1.dc1",



"id": "54d0bac6-45c8-471c-bf0d-16ffd81ef88a",

"size": 1,

"share_type": "default",

"consistency_group_id": null,

"project_id": "da0f615c35eb4d72812d1547a77b5394",

"metadata": {},

"status": "available",

"description": "test description",

"export_locations": ["sfs.dong.com:/share-e1c2d35e"],

"host":

"DJ01@9656beb1-7ce2-4c46-9911-ecd51ab632bf#9656beb1-7ce2-4c46-9911-ecd51ab632bf

",

"is_public": false,

"name": "cl01",

"created_at": "2017-07-07T03:15:06.858662",


"volume_type": "default"

}

]

}

Return Value Normal

200

Abnormal








the request.












27






is invalid.


is unavailable.


3.3 Querying Details About a Shared File System

Function

This interface is used to query details about a shared file system.

URI GET /v2/{tenant_id}/shares/{share_id}


Name Mandatory

Type Description

share_id Yes string Specifies the UUID of the shared file

system.

tenant_id Yes string Specifies the tenant ID in a multi-tenant

cloud scenario.


None

Example request

None


Name Mandatory

Type Description






28


Name Mandatory

Type Description


availability_

zone


share_server

_id

Yes string Specifies the UUID for managing share

services.

share_netwo

rk_id



network management is not supported

currently.

snapshot_id No string Specifies the UUID of the source snapshot

that was used to create the shared file

system. This parameter is reserved, because

snapshots are not supported currently.

snapshot_su

pport

Yes boolean Specifies whether snapshots are supported.

This parameter is reserved, because

snapshots are not supported currently.


system.

size Yes integer Specifies the size of the shared file system

in GB.

consistency

_group_id

No string Specifies the UUID of the consistency

group. This parameter is reserved, because

consistency groups are not supported

currently.

project_id Yes string Specifies the UUID of the project in which


metadata No object Sets that one or more metadata key and

value pairs as a dictionary of strings.

status Yes string Specifies the status of the shared file

system.

task_state Yes string Specifies the data migration status. This

parameter is reserved, because data

migration is not supported currently.

has_replicas Yes boolean Specifies whether replicas exist. This

parameter is reserved, because replication is

not supported currently.

replication_t

ype No string Specifies the replication type. This

parameter is reserved, because replication is





29

Name Mandatory

Type Description

not supported currently.


host No string Specifies the host name of the shared file

system.

name No string Specifies the name of the shared file system.

created_at Yes string Specifies the date and time stamp when the

shared file system was created.

access_rules

_status

Yes string Specifies the configuration status of the

access rule. Possible values are active

(effective), error (configuration failed),

syncing (configuration in progress).

share_proto Yes string Specifies the protocol for sharing file

systems.

volume_typ

e

No string Specifies the volume type. The definition of

this parameter is the same as that of

share_type.

share_type_

name

Yes string Specifies the storage service type assigned

for the shared file system, such as

high-performance storage (composed of

SSDs) and large-capacity storage

(composed of SATA disks).

share_type Yes string Specifies the UUID of the share type.

export_locat

ions

No array Lists the export locations. Currently, only a

single export location is supported. This


X-Openstack-Manila-Api-Version specified in the request header is smaller

than 2.8.

export_locat

ion

No string Specifies the export location. This


X-Openstack-Manila-Api-Version specified in the request header is smaller

than 2.8.

is_public No bool (Since API v2.8) Specifies the level of

visibility for the shared file system. To

make the shared file system public, set it to

true. To make the shared file system

private, set it to false. The default value is

false.

source_cgsn

apshot_me

mber_id

Yes string Specifies the UUID of the snapshot's

source. This parameter is reserved, because

consistency snapshot is not supported





30

Name Mandatory

Type Description

currently.

Example response

{

"share":

{"share_type_name": "default",

"links": [{"href":

"https://192.145.22.48:8796/v2/e730d004ee914ecdbfafed7c315dd9a0/shares/279e745e

-80b6-45e0-a5f8-cee16b1eb13f", "rel": "self"},

{"href":

"https://192.145.22.48:8796/e730d004ee914ecdbfafed7c315dd9a0/shares/279e745e-80

b6-45e0-a5f8-cee16b1eb13f", "rel": "bookmark"}],

"export_location": "sfs.dong.com:/share-e1c2d35e",



"share_server_id": null,


"id": "279e745e-80b6-45e0-a5f8-cee16b1eb13f",

"size": 10,

"share_type": "36ff7c75-e501-45bd-9b78-6b44cd695c9a",

"consistency_group_id": null,

"project_id": "5751d8c3f2f6415993ee4326b41630ec",

"metadata": {"share_used": "0"},

"status": "available",

"description": null,

"export_locations": ["sfs.dong.com:/share-e1c2d35e"],

"host":

"DJ01@cda055ec-772a-470d-ac0f-64ba618d76ad#cda055ec-772a-470d-ac0f-64ba618d76ad

",

"access_rules_status": "active",

"is_public": false,

"task_state": null,

"snapshot_support": true,

"name": null,

"has_replicas": false,

"replication_type": null,

"created_at": "2017-08-09T09:32:51.742721",


"volume_type": "default",

"source_cgsnapshot_member_id": null}

}

Return Value Normal

200

Abnormal






31








the request.












is invalid.


is unavailable.


3.4 Querying Export Locations of a Shared File System

Function

This interface is used to query export locations of a shared file system.

This interface exists only when X-Openstack-Manila-Api-Version in the request header is equal to or

greater than 2.9.

URI GET /v2/{tenant_id}/shares/{share_id}/export_locations






32

Name Mandatory

Type Description


system.


cloud scenario.


None

Example request

None


Name Mandatory

Type Description

export_locations Yes object Specifies the share object.


Name Mandatory

Type Description

id Yes string Specifies the UUID of the export location of

the shared file system.

share_instan

ce_id

Yes string Specifies the UUID of the shared file

system instance.

path Yes string Specifies the path to which the shared file

system will be mounted.

is_admin_o

nly

Yes boolean Specifies whether the shared file system is

only visible to administrators and its owner.

Possible values are true (yes) and its owner

and false (no, and the shared file system is

visible to all users).

preferred No boolean Identifies which export locations are most

efficient and are used preferentially when

multiple export locations exist.

Example response





33

{

"export_locations": [

{

"path": "sfs-9000.dong.com:/share-e1c2d35e",

"share_instance_id": "e1c2d35e-fe67-4028-ad7a-45f668732b1d",

"is_admin_only": false,

"id": "b6bd76ce-12a2-42a9-a30a-8a43b503867d",

"preferred": false

}

]

}

Return Value Normal

200

Abnormal







3.5 Modifying a Shared File System

Function

This interface is used to modify the name and description of a shared file system.

URI PUT /v2/{tenant_id}/shares/{share_id}


Name Mandatory

Type Description


system.


cloud scenario.





34


Name Mandatory

Type Description



Name Mandatory

Type Description

display_name Yes String Specifies the new name of the shared file

system. The value consists of 1 to 255

characters.

display_descr

iption

No String Describes the shared file system. The

value contains 0 to 255 characters.

Example request

{

"share": {

"display_name": "testshare",

"display_description": "test"

}

}


Name Mandatory

Type Description



Name Mandatory

Type Description


availability_z

one


share_networ

k_id



network management is not supported currently.





35

Name Mandatory

Type Description

share_type Yes string (Since API v2.6) Specifies the UUID of

the share type. In minor versions, this

parameter indicates the share type, as a

string.

snapshot_id No string Specifies the UUID of the source

snapshot that was used to create the

shared file system.


system.

size Yes integer Specifies the size of the shared file

system in GB.

project_id Yes string Specifies the UUID of the project in

which the shared file system was created.

metadata No object Sets that one or more metadata key and

value pairs as a dictionary of strings.

consistency_

group_id

No string Specifies the UUID of the consistency

group. This parameter is reserved,

because consistency groups are not


status Yes string Specifies the status of the shared file

system.


host No string Specifies the host name of the shared file

system.

name No string Specifies the name of the shared file

system.

created_at Yes string Specifies the date and time stamp when


share_proto Yes string Specifies the protocol for sharing file

systems.

volume_type No string Specifies the volume type.

is_public No bool (Since API v2.8) Specifies the level of

visibility for the shared file system. To

make the shared file system public, set it

to true. To make the shared file system

private, set it to false. The default value is

false.

Example response





36

{

"share": {

"links": [

{

"href":

"https://100.133.170.97:8796/v2/61b01a94b84448cfac2424e46553d7e7/shares/4629a30

8-189a-4c7d-9b0c-1dc5ff8ba398",

"rel": "self"

},

{

"href":

"https://100.133.170.97:8796/61b01a94b84448cfac2424e46553d7e7/shares/4629a308-1

89a-4c7d-9b0c-1dc5ff8ba398",

"rel": "bookmark"

}

],

"export_location": "sfs.dong.com:/share-33816c98",




"id": "4629a308-189a-4c7d-9b0c-1dc5ff8ba398",

"size": 1,

"share_type": "33d665c8-c227-4e1b-ade1-e2996cd40147",

"project_id": "da0f615c35eb4d72812d1547a77b5394",

"metadata": {},

"status": "inactive",

"description": "test",

"export_locations": [],

"host":

"DJ01@9656beb1-7ce2-4c46-9911-ecd51ab632bf#9656beb1-7ce2-4c46-9911-ecd51ab632bf

",

"is_public": false,

"name": "testcl",

"created_at": "2017-07-07T03:15:01.697772",


"volume_type": "cltype"

}

}

Return Value Normal

200

Abnormal











37



the request.












is invalid.


is unavailable.


3.6 Deleting a Shared File System

Function

This API is used to delete a shared file system.



details to identify whether the deletion is complete and successful.

URI DELETE /v2/{tenant_id}/shares/{share_id}


Name Mandatory

Type Description


system.


cloud scenario.





38


None

Example request

None

Response Example response

None

Return Value Normal

202

Abnormal








the request.












is invalid.


is unavailable.



API Reference 4 Share Access Rules



39

4 Share Access Rules

4.1 Adding a Share Access Rule

Function

This interface is used to add a share access rule.


successfully received. Later, you can query the share access rule status to identify whether the rule

adding is complete and successful.

URI POST /v2/{tenant_id}/shares/{share_id}/action


Name Mandatory

Type Description


system.


cloud scenario.



os-allow_acc

ess

Yes object Specifies the os-allow_access object.

Description of field os-allow_access





40

Name Mandatory

Type Description

access_level Yes string Specifies the access level to the shared file

system. Possible values are ro (read-only)

and rw (read-write).

access_type Yes string Specifies type of the share access rule. For

NFS shared file systems, the value can only

be cert. When this parameter is set to cert

for NFS shared file systems, set access_to

to the VPC ID.

access_to Yes string Specifies the access rule. The value

contains 1 to 255 characters. When

access_type is set to cert, this parameter is

available and must be the VPC ID.

Example request

{

"os-allow_access": {

"access_to": "59cd070d-9c4c-462e-9dcc-b6bb716225bc",

"access_type": "cert",

"access_level": "rw"

}

}



access Yes object Specifies the access object. If the share

access rule is not updated, this value is null.

Description of field access

Name Mandatory

Type Description


system to which the access rule is added.

access_type Yes string Specifies the type of the share access rule.

access_to Yes string Specifies the access that the back end

grants or denies.

access_level Yes string Specifies the access level of the shared file

system.

id Yes string Specifies the UUID of the share access





41

Name Mandatory

Type Description

rule.

state Yes string Specifies the status of the share access rule.

Possible values are active and error.

Example response

{

"access": {

"share_id": "15940c49-789f-476a-b099-a3be7d311854",


"access_to": "59cd070d-9c4c-462e-9dcc-b6bb716225bc",

"access_level": "rw",

"state": "new",

"id": "418e3cf4-08c3-4ed2-a29a-ceffa346b3b8"

}

}

Return Value Normal

200

Abnormal








the request.















42



is invalid.


is unavailable.


4.2 Deleting a Share Access Rule

Function

This interface is used to delete a share access rule.


successfully received. Later, you can query the share access rule status to identify whether the rule

deletion is complete and successful.



Name Mandatory

Type Description


system.


cloud scenario.



os-deny_access Yes object Specifies the os-deny_access object.

Description of field os-deny_access


access_id Yes string Specifies the UUID of the share access

rule of the shared file system. The value





43


contains 1 to 36 characters.

Example request

{

"os-deny_access": {

"access_id": "418e3cf4-08c3-4ed2-a29a-ceffa346b3b8"

}

}


None

Example response

None

Return Value Normal

202

Abnormal








the request.















44



is invalid.


is unavailable.


4.3 Querying a Share Access Rule

Function

This interface is used to query a share access rule.



Name Mandatory

Type Description


system.


cloud scenario.



os-access_list Yes object Specifies the os-access_list object. To view

access rules, set this value to null.

Example request

{

"os-access_list": null

}






45


access_list Yes array Lists the access rules.

Description of field access_list

Name Mandatory

Type Description

access_type Yes string Specifies the type of the share access

rule.

access_to Yes string Specifies the access that the back end

grants or denies.

access_level Yes string Specifies the level of the access rule.

state Yes string Specifies the status of the access rule.

Possible values are active and error.

id Yes string Specifies the UUID of the share access

rule.

Example response

{

"access_list": [

{

"access_level": "rw",

"state": "active",

"id": "418e3cf4-08c3-4ed2-a29a-ceffa346b3b8",


"access_to": "59cd070d-9c4c-462e-9dcc-b6bb716225bc"

}

]

}

Return Value Normal

200

Abnormal











46



the request.












is invalid.


is unavailable.



API Reference 5 Quota Management



47

5 Quota Management

5.1 Querying a Quota

Function

This interface is used to query quota information.

URI GET /v2/{tenant_id}/os-quota-sets/{tenant_id}


Name Mandatory

Type Description

tenant_id Yes string Specifies the tenant ID of the operator.

tenant_id Yes string Specifies the UUID of the tenant whose

quotas are to be queried, updated, or

modified. This ID differs from the first tenant

ID (the administrative tenant ID) contained

in the URI.


None

Example request

None



quota_set Yes object Specifies the quota_set object.





48

Description of field quota_set

Name Mandatory

Type Description

gigabytes Yes integer Specifies the capacity in gigabytes allowed

for each tenant.

snapshots Yes integer Specifies the number of snapshots allowed

for each tenant.

shares Yes integer Specifies the number of shared file systems

allowed for each tenant.

snapshot_gi

gabytes

Yes integer Specifies the snapshot capacity in gigabytes

allowed for each tenant.

id Yes string Specifies the UUID of the tenant for which

you manage quotas.

share_netwo

rks

Yes integer Specifies the number of share networks for

each tenant.

Example response

{

"quota_set": {

"gigabytes": -1,

"snapshots": -1,

"snapshot_gigabytes": -1,

"shares": -1,

"id": "da0f615c35eb4d72812d1547a77b5394",

"share_networks": 10

}

}

Return Value Normal

200

Abnormal








the request.





49













is invalid.


is unavailable.



API Reference 6 Capacity Expansion or Reduction



50

6 Capacity Expansion or Reduction

6.1 Expanding the Capacity of a Shared File System

Function

This interface is used to expand the capacity of a shared file system.


successfully received. Later, you can query the status of a shared file system in the shared file system

details to identify whether the capacity expansion is complete and successful.



Name Mandatory

Type Description


system.


cloud scenario.



os-extend Yes object Specifies the os-extend object.

Description of field os-extend






51


new_size Yes integer Specifies the post-expansion capacity

of the shared file system in GB.

Example request

{

"os-extend": {

"new_size": 2

}

}


None

Example response

None

Return Value Normal

202

Abnormal



400 Bad Request Invalid input: The post-deduction capacity must

be larger than 0 and smaller than the current

capacity. (Current capacity: XX; post-deduction

capacity: XX)

400 Bad Request Invalid input: The post-expansion capacity must

be larger than the current capacity. (Current

capacity: XX; post-expansion capacity: XX)






the request.









52









is invalid.


is unavailable.


6.2 Reducing the Capacity a Shared File System

Function

This interface is used to reduce the capacity of a shared file system.



details to identify whether the capacity reduction is complete and successful.



Name Mandatory

Type Description

share_id Yes string Specifies the UUID of the shared file system.

tenant_id Yes string Specifies the tenant ID in a multi-tenant cloud

scenario.



os-shrink Yes object Specifies the os-shrink object.





53

Description of field os-shrink


new_size Yes integer Specifies the post-reduction capacity of the

shared file system in GB.

Example request

{

"os-shrink": {

"new_size": 1

}

}


None

Example response

None

Return Value Normal

202

Abnormal








the request.













54





is invalid.


is unavailable.



API Reference A Change History



55

A Change History

Release Date What's New

2017-09-23 This is the first official release.

api reference · the public cloud service provides restful apis. representational state transfer...

Documents