api reference · the public cloud provides apis complying with the design principle of restful...

Data Warehouse Service

API Reference

Issue 08

Date 2018-07-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 08 (2018-07-30) Huawei Proprietary and ConfidentialCopyright © Huawei Technologies Co., Ltd.

i

http://e.huawei.com

Contents

1 Before You Start............................................................................................................................. 1

2 API Overview................................................................................................................................. 2

3 Environment Preparation.............................................................................................................33.1 Creating a VPC...............................................................................................................................................................33.2 Obtaining Request Authentication Information............................................................................................................. 33.2.1 Token Authentication...................................................................................................................................................43.3 Obtaining a Project ID....................................................................................................................................................4

4 API Usage........................................................................................................................................64.1 REST API....................................................................................................................................................................... 64.2 Example........................................................................................................................................................................ 10

5 API Description........................................................................................................................... 165.1 Cluster Management APIs............................................................................................................................................165.1.1 Creating a Cluster...................................................................................................................................................... 165.1.2 Querying the Cluster List.......................................................................................................................................... 205.1.3 Querying Cluster Details........................................................................................................................................... 275.1.4 Querying the Supported Node Types.........................................................................................................................365.1.5 Deleting a Cluster...................................................................................................................................................... 385.2 Snapshot Management APIs.........................................................................................................................................395.2.1 Creating a Snapshot................................................................................................................................................... 405.2.2 Querying the Snapshot List....................................................................................................................................... 425.2.3 Querying Snapshot Details........................................................................................................................................ 445.2.4 Deleting a Snapshot................................................................................................................................................... 465.2.5 Restoring a Cluster.................................................................................................................................................... 47

6 Common Parameters................................................................................................................... 516.1 Error Code.................................................................................................................................................................... 516.2 Status Code................................................................................................................................................................... 57

A Exception Response................................................................................................................... 61

B Change History............................................................................................................................62

Data Warehouse ServiceAPI Reference Contents


ii

1 Before You Start

This document describes APIs, syntaxes, parameters, examples of Data Warehouse Service(DWS). You can search for information you need according to Table 1-1.

Table 1-1 Documentation guide

Phase Related Link

DWS APIs and API list API Overview

Preparations before using the APIs Environment Preparation

REST message bodies, invokingmethods, and examples

API Usage

API usage description API Description

Common parameters Common Parameters

Data Warehouse ServiceAPI Reference 1 Before You Start


1

2 API Overview

DWS provides Huawei-developed APIs. With these APIs, DWS provides the followingfunctions.

Type API Description

ClustermanagementAPIs

Creating a Cluster Creates a cluster.

Querying the Cluster List Queries and displays the cluster list.

Querying Cluster Details Queries cluster details.

Querying the SupportedNode Types

Queries the node types supported by DWS.

Deleting a Cluster Deletes a cluster.

SnapshotmanagementAPIs

Creating a Snapshot Creates snapshots for a specified cluster.

Querying the Snapshot List Queries the snapshot list.

Querying Snapshot Details Uses the snapshot ID to query the snapshotdetails.

Deleting a Snapshot Deletes a specified snapshot.

Restoring a Cluster Restores a cluster using its snapshot.

Data Warehouse ServiceAPI Reference 2 API Overview


2

3 Environment Preparation

3.1 Creating a VPC

BackgroundBefore creating a cluster, you need to create a VPC to provide a secure and isolated networkenvironment for using DWS.

If you have already created a VPC, you do not need to create it again.

NOTE

For details about how to create a VPC, see Creating a VPC in the Virtual Private Cloud User Guide.

Procedure

Step 1 Log in to the management console.

Step 2 Under Network, click Virtual Private Cloud.

Step 3 On the VPC page, click Apply for VPC to create a VPC.

Step 4 Obtain the VPC and subnet ID for subsequent use in Creating a Cluster.

Step 5 On the VPC page, click Create Security Group to create a security group.

Step 6 Obtain the security group ID for subsequent use in Creating a Cluster.

----End

3.2 Obtaining Request Authentication InformationThe token is used to call APIs and authenticate the calling request.

Data Warehouse ServiceAPI Reference 3 Environment Preparation


3

http://support.huaweicloud.com/en-us/usermanual-vpc/en-us_topic_0013748724.html

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

Invoking an API1. 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 CNNorth-Beijing1.

An example request message is as follows:

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. The X-Subject-Token value contained in thereturned message header is the token.

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

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



4

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

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 3-1 Viewing project IDs



5

4 API Usage

The public cloud provides APIs complying with the design principle of RESTful APIs.Representational State Transfer (REST) allocates Uniform Resource Identifiers (URIs) todispersed resources so that the resources can be located. Applications on clients use unifiedresource locators (URLs) to obtain the resources. The URL is in the following format: https://Endpoint/uri. uri indicates the resource path. That is, the API access path.

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

4.1 REST APIDWS provides REST APIs.

In REST, specific information or data on a network is represented by resources. REST allowsusers to access service resources, such as clusters, snapshots, and tags, by creating, querying,updating, and deleting resources.

The REST API request/response pair consists of the following:

l Request URI

l Request Header

l (Optional) Request Body

l Response Header

l (Optional) Response Body

Request URI

A request URI consists of the following:

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

Although the request URI is included in the request header, most languages or frameworksrequire that it be transmitted separately from the request message. Therefore, the request URIis listed independently.

Data Warehouse ServiceAPI Reference 4 API Usage


6

Table 4-1 Parameters in a URI

Parameter Description

URI-scheme Specifies the protocol used for transmitting the request. HTTPS isused in DWS APIs.

Endpoint Domain name or IP address of the server bearing the REST serviceendpoint. Obtain this value from Regions and Endpoints.

resource-path Specifies the resource path, that is, the API access path. Obtain thevalue from the URI of a specific API, for example, v3/auth/tokens.

Query string This parameter is optional, for example, API version or resourceselection criteria.

Request HeaderA request header contains the following:l HTTP methods, which are also called operations or actions, specify the type of

operations that you are requesting. Table 4-2 describes methods supported by DWSREST APIs.

Table 4-2 HTTP methods

Method Description

GET Requests a representation of the specified resource.

PUT Requests to update the specified resource.

POST Requests that the server accept the entity enclosed in the request as anew subordinate of the web resource identified by the URI.

DELETE Requests the server to delete a specific resource such as an object.

HEAD Requests the server resource header.

PATCH Requests to update the partial content of the specified resource.If the resource does not exist, the PATCH method may create aresource.

l (Optional) Additional fields in the request header required by a specified URI and HTTP

method. For details about common request headers, see Table 4-3. For details about therequest authentication information, see Obtaining Request AuthenticationInformation.



7

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

Table 4-3 Common request headers

Name Description Mandatory Example Value

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

No 20150907T101459Z

Authorization Indicates theauthenticationinformation.The value can beobtained from therequest signingresult.

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

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

No code.test.comorcode.test.com:443

Content-type Indicates the requestbody MIME type.

Yes application/json

Content-Length

Indicates the lengthof the request body.The unit is byte.

This parameteris mandatoryfor POST andPUT requests,but must beleft blank forGET requests.

3495



8

Name Description Mandatory Example Value

X-Project-Id Indicates the projectID. This parameteris used to obtain thetoken for the project.This parameter ismandatory for arequest from a DeCor multi-project user.

No e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token Indicates the usertoken.

Yes -

X-Language Indicates the requestlanguage.

No zh_cn

NOTE

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

(Optional) Request Body

The request body is generally sent in a structured format (for example, JSON or XML),corresponding to Content-type in the request header, and is used to transfer content other thanthe request header.

Response Header

A response header consists of the following two parts:

l An HTTP status code, from 2xx success code to 4xx or 5xx error code, or a status codethat can return the service definition, as shown in the API document.

l Additional fields in the response header required by a specified response, for example,the Content-type response header. For details about common message headers, see Table4-4.

Table 4-4 Response headers

Name Description Example Value

Date Indicates a standard HTTP header,which represents the date and timeat which the message wasoriginated. The format is defined byRFC 822.

Mon, 12 Nov 200715:55:01 GMT

Server Indicates a standard HTTP header,which includes the softwareinformation that the server uses toprocess the request.

Apache



9

Name Description Example Value

Content-Length Indicates a standard HTTP header,which specifies the size of the entitybody, in decimal number of bytes,sent to the recipient.

-

Content-Type Indicates a standard HTTP header,which specifies the media type ofthe entity body sent to the recipient.

application/json

(Optional) Response BodyThe response body is generally returned in a structured format (for example, JSON or XML),corresponding to Content-type in the response header, and is used to transfer content otherthan the response header.

Initiating a RequestYou can send a request based on the constructed request body using any of the following threemethods:

l cURLcURL is a command-line tool used to perform URL operations and transfer information.cURL acts as the HTTP client that can send HTTP requests to the HTTP server andreceive response messages. It is applicable to API debugging. For more informationabout cURL, visit https://curl.haxx.se/.

l CodeYou can invoke APIs using code to assemble, send, and process request messages.

l REST clientsBoth Mozilla Firefox and Google Chrome provide a graphical browser plug-in, that is,REST client, to send and process requests. For details about the Mozilla Firefox, seeFirefox REST Client. For details about Google Chrome, see Postman Interceptor.

4.2 ExampleThis section describes how to use DWS APIs by using APIs to manage clusters. Theprocedure of the management clusters is as follows:

1. Call the API in Token Authentication to obtain the user token, which will be put intothe request header for authentication in a subsequent request.

2. Call the API in Querying the Supported Node Types to obtain the supported nodetypes.

3. Call the API in Creating a Cluster to create a cluster.4. Call the API in Querying the Cluster List to obtain the cluster information.5. Call the API in Querying Cluster Details to view cluster details.6. Call the API in Creating a Snapshot to create a snapshot.7. Call the API in Querying Snapshot Details to check whether the snapshot is

successfully created.



10

https://curl.haxx.se/

https://addons.mozilla.org/en-US/firefox/addon/restclient/

https://chrome.google.com/webstore/detail/postman-interceptor/aicmkgpgakddgnaphhhpliifpcfhicfo?hl=en

8. Call the API in Restoring a Cluster to restore a cluster using its snapshot.9. Call the API in Deleting a Snapshot to delete an unwanted snapshot.10. Call the API in Deleting a Cluster to delete an unwanted cluster.

Prerequisitesl You have created a VPC, subnet, and security group and obtained their IDs. For details,

see Creating a VPC.l You have obtained the endpoints of IAM and DWS For details, see Regions and

Endpoints.l You have obtained the project ID. For details, see Obtaining a Project ID.

Managing a ClusterThe following values are examples (replace them based on the actual situation).

l IAM endpoint: iam_endpointl DWS endpoint: dws_endpointl VPC ID: 219ab8a0-1272-4049-a383-8ad0b770fa11l Subnet ID: d23ef2e9-8b90-49b3-bc4a-fd7d6bea6becl Security group ID: 12e3c23a-8710-4b75-95e4-5c8d7f68ef3cl Project ID: 9bc552e6-19af-4326-800d-281a92984636

Perform the following operations to manage the cluster.

Step 1 Before invoking other interfaces in Token Authentication, obtain the token and set it as anenvironment variable.curl -H "Content-Type:application/json" https://{iam_endpoint}/v3/auth/tokens -X POST -d '{ "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "testname", "domain": { "name": "testname" }, "password": "Passw0rd" } } }, "scope": { "project": { "name": "cn-north-1", } } }}' -v -k

1. Obtain the value of X-Subject-Token from the response header as follows. X-Subject-Token indicates the token.X-Subject-Token:MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...

2. Run the following command to set the token as an environment variable:export Token={X-Subject-Token}



11



X-Subject-Token is the token obtained in the preceding step.export X-Auth-Token=MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...

Step 2 Call the API in Querying the Supported Node Types to obtain the supported node types.curl -X GET -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/node_types -v -k

The request response is as follows:

STATUS CODE 200{ "node_types": [ { "spec_name": "dws.d1.xlarge", "id": "ebe532d6-665f-40e6-a4d4-3c51545b6a67", "detail": [ { "type": "vCPU", "value": "4" }, { "value": "3600", "type": "LOCAL_DISK", "unit": "GB" }, { "type": "mem", "value": "32", "unit": "GB" } ] }, { "spec_name": "dws.m1.xlarge.ultrahigh", "id": "ebe532d6-665f-40e6-a4d4-3c51545b4f71", "detail": [ { "type": "vCPU", "value": "4" }, { "value": "512", "type": "SSD", "unit": "GB" }, { "type": "mem", "value": "32", "unit": "GB" } ] } ]}

Step 3 Call the API in Creating a Cluster to create a cluster.

The examples for configuring the cluster are as follows:

l Cluster name: dws-demo

l Administrator username: dbadmin

l Administrator password: Dws2017demo!



12

l Port: 8000l Node type: dws.d1.xlargel Number of nodes: 3l EIP: auto_assigncurl -X POST -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" -d '{ "node_type": "dws.d1.xlarge", "number_of_node": 3, "subnet_id": "d23ef2e9-8b90-49b3-bc4a-fd7d6bea6bec", "security_group_id": "12e3c23a-8710-4b75-95e4-5c8d7f68ef3c", "vpc_id": "219ab8a0-1272-4049-a383-8ad0b770fa11", "port": 8000, "name": "dws-demo", "user_name": "dbadmin", "user_pwd": "Dws2017demo!", "public_ip": { "public_bind_type": "auto_assign" }}' https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/clusters -v -k

If status code 200 is returned, the request for creating a cluster is successfully sent.

Step 4 Call the API in Querying the Cluster List to obtain the cluster information.curl -X GET -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/clusters -k –v


{ "clusters": [ { "id": "7ba031f6-81f4-4670-ad20-c490b91877e5", "status": "AVAILABLE", "sub_status": "NORMAL", "task_status": null, "node_type": "dws.d1.xlarge", "subnet_id": "d23ef2e9-8b90-49b3-bc4a-fd7d6bea6bec", "security_group_id": "12e3c23a-8710-4b75-95e4-5c8d7f68ef3c", "number_of_node": 3, "availability_zone": "cn-north-1b", "port": 8000, "name": "dws-demo", "version": "1.1.0", "vpc_id": "219ab8a0-1272-4049-a383-8ad0b770fa11", "user_name": "dbadmin", "public_ip": { "public_bind_type": "auto_assign", "eip_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574" }, "updated": "2018-01-15T12:50:06", "created": "2018-01-15T12:50:06" } ]}l If status is CREATING, the cluster is being created. If status is AVAILABLE, the

cluster is successfully created.l The UUID of cluster dws-demo is 7ba031f6-81f4-4670-ad20-c490b91877e5. Record

the UUID for subsequent use.

Step 5 Call the API in Querying Cluster Details to view cluster details.curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:$Token" https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/clusters/7ba031f6-81f4-4670-ad20-c490b91877e5 -k -v



13


{ "clusters": [ { "id": "7ba031f6-81f4-4670-ad20-c490b91877e5", "status": "AVAILABLE", "sub_status": "NORMAL", "task_status": null, "node_type": "dws.d1.xlarge", "node_type_id": "5ddb1071-c5d7-40e0-a874-8a032e81a697", "subnet_id": "d23ef2e9-8b90-49b3-bc4a-fd7d6bea6bec", "security_group_id": "12e3c23a-8710-4b75-95e4-5c8d7f68ef3c", "number_of_node": 3, "availability_zone": "cn-north-1b", "port": 8000, "name": "dws-demo", "version": "1.1.0", "vpc_id": "219ab8a0-1272-4049-a383-8ad0b770fa11", "user_name": "dbadmin", "public_ip": { "public_bind_type": "auto_assign", "eip_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574" }, "updated": "2018-01-15T12:50:06", "created": "2018-01-15T12:50:06", "public_endpoints": [ { "public_connect_info": "10.0.0.8:8000", "jdbc_url": "jdbc:postgresql://10.0.0.8:8000/<YOUR_DATA_BASENAME>" } ], "endpoints": [ { "connect_info": "192.168.0.8:8000", "jdbc_url": "jdbc:postgresql://192.168.0.8:8000/<YOUR_DATA_BASENAME>" } ] } ]}

public_endpoints and endpoints can be queried from the response. After the cluster issuccessfully created, you can use public_endpoints or endpoints to access the cluster froman external source.

Step 6 Call the API in Creating a Snapshot to create a snapshot.

Create snapshot snapshotForDemoCluster for cluster dws-demo.curl -X POST -H "Content-Type:application/json" -H "X-Auth-Token:$Token" -d '{ "snapshot": { "name": "snapshotForDemoCluster", "cluster_id": "7ba031f6-81f4-4670-ad20-c490b91877e5", "description": "Snapshot description" }}' https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/snapshots -k -v


{ "snapshot": { "id": "2a4d0f86-67cd-408a-8b66-017454fb7793" }}

If status code 200 is returned, the request for creating a snapshot is successfully sent. Recordid so that the ID can be used when you query the snapshot details later.



14

Step 7 Call the API in Querying Snapshot Details to check whether the snapshot is successfullycreated.curl -X GET -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/snapshots/2a4d0f86-67cd-408a-8b66-017454fb7793 -k -v

If the snapshot status in the response is AVAILABLE, the snapshot is successfully created. Ifthe snapshot status is CREATING, the snapshot is being created.

{ "snapshot": { "id": "2a4d0f86-67cd-408a-8b66-017454fb7793", "name": "snapshotForDemoCluster", "description": "Snapshot description", "started": "2018-01-18T13:59:23Z", "finished": "2018-01-18T13:01:40Z", "size": 500, "status": "AVAILABLE", "type": "MANUAL", "cluster_id": "4f87d3c4-9e33-482f-b962-e23b30d1a18c" } }

Step 8 Call the API in Restoring a Cluster to restore a cluster using its snapshot.

Restore snapshot snapshotForDemoCluster to new cluster dws-restore.curl -X POST -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" -d '{ "restore": { "name": "dws-restore" }}' https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/snapshots/2a4d0f86-67cd-408a-8b66-017454fb7793/actions -v -k

If status code 200 is returned, the cluster is successfully restored. You can check the clusterrestoration status by performing operations in Querying Cluster Details.

Step 9 Call the API in Deleting a Snapshot to delete an unwanted snapshot.curl -X DELETE -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/snapshots/2a4d0f86-67cd-408a-8b66-017454fb7793 -v -k

If status code 202 is returned, the snapshot is successfully deleted.

Step 10 Call the API in Deleting a Cluster to delete an unwanted cluster.curl -X DELETE -H 'Content-Type:application/json;charset=utf-8' -H "X-Auth-Token:$Token" -d '{ "keep_last_manual_snapshot":0}' https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/clusters/7ba031f6-81f4-4670-ad20-c490b91877e5 -v -k

If status code 202 is returned, the cluster is successfully deleted.

----End



15

5 API Description

5.1 Cluster Management APIsA data warehouse cluster is the smallest management unit in DWS. A cluster is a datawarehouse that runs independently. You can manage the cluster life cycle in DWS.

5.1.1 Creating a Cluster

Function

This API is used to create clusters.

The cluster must run in the VPC. Before creating a cluster, you need to create a VPC andobtain the VPC and subnet IDs.

This API is an asynchronous API. It takes 10 to 15 minutes to create a cluster.

URIl URI format

POST /v1.0/{project_id}/clusters

l Parameter description

Table 5-1 URI parameter description

Parameter Mandatory Type Description

project_id Yes String Project ID. For detailsabout how to obtain theproject ID, seeObtaining a ProjectID.

Data Warehouse ServiceAPI Reference 5 API Description


16

Requestl Sample request

POST /v1.0/89cd04f168b84af6be287f71730fdb4b/clusters

{"cluster": { "node_type": "dws.m1.xlarge.ultrahigh", "number_of_node": 3, "subnet_id": "374eca02-cfc4-4de7-8ab5-dbebf7d9a720", "security_group_id": "dc3ec145-9029-4b39-b5a3-ace5a01f772b", "vpc_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574", "availability_zone": "cn-north-1b", "port": 8000, "name": "dws-1", "user_name": "dbadmin", "user_pwd": "Passw0rd!", "public_ip": { "public_bind_type": "auto_assign", "eip_id": "" } }}


Table 5-2 Request parameter description


cluster Yes Object Cluster object

node_type Yes String Node type. For details, seeQuerying the SupportedNode Types.

number_of_node Yes Integer Number of nodes in a cluster.The value ranges from 3 to32.

subnet_id Yes String Subnet ID, which is used forconfiguring cluster network.

vpc_id Yes String VPC ID, which is used forconfiguring cluster network.

security_group_id Yes String ID of a security group. TheID is used for configuringcluster network.

availability_zone No String AZ in a clusterThe following AZs aresupported:l cn-north-1bl cn-east-2a



17


name Yes String Cluster name, which must beunique. The cluster namemust contain 4 to 64characters, which consist ofletters, digits, hyphens (-), orunderscores (_) only andmust start with a letter.

user_name Yes String Administrator username forlogging in to a datawarehouse cluster. Theadministrator username must:l Consist of lowercase

letters, digits, orunderscores.

l Start with a lowercaseletter or an underscore.

l Contain 1 to 63characters.

l Cannot be a keyword ofthe DWS database. Fordetails about thekeywords of the DWSdatabase, download theData Warehouse ServiceDatabase DevelopmentGuide from theDocument Downloadpage and refer toKeyword.



18

http://support.huaweicloud.com/en-us/devg-dws/keyword.html


user_pwd Yes String Administrator password forlogging in to a datawarehouse clusterA password must conform tothe following rules:l Contains 8 to 32

characters.l Cannot be the same as the

username or the usernamewritten in reverse order.

l Contains three types ofthe following:– Lowercase letters– Uppercase letters– Digits– Special characters ~!

@#%^&*()-_=+|[{}];:,<.>/?

port No Integer Service port of a cluster(8000 to 10000). The defaultvalue is 8000.

public_ip No Object Public IP address. If thevalue is not specified, publicconnection is not used bydefault.

public_bind_type No String Binding type of an elastic IPaddress (EIP). The value canbe either of the following:l auto_assignl not_usel bind_existingThe default value is not_use.

eip_id No UUID EIP ID

Responsel Sample response

{ "cluster": { "id": "7d85f602-a948-4a30-afd4-e84f47471c15" }}




19

Table 5-3 Response parameter description



id Yes String Cluster ID

Returned Valuesl Normal

200l Abnormal

Table 5-4 Returned value description

Returned Value Description

400 Bad Request Request error.

401 Unauthorized Authentication failed.

403 Forbidden You do not have the rights to perform theoperation.

404 Not Found The requested resource was not found.

500 Internal Server Error Internal service error.

503 Service Unavailable The service is unavailable.

5.1.2 Querying the Cluster List

FunctionThis API is used to query and display the cluster list.

URIl URI format

GET /v1.0/{project_id}/clustersl Parameter description



20



project_id Yes String Project ID. Fordetails about howto obtain theproject ID, seeObtaining aProject ID.

RequestSample request

GET /v1.0/89cd04f168b84af6be287f71730fdb4b/clusters

Responsel Sample response{ "clusters": [ { "id": "7d85f602-a948-4a30-afd4-e84f47471c15", "status": "AVAILABLE", "sub_status": "READONLY", "task_status": "SNAPSHOTTING", "action_progress": {"SNAPSHOTTING": "20%"}, "node_type": "dws.m1.xlarge.ultrahigh", "subnet_id": "374eca02-cfc4-4de7-8ab5-dbebf7d9a720", "security_group_id": "dc3ec145-9029-4b39-b5a3-ace5a01f772b", "number_of_node": 3, "availability_zone": "cn-north-1b", "port": 8000, "name": "dws-1", "version": "1.2.0", "vpc_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574", "user_name": "dbadmin", "public_ip": { "public_bind_type": "auto_assign", "eip_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574" }, "public_endpoints": [ { "public_connect_info": "10.0.0.8:8000", "jdbc_url": "jdbc:postgresql://10.0.0.8:8000/<YOUR_DATABASE_NAME>" } ], "endpoints": [ { "connect_info": "192.168.0.8:8000", "jdbc_url": "jdbc:postgresql://192.168.0.8:8000/<YOUR_DATABASE_NAME>" }, { "connect_info": "192.168.0.10:8000", "jdbc_url": "jdbc:postgresql://192.168.0.10:8000/<YOUR_DATABASE_NAME>" } ], "updated": "2016-02-10T14:28:14Z", "created": "2016-02-10T14:26:14Z", "recent_event": 6



21

} ]}l Parameter description



clusters Yes Array List of cluster objects


status Yes String Cluster status, which can beone of the following:l CREATINGl AVAILABLEl UNAVAILABLEl CREATION FAILEDl FROZEN



22


task_status Yes String Cluster management task. Thevalue can be one of thefollowing:l UNFREEZINGl FREEZINGl RESTORINGl SNAPSHOTTINGl GROWINGl REBOOTINGl SETTING_CONFIGUR

ATIONl CONFIGURING_EXT_

DATASOURCEl DELETING_EXT_DAT

ASOURCEl REBOOT_FAILUREl RESIZE_FAILURE

action_progress Yes Map The key indicates the ongoingtask, and the value indicatesthe progress of the ongoingtask.Valid key values include:l GROWINGl RESTORINGl SNAPSHOTTINGl REPAIRINGl GREATING

node_type Yes UUID Node type

subnet_id Yes UUID Subnet ID

security_group_id Yes UUID ID of a security group

number_of_node Yes Integer Number of nodes

availability_zone Yes String Availability zone (AZ)

port Yes Integer Service port of a cluster (8000to 10000). The default valueis 8000.

name Yes String Cluster name

version Yes String Data warehouse version

vpc_id Yes UUID VPC ID



24


user_name Yes String Username of the administrator

public_ip Yes Object. Fordetails, seeTable 5-7.

Public IP address. If the valueis not specified, publicconnection is not used bydefault.

public_endpoints Yes Array. Fordetails, seeTable 5-8.

Public network connectioninformation about the cluster.If the value is not specified,the public network connectioninformation is not used bydefault.

endpoints Yes Array. Fordetails, seeTable 5-9.

Private network connectioninformation about the cluster

updated Yes Time Last modification time of acluster. The format isISO8601:YYYY-MM-DDThh:mm:ssZ.

created Yes Time Cluster creation time. Theformat is ISO8601:YYYY-MM-DDThh:mm:ssZ.

failed_reasons No Object. Fordetails, seeTable 5-10.

Cause of failure.

recent_event Yes Integer Number of events

Table 5-7 public_ip field data structure description


public_bind_type Yes String Binding type of an EIP. Thevalue can be either of thefollowing:l auto_assignl not_usel bind_existing


status No String EIP binding status. An optionalvalue is FAIL (binding fails).

error_message No String Cause of an EIP binding failure



25

Table 5-8 public_endpoints field data structure description

Parameter Mandatory

Type Description

public_connect_info

No String Public network connectioninformation

jdbc_url No String JDBC URL on the publicnetwork. The following is thedefault format:jdbc:postgresql://<public_connect_info>/<YOUR_DATABASE_NAME>

Table 5-9 endpoints field data structure description

Parameter Mandatory

Type Description

connect_info Yes String Private network connectioninformation

jdbc_url Yes String JDBC URL on the private network.The following is the default format:jdbc:postgresql://< connect_info>/<YOUR_DATABASE_NAME>

Table 5-10 failed_reasons field data structure description

Parameter Mandatory

Type Description

error_code No String Error code. Possible values can be:l DWS.6000: indicates that

cluster creation fails.l DWS.6001: indicates that

cluster scale-out fails.l DWS.6002: indicates that

cluster restart fails.l DWS.6003: indicates that

cluster restoration fails.

error_msg No String Error message




26

200l Abnormal



400 Bad Request Request error. For details about the returnederror code, see Exception Response.






5.1.3 Querying Cluster Details

Function

This API is used to query cluster details.

URIl URI format

GET /v1.0/{project_id}/clusters/{cluster_id}l Parameter description




cluster_id Yes String Cluster ID

Request

Sample request

GET /v1.0/89cd04f168b84af6be287f71730fdb4b/clusters/b5c45780-1006-49e3-b2d5-b3229975bbc7



27

Responsel Sample response{ "cluster": { "id": "7d85f602-a948-4a30-afd4-e84f47471c15", "status": "AVAILABLE", "name": "dws-1", "updated": "2018-02-10T14:28:14Z", "created": "2018-02-10T14:28:14Z", "user_name": "dbadmin", "sub_status": "READONLY", "task_status": "SNAPSHOTTING", "action_progress": {"SNAPSHOTTING": "20%"}, "node_type": "dws.m1.xlarge.ultrahigh", "node_type_id": "5ddb1071-c5d7-40e0-a874-8a032e81a697", "subnet_id": "374eca02-cfc4-4de7-8ab5-dbebf7d9a720", "security_group_id": "dc3ec145-9029-4b39-b5a3-ace5a01f772b", "number_of_node": 3, "availability_zone": "cn-north-1b", "port": 8000, "vpc_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574", "public_ip": { "public_bind_type": "auto_assign", "eip_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574" }, "public_endpoints": [ { "public_connect_info": "10.0.0.8:8000", "jdbc_url": "jdbc:postgresql://10.0.0.8:8000/<YOUR_DATABASE_NAME>" } ], "endpoints": [ { "connect_info": "192.168.0.8:8000", "jdbc_url": "jdbc:postgresql://192.168.0.8:8000/<YOUR_DATABASE_NAME>" }, { "connect_info": "192.168.0.10:8000", "jdbc_url": "jdbc:postgresql://192.168.0.10:8000/<YOUR_DATABASE_NAME>" } ], "version": "1.2.0", "maintain_window": { "day": "Wed", "start_time": "22:00", "end_time": "02:00" }, "resize_info" : { "target_node_num": "6", "origin_node_num": "3", "status": "GROWING", "start_time": "2018-02-14T14:28:14Z" }, "recent_event": 6, "tags":[ { "key": "key1", "value": "value1" }, { "key": "key2", "value": "value2" } ], "parameter_group": { "id": "157e9cc4-64a8-11e8-adc0-fa7ae01bbebc",



28

"name": "Default-Parameter-Group-DWS", "status": "In-Sync" } }}l Parameter description





status Yes String Cluster status, which can beone of the following:l CREATINGl AVAILABLEl UNAVAILABLEl CREATION FAILEDl FROZEN

name Yes String Cluster name

updated Yes Time Last modification time of acluster. The format isISO8601:YYYY-MM-DDThh:mm:ssZ.

created Yes Time Cluster creation time. Theformat is ISO8601:YYYY-MM-DDThh:mm:ssZ.

user_name Yes String Administrator username



29


task_status Yes String Cluster management task.The value can be one of thefollowing:l UNFREEZINGl FREEZINGl RESTORINGl SNAPSHOTTINGl GROWINGl REBOOTINGl SETTING_CONFIGU

RATIONl CONFIGURING_EXT

_DATASOURCEl DELETING_EXT_DA

TASOURCEl REBOOT_FAILUREl RESIZE_FAILURE

action_progress Yes Map The key indicates anongoing task. The value canbe one of the following:l GROWINGl RESTORINGl SNAPSHOTTINGl REPAIRINGl GREATING

The key value indicatesthe progress of theongoing task.

node_type Yes UUID Node type

node_type_id Yes UUID ID of a node type

subnet_id Yes UUID Subnet ID

security_group_id Yes UUID ID of a security group

number_of_node Yes Integer Number of nodes

availability_zone Yes String AZ

port Yes Integer Service port of a cluster(8000 to 10000). Thedefault value is 8000.

vpc_id Yes UUID VPC ID



31


public_ip Yes Object.For details,see Table5-14.

Public IP address. If thevalue is not specified, publicconnection is not used bydefault.

public_endpoints Yes Array. Fordetails, seeTable5-15.

Public network connectioninformation about thecluster. If the value is notspecified, the publicnetwork connectioninformation is not used bydefault.

endpoints Yes Array. Fordetails, seeTable5-16.

View the private networkconnection informationabout the cluster.

version Yes String Data warehouse version

maintain_window Yes Object.For details,see Table5-17.

Cluster maintenance timewindow

resize_info No Object.For details,see Table5-18.

Cluster scale-out statusdetails

failed_reasons No Object.For details,see Table5-19.

Cause of failure. If the valueis empty, the cluster is in thenormal state.

recent_event Yes Integer Number of events

tags Yes Array. Fordetails, seeTable5-20.

Tags in a cluster

parameter_group No Object.For details,see Table5-21.

Information about theparameter group associatedwith the cluster



32

Table 5-14 public_ip field data structure description

Parameter Mandatory

Type Description

public_bind_type Yes String Binding type of an EIP. The valuecan be either of the following:l auto_assignl not_usel bind_existing


status No String Binding status of an EIP. Theparameter value is as follows:l FAIL

error_message No String Cause of an EIP binding failure

Table 5-15 public_endpoints field data structure description

Parameter Mandatory

Type Description

public_connect_info No String Public network connectioninformation

jdbc_url No String JDBC URL on the public network.The following is the defaultformat:jdbc:postgresql://<public_connect_info>/<YOUR_DATABASE_NAME>

Table 5-16 endpoints field data structure description

Parameter Mandatory

Type Description

connect_info Yes String Private network connectioninformation

jdbc_url Yes String JDBC URL on the privatenetwork. The following is thedefault format:jdbc:postgresql://<connect_info>/<YOUR_DATABASE_NAME>



33

Table 5-17 maintain_window field data structure description


day No String Maintenance time ineach week in the unitof day. The value canbe one of thefollowing:l Monl Tuel Wedl Thul Fril Satl Sun

start_time No String Maintenance starttime. The format isHH:mm. The timezone is GMT+0.

end_time No String Maintenance end time.The format isHH:mm. The timezone is GMT+0.

Table 5-18 resize_info field data structure description


target_node_num No Int Number of nodes afterthe scale-out

origin_node_num No Int Number of nodesbefore the scale-out

status No String Scale-out status. Thevalue can be either ofthe following:l GROWINGl RESIZE_FAILUR

E

start_time No String Scale-out start time.The format isISO8601:YYYY-MM-DDThh:mm:ss.



34

Table 5-19 failed_reasons field data structure description


error_code No String Error code. Possiblevalues can be:l DWS.6000: indicates

that cluster creationfails.

l DWS.6001: indicatesthat cluster scale-outfails.

l DWS.6002: indicatesthat cluster restartfails.

l DWS.6003: indicatesthat clusterrestoration fails.

error_msg No String Error message

Table 5-20 tags field data structure description


key No String Tag key

value No String Tag value

Table 5-21 parameter_group field data structure description

Parameter Mandatory

Type Description

id Yes String Parameter group ID

name Yes String Parameter group name

status Yes String Cluster parameter status. Possiblevalues are:l In-Sync: synchronizedl Applying: in applicationl Pending-Reboot: restart for the

modification to take effectl Sync-Failure: application failure



35


200l Abnormal









5.1.4 Querying the Supported Node Types

FunctionThis API is used to query the node types supported by DWS.

URIl URI format

GET /v1.0/{project_id}/node_types


Parameter Mandatory

Type Description

project_id Yes String Project ID. For details abouthow to obtain the project ID,see Obtaining a Project ID.


GET /v1.0/89cd04f168b84af6be287f71730fdb4b/node_types


STATUS CODE 200{



36

"node_types": [ { "spec_name": "dws.d1.xlarge", "id": "ebe532d6-665f-40e6-a4d4-3c51545b6a67", "detail": [ { "type": "vCPU", "value": "4" }, { "value": "3600", "type": "LOCAL_DISK", "unit": "GB" }, { "type": "mem", "value": "32", "unit": "GB" } ] }, { "spec_name": "dws.m1.xlarge.ultrahigh", "id": "ebe532d6-665f-40e6-a4d4-3c51545b4f71", "detail": [ { "type": "vCPU", "value": "4" }, { "value": "512", "type": "SSD", "unit": "GB" }, { "type": "mem", "value": "32", "unit": "GB" } ] } ]}




node_types Yes Array List of node types

spec_name Yes String Name of a node type

id Yes String ID of a node type

detail Yes Object Node type details

value Yes String Attribute value

unit No String Attribute unit

type Yes String Attribute type



37


200

l Abnormal









5.1.5 Deleting a Cluster

Function

This API is used to delete clusters. All resources, including customer data, of the deletedcluster will be released. For data security reasons, create a snapshot for the cluster that youwant to delete before deleting the cluster.

URIl URI format

DELETE /v1.0/{project_id}/clusters/{cluster_id}




project_id Yes String Project ID. For detailsabout how to obtain theproject ID, seeObtaining a Project ID.

cluster_id Yes String ID of the cluster to bedeleted



38

Requestl Sample requestDELETE /v1.0/89cd04f168b84af6be287f71730fdb4b/clusters/4ca46bf1-5c61-48ff-b4f3-0ad4e5e3ba90{ "keep_last_manual_snapshot":0}




keep_last_manual_snapshot

Yes Integer Number of snapshotsthat you want to reservefor a cluster

Response

Sample response

STATUS CODE 202


202l Abnormal









5.2 Snapshot Management APIsA DWS snapshot is a complete backup of a cluster. Snapshots are stored in the storage spaceof Object Storage Service (OBS). A snapshot can be used to restore a cluster to a newlycreated one that has the same flavor. Currently, you can only restore a cluster to a new one.



39

5.2.1 Creating a Snapshot

Function

This API is used to create snapshots for a specified cluster.

URIl URI format

POST /v1.0/{project_id}/snapshotsl Parameter description




Requestl Sample requestPOST /v1.0/89cd04f168b84af6be287f71730fdb4b/snapshots{ "snapshot": { "name": "snapshot-3", "cluster_id": "44b277eb-39be-4921-be31-3d61b43651d7", "description": "Snapshot-3 description" }}




snapshot Yes Object Snapshot object

cluster_id Yes String ID of the cluster for whichyou want to create asnapshot

name Yes String Snapshot name, which mustbe unique and start with aletter. It consists of 4 to 64characters, which are case-insensitive and containletters, digits, hyphens (-),and underscores (_) only.



40


description No String Snapshot description. If novalue is specified, thedescription is empty.


STATUS CODE 200{ "snapshot": { "id": "2a4d0f86-67cd-408a-8b66-017454fb7793" }}





id Yes String Snapshot ID


200l Abnormal











41

5.2.2 Querying the Snapshot List

Function

This API is used to query the snapshot list.

URIl URI formatGET /v1.0/{project_id}/snapshotsl Parameter description




Request

Sample request

GET /v1.0/89cd04f168b84af6be287f71730fdb4b/snapshots


STATUS CODE 200{ "snapshots": [ { "id": "2a4d0f86-67cd-408a-8b66-017454fb7793", "name": "snapshot-1", "description": "", "started": "2016-08-23T03:59:23Z", "finished": "2016-08-23T04:01:40Z", "size": 500, "status": "AVAILABLE", "type": "MANUAL", "cluster_id": "4f87d3c4-9e33-482f-b962-e23b30d1a18c" }, { "id": "4af11460-06ec-48a4-b3ad-0e3bbdcd8ab1", "name": "snapshot-2", "description": "", "started": "2016-08-23T18:20:00Z", "finished": "2016-08-23T18:22:12Z", "size": 500, "status": "AVAILABLE", "type": "MANUAL", "cluster_id": "4f87d3c4-9e33-482f-b962-e23b30d1a18c" } ]}



42




snapshots Yes Array List of snapshot objects

name Yes String Snapshot name

id Yes String Snapshot ID

description Yes String Snapshot description

started Yes String Time when a snapshot is beingcreated. The format is ISO8601:YYYY-MM-DDThh:mm:ssZ.

finished Yes String Time when a snapshot has beencreated. The format is ISO8601:YYYY-MM-DDThh:mm:ssZ.

size Yes Double Snapshot size, expressed in GB.

status Yes String Snapshot status, which can be oneof the following:l CREATINGl AVAILABLEl UNAVAILABLE

type Yes String Snapshot creation type. Currently,only MANUAL is supported.

cluster_id Yes String ID of the cluster for which asnapshot is created


200

l Abnormal





403 Forbidden You do not have the rights to perform the operation.




43




5.2.3 Querying Snapshot Details

Function

This API is used to query snapshot details by using the snapshot ID.

URIl URI format

GET /v1.0/{project_id}/snapshots/{snapshot_id}l Parameter description




snapshot_id Yes String Snapshot ID

Request

Sample request

GET /v1.0/89cd04f168b84af6be287f71730fdb4b/snapshots/b5c45780-1006-49e3-b2d5-b3229975bbc7


STATUS CODE 200{ "snapshot": { "id": "2a4d0f86-67cd-408a-8b66-017454fb7793", "name": "snapshot-1", "description": "snapshot description", "started": "2016-08-23T03:59:23Z", "finished": "2016-08-23T04:01:40Z", "size": 500, "status": "AVAILABLE", "type": "MANUAL", "cluster_id": "4f87d3c4-9e33-482f-b962-e23b30d1a18c" }}



44





name Yes String Snapshot name

Id Yes String Snapshot ID

description Yes String Snapshot description

started Yes String Time when a snapshot is beingcreated. The format is ISO8601:YYYY-MM-DDThh:mm:ssZ.

finished Yes String Time when a snapshot has beencreated. The format is ISO8601:YYYY-MM-DDThh:mm:ssZ.

size Yes Double Snapshot size, expressed in GB.

status Yes String Snapshot status, which can be oneof the following:l CREATINGl AVAILABLEl UNAVAILABLE

type Yes String Snapshot creation type. Currently,only MANUAL is supported.

cluster_id Yes String ID of the cluster for which asnapshot is created


200l Abnormal









45




5.2.4 Deleting a Snapshot

Function

This API is used to delete a specified snapshot.

URIl URI format

DELETE /v1.0/{project_id}/snapshots/{snapshot_id}




project _id Yes String Project ID. For detailsabout how to obtain theproject ID, seeObtaining a ProjectID.


Request

Sample request

DELETE /v1.0/89cd04f168b84af6be287f71730fdb4b/snapshots/4ca46bf1-5c61-48ff-b4f3-0ad4e5e3ba90

Response

Sample response

STATUS CODE 202


202

l Abnormal



46









5.2.5 Restoring a Cluster

FunctionThis API is used to restore clusters using the snapshot.

URIl URI format

POST /v1.0/{project_id}/snapshots/{snapshot_id}/actionsl Parameter description






POST /v1.0/89cd04f168b84af6be287f71730fdb4b/snapshots/4ca46bf1-5c61-48ff-b4f3-0ad4e5e3ba90/actions{"restore": { "name": "dws-1", "subnet_id": "374eca02-cfc4-4de7-8ab5-dbebf7d9a720", "security_group_id": "dc3ec145-9029-4b39-b5a3-ace5a01f772b", "vpc_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574", "availability_zone": "cn-north-1b", "port": 8000, "public_ip": { "public_bind_type": "auto_assign",



47

"eip_id": "" } }}




restore Yes Object Object to be restored

name Yes String Cluster name, which must beunique. The cluster namemust contain 4 to 64characters, which consist ofletters, digits, hyphens (-), orunderscores (_) only andmust start with a letter.

subnet_id No String Subnet ID, which is used forconfiguring cluster network.The default value is the sameas that of the original cluster.

vpc_id No String VPC ID, which is used forconfiguring cluster network.The default value is the sameas that of the original cluster.

security_group_id No String ID of a security group. TheID is used for configuringcluster network. The defaultvalue is the same as that ofthe original cluster.

availability_zone No String AZ in a cluster The defaultvalue is the same as that ofthe original cluster.

port No Integer Service port of a cluster(8000 to 10000). The defaultvalue is 8000.

public_ip No Object Public IP address. If thevalue is not specified, publicconnection is not used bydefault.



48


public_bind_type No String Binding type of an EIP. Thevalue can be either of thefollowing:l auto_assignl not_usel bind_existingThe default value is not_use.

eip_id No UUID EIP ID The default value isthe same as that of theoriginal cluster.


{ "cluster": { "id": "7d85f602-a948-4a30-afd4-e84f47471c15" }}







200

l Abnormal









49






50

6 Common Parameters

6.1 Error CodeNo data is returned if an API fails to be called. You can locate the cause of error according tothe error code of each API. When the calling fails, HTTP status code 4xx or 5xx is returned.The returned message body contains the specific error code and error information. If you failto locate the cause of error, contact the customer service personnel and technical support andprovide the error code so that we can help you solve the problem as soon as possible.

Table 6-1 Error code

ErrorCode

StatusCode

Description Solution

DWS.0001 400 Incorrect parameter! Enter the correct parameteraccording to the correspondingparameter description and retry.

DWS.0005 500 Server failure. Contact the customer servicepersonnel or retry later.

DWS.0006 400 The request is empty. Enter arequest parameter.

Enter the request parameter andretry.

DWS.0011 409 This operation cannot beperformed because anotheroperation is being performed onthe instance or the instance isfaulty. Please try again later.

Contact the customer servicepersonnel or retry later.

DWS.0015 403 Resource not found or permissiondenied.

Verify the access resources andthe access rights and retry.

DWS.0020 403 Restricted account. Contact the customer servicepersonnel.

Data Warehouse ServiceAPI Reference 6 Common Parameters


51

ErrorCode

StatusCode


DWS.0021 403 Frozen account. Contact the customer servicepersonnel.

DWS.0022 404 The instance does not exist or hasbeen deleted.

Enter a correct instance andretry.

DWS.0030 400 The number of snapshots reachesthe quota!

Contact the customer servicepersonnel.

DWS.0031 400 The object already exists! Enter a correct object and retry.

DWS.0032 403 You are not authorized to performthe operation. Check the accountpermission on the IAM.

Check the account permissionthrough the IAM.

DWS.1102 400 The instance name already exists! Enter a correct instance andretry.

DWS.1112 400 The number of instances reachesthe quota.


DWS.2026 400 This is a weak password. Enter astrong password!

Enter a valid passwordaccording to the passworddescription.

DWS.2067 400 The input parameter is illegal! Enter the correct parameteraccording to the correspondingparameter description and retry.

DWS.3026 400 The backup file does not exist. Ensure that the backup file iscorrect and retry.

DWS.3027 400 The cluster does not exist. Ensure that the cluster is correctand retry.

DWS.3029 400 The backup file of a specific timepoint does not exist.

Ensure that the backup file iscorrect and retry.

DWS.3030 400 The volume size of the newinstance should not be less thanthat of the original one.

Rectify the fault according tothe prompted error message andretry.

DWS.5001 400 Invalid instance name. Enter a valid instance nameaccording to the instance namedescription and retry.

DWS.5002 400 Invalid database type. Enter a valid database typeaccording to the databaseparameter description and retry.



52

ErrorCode

StatusCode


DWS.5003 400 Invalid database version. Enter a valid database versionaccording to the databaseparameter description and retry.

DWS.5004 400 Empty datastore field. Enter the correct datastoreaccording to the actual situationand retry.

DWS.5005 400 Database type or version notsupported.

Enter the valid database typeand version according to thedatabase parameter descriptionand retry.

DWS.5006 400 Invalid flavor. Select the correct flavor andretry.

DWS.5007 400 The selected flavor does not exist. Select the correct flavor andretry.

DWS.5013 400 Invalid password of database root. Enter a valid passwordaccording to the passworddescription.

DWS.5014 400 Invalid VPC ID. Enter a valid ID according tothe description of parametervpc_id.

DWS.5015 400 Invalid subnet ID. Enter a valid ID according tothe description of parametersubnet_id.

DWS.5017 400 Invalid retention period ofautomatic backup.

Enter a proper retention periodof automatic backup and retry.

DWS.5018 400 Invalid automatic backup period. Enter a proper automaticbackup period and retry.

DWS.5020 400 The time when automatic backupstarts is invalid.

Enter a proper automaticbackup start time and retry.

DWS.5021 400 The VPC does not exist or doesnot belong to the user.

Enter a correct VPC and retry.

DWS.5022 400 The subnet does not exist or doesnot belong to the VPC.

Enter a correct subnet and retry.

DWS.5023 400 The security group does not existor does not belong to the VPC.

Enter a correct security groupand retry.

DWS.5026 400 Ha available zone is illegal! Enter a correct available zoneand retry.



53

ErrorCode

StatusCode


DWS.5027 400 Ha invalid available zone! Enter a correct available zoneand retry.

DWS.5045 400 Current tenant is not allowed! Contact the customer servicepersonnel.

DWS.5048 400 Invalid extended parameter. Enter a valid extendedparameter according to thecorresponding description ofthe extended parameter.

DWS.5049 400 Invalid cluster name. Enter a valid cluster nameaccording to the cluster namedescription.

DWS.5050 409 Cluster name already exists. Enter the correct cluster nameand retry.

DWS.5052 400 Invalid value of the AZ. Enter a correct AZ and retry.

DWS.5053 400 The value of locality betweeninstances is invalid.

Enter a correct locality valueand retry.

DWS.5054 400 Paragroup id is invalid. Enter a correct paragroup IDand retry.

DWS.5055 400 The flavor ID is invalid. Enter a correct flavor ref ID andretry.

DWS.5057 400 Cluster name pattern is invalid. Enter a valid cluster nameaccording to the cluster namedescription.

DWS.5059 400 Database username containsinvalid characters.

Enter a valid database usernameaccording to the databaseusername description.

DWS.5060 400 Integer field is of wrong range. Enter a valid Integer type andretry.

DWS.5061 400 Volume type is illegal. Enter a valid volume type andretry.

DWS.5062 400 Volume tag is illegal. Enter a valid Volume tag andretry.

DWS.5063 400 Invalid Specific field. Enter a correct Specific valueand retry.

DWS.5068 400 Invalid disk parameters. Enter correct disk parametersand retry.



54

ErrorCode

StatusCode


DWS.5070 400 Flavor ref is invalid in xml. Enter correct flavor ref andretry.

DWS.5071 400 Volume type is invalid in xml. Enter a correct disk type andretry.

DWS.5072 400 The security group ID is invalid. Enter a valid security group IDand retry.

DWS.5074 400 The subnet does not belong to theVPC.

Enter a correct subnet and retry.

DWS.5079 400 The backup period is notpermitted.

Enter a proper backup periodand retry.

DWS.5080 400 The backup retention period is notpermitted.

Enter a proper backup retentionduration and retry.

DWS.5082 400 Database user is not supported. Enter a valid database usernameaccording to the databaseusername description.

DWS.5083 400 Locality is not permitted in xml. Contact the customer servicepersonnel.

DWS.5084 400 Incorrect Volume configuration inthe XML file.

Enter a correct Volume valueand retry.

DWS.5085 400 Locality is not globally consistent. Contact the customer servicepersonnel.

DWS.5086 400 The same instance type does notmeet flavor consistencyrequirements.

Enter the correct flavor andretry.

DWS.5087 400 The same instance type does notmeet disk consistencyrequirements.

Enter a correct disk and retry.

DWS.5093 400 Flavor info is invalid. Enter valid flavor info and retry.

DWS.5096 400 Invalid disk quantity. Enter valid disk quantity andretry.

DWS.5097 400 HA Region or Available Zonedoes not exist.

Enter a correct HA Region andAvailable Zone and retry.

DWS.5098 400 Invalid EIP binding type. Enter a correct EIP binding typeand retry.

DWS.5100 400 Configuration file cannot beparsed.




55

ErrorCode

StatusCode


DWS.5106 400 Invalid instance type! Enter a valid instance type andretry.

DWS.5107 400 Invalid cluster mode! Enter a valid disk mode andretry.

DWS.5110 400 Parameter groups of instances areinconsistent!

Enter a correct parameter groupand retry.

DWS.5111 400 The backup file ID does not exist! Enter a correct backup file IDand retry.

DWS.5144 400 Invalid password of the clusteradministrator.

Enter a valid clusteradministrator passwordaccording to the description ofthe cluster administrator'spassword.

DWS.5145 400 The administrator password cannotcontain the username or thereverse username.

Enter a valid administratorpassword as prompted and retry.

DWS.5149 400 Invalid snapshot ID. Enter a valid snapshot IDaccording to the snapshot IDdescription.

DWS.6000 400 Cluster creation fails. Check the account's remainingquota. If it is greater than theresources applied by the user,contact customer servicepersonnel.

DWS.6001 400 Cluster scale-out fails. Check the account's remainingquota of nodes. If it is greaterthan the number of nodes to beadded, contact the customerservice personnel.

DWS.6002 400 Cluster restart fails. Contact the customer servicepersonnel or retry later.

DWS.6003 400 Cluster restoration fails. Check the account's remainingquota. If it is greater than theapplied quota, contact thecustomer service personnel.

DWS.9999 500 Request processing failed. Contact the customer servicepersonnel or retry later.



56

6.2 Status CodeTable 6-2 describes the status code.

Table 6-2 Status code

StatusCode

Code Description

100 Continue The client continues sending the request.This interim response is used to inform the client thatthe initial part of the request has been received andhas not yet been rejected by the server.

101 Switching Protocols Switching protocols. The target protocol must bemore advanced than the source protocol.For example, the current HTTP protocol is switchedto a later version.

201 Created The request for creating a resource has been fulfilled.

202 Accepted The request has been accepted, but the processing hasnot been completed.

203 Non-AuthoritativeInformation

The server successfully processed the request, but isreturning information that may be from anothersource.

204 NoContent The server has successfully processed the request, buthas not returned any content.The status code is returned in response to an HTTPOPTIONS request.

205 Reset Content The server has fulfilled the request, but the requesteris required to reset the content.

206 Partial Content The server has processed certain GET requests.

300 Multiple Choices There are multiple options for the location of therequested resource. The response contains a list ofresource characteristics and addresses from which theuser or user agent (such as a browser) can choose themost appropriate one.

301 Moved Permanently The requested resource has been assigned a newpermanent URI, and the new URI is contained in theresponse.

302 Found The requested resource resides temporarily under adifferent URI.



57

StatusCode

Code Description

303 See Other Retrieve a location.The response to the request can be found under adifferent URI and should be retrieved using a GET orPOST method.

304 Not Modified The requested resource has not been modified. Whenthe server returns this status code, it does not returnany resources.

305 Use Proxy The requested resource must be accessed through aproxy.

306 Unused The HTTP status code is no longer used.

400 BadRequest Invalid request.The client should not repeat the request withoutmodifications.

401 Unauthorized The status code is returned after the client providesthe authentication information, indicating that theauthentication information is incorrect or invalid.

402 Payment Required This status code is reserved for future use.

403 Forbidden The server understood the request, but is refusing tofulfill it.The client should not repeat the request withoutmodifications.

404 NotFound The requested resource cannot be found.The client should not repeat the request withoutmodifications.

405 MethodNotAllowed The method specified in the request is not supportedfor the requested resource.The client should not repeat the request withoutmodifications.

406 Not Acceptable The server cannot fulfill the request according to thecontent characteristics of the request.

407 Proxy AuthenticationRequired

This status code is similar to 401, but indicates thatthe client must first authenticate itself with the proxy.

408 Request Time-out The request timed out.The client may repeat the request withoutmodifications at any later time.



58

StatusCode

Code Description

409 Conflict The request could not be completed due to a conflictwith the current state of the resource.This status code indicates that the resource that theclient attempts to create already exits, or the requestfails to be processed because of the update of theconflict request.

410 Gone The requested resource is no longer available.The status code indicates that the requested resourcehas been deleted permanently.

411 Length Required The server refuses to process the request without adefined Content-Length.

412 Precondition Failed The server does not meet one of the preconditionsthat the requester puts on the request.

413 Request Entity TooLarge

The request is larger than that a server is able toprocess. The server may close the connection toprevent the client from continuing the request. If theserver cannot process the request temporarily, theresponse will contain a Retry-After header field.

414 Request-URI TooLarge

The URI provided was too long for the server toprocess.

415 Unsupported MediaType

The server is unable to process the media format inthe request.

416 Requested range notsatisfiable

The requested range is invalid.

417 Expectation Failed The server fails to meet the requirements of theExpect request-header field.

422 UnprocessableEntity The request is well-formed but is unable to beprocessed due to semantic errors.

429 TooManyRequests The client has sent more requests than its rate limit isallowed within a given amount of time, or the serverhas received more requests than it is able to processwithin a given amount of time. In this case, it isadvisable for the client to re-initiate requests after thetime specified in the Retry-After header of theresponse expires.

500 InternalServerError The server is able to receive the request but it couldnot understand the request.

501 Not Implemented The server does not support the requested function.

502 Bad Gateway The server is acting as a gateway or proxy andreceives an invalid request from a remote server.



59

StatusCode

Code Description

503 ServiceUnavailable The requested service is invalid.The client should not repeat the request withoutmodifications.

504 ServerTimeout The request cannot be fulfilled within a given time.This status code is returned to the client only whenthe Timeout parameter is specified in the request.

505 HTTP Version notsupported

The server does not support the HTTP protocolversion used in the request.



60

A Exception Response

DWS APIs provide unified exception response, involving error code and exception details ofspecific messages.


STATUS CODE 500{ "errCode": "DWS.0001", "externalMessage": " Incorrect parameter!"}


Table A-1 Response parameter description

Parameter Mandatory Description

errCode Yes Error code

externalMessage Yes Error message

Data Warehouse ServiceAPI Reference A Exception Response


61

B Change History

Date Description

2018-07-30 This is the eighth official release.Modified the following section:l Querying Cluster Details: Added parameters of the

parameter group associated with a cluster.

2018-05-15 This issue is the seventh official release.Modified the following sections:l Querying the Cluster List: Added some request

parameters.l Querying Cluster Details: Added some request

parameters.

2018-03-31 This is the sixth official release.Modified the following sections:Error Code

2018-03-02 This is the fifth official release.Added the following section:Restoring a Cluster

Data Warehouse ServiceAPI Reference B Change History


62

Date Description

2018-02-02 This is the fourth official release.Added the following sections:l Before You Startl API Overviewl Creating a VPCl REST APIl Examplel Status CodeModified the following section:Error Code: Added solutions for the error code.Deleted the following content:AK/SK Authentication

2017-12-15 This is the third official release.Deleted the API used for restoring clusters using thesnapshot.Modified the following sections:l Cluster Management APIsl Snapshot Management APIsl Exception Response

2017-11-30 This is the second official release.Modified the following sections:l Common Request Headersl Querying the Cluster Listl Querying Cluster Detailsl Querying the Supported Node Typesl Error Code

2017-08-25 This is the first official release.

Data Warehouse ServiceAPI Reference B Change History


63

api reference · the public cloud provides apis complying with the design principle of restful...

Documents