# 快速入门
本节通过调用一系列API，以集群管理为例，介绍使用DWS API的基本流程。集群管理的流程如下：
1. 调用[认证鉴权](https://support.huaweicloud.com/api-dws/dws_02_0064.html)获取用户的Token，因为在后续的请求中需要将Token放到请求消息头中作为认证。
2. 调用[查询规格信息](https://support.huaweicloud.com/api-dws/ListNodeTypes.html)接口获取支持的节点类型。
3. 调用[创建集群](https://support.huaweicloud.com/api-dws/CreateCluster.html)接口创建集群。
4. 调用[查询集群列表](https://support.huaweicloud.com/api-dws/ListClusters.html)接口获取集群信息。
5. 调用[查询集群详情](https://support.huaweicloud.com/api-dws/ListClusterDetails.html)接口查看集群详细内容。
6. 调用[创建快照](https://support.huaweicloud.com/api-dws/CreateSnapshot.html)接口创建快照。
7. 调用[查询快照列表](https://support.huaweicloud.com/api-dws/ListSnapshots.html)接口查看快照是否创建成功。
8. 调用[恢复集群](https://support.huaweicloud.com/api-dws/RestoreCluster.html)接口使用快照恢复集群。
9. 当不再需要快照时，调用[删除快照](https://support.huaweicloud.com/api-dws/DeleteSnapshot.html)接口删除快照。
10. 当集群使用完成或不再需要时，调用[删除集群](https://support.huaweicloud.com/api-dws/DeleteCluster.html)接口删除集群。
#### 前提条件
- 已创建VPC、子网和安全组，并获取VPC、子网和安全组的ID，具体请参见[创建VPC](https://support.huaweicloud.com/api-dws/dws_02_0040.html)。
- 已获取[IAM的EndPoint](https://developer.huaweicloud.com/endpoint?IAM)和[DWS的Endpoint](https://developer.huaweicloud.com/endpoint?DWS)。
- 已获取项目ID，具体请参见[获取项目ID](https://support.huaweicloud.com/api-dws/dws_02_0011.html)。
 
#### 集群管理
假设已获取前提条件中的信息为如下值（实际操作中您需要根据实际情况替换）：
- IAM的Endpoint：下面示例中以**iam_endpoint**代替
- DWS的Endpoint：下面示例中以**dws** **_endpoint**代替
- VPC的ID：**219ab8a0-1272-4049-a383-8ad0b770fa1** **1**
- 子网的ID：**d23ef2e9-8b90-49b3-bc4a-fd7d6bea6bec**
- 安全组的ID：**12e3c23a-8710-4b75-95e4-5c8d7f68ef3c**
- 项目ID：**9bc552e6-19af-4326-800d-281a92984636**
则可以通过如下步骤管理集群。
1. 调用其他接口前，需要调用[认证鉴权](https://support.huaweicloud.com/api-dws/dws_02_0064.html)中的接口获取Token，并设置成环境变量。
   
   ```
   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-4"
               }
           }
       }
   }' -v -k
   ```
   1. 获取响应Header中"X-Subject-Token"的值即为Token，示例如下：
      ```
      X-Subject-Token:MIidkgYJKoZIhvcNAQcCoIidgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...
      ```
      
   
   2. 使用如下命令将token设置为环境变量。 export Token={X-Subject-Token}
      **X-Subject-Token** 即为上一步骤获取到的token，示例如下：
      ```
      export Token=MIidkgYJKoZIhvcNAQcCoIidgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...
      ```
      
   
   
   
   
2. 调用[查询规格信息](https://support.huaweicloud.com/api-dws/ListNodeTypes.html)接口获取支持的节点类型。
   
   ```
   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
   ```
   获取响应如下所示：
   ```
   status CODE 200
   {
       "node_types": [
           {
               "spec_name": "dws.d2.xlarge",
               "id": "ebe532d6-665f-40e6-a4d4-3c51545b6a67",
               "detail": [
                   {
                       "type": "vCPU", 
                       "value": "4"
                   },
                   {
                       "value": "1675",
                       "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"
                   }
               ]
           }
       ]
   }
   ```
   
   
3. 调用[创建集群](https://support.huaweicloud.com/api-dws/CreateCluster.html)接口创建集群。
   
   创建集群配置样例信息如下：
   - 集群名称：dws-demo
   
   - 管理员用户名：dbadmin
   
   - 管理员密码：*passw0rd*
   
   - 端口：8000
   
   - 节点类型：dws.d1.xlarge
   
   - 节点数量：3
   
   - 弹性IP：auto_assign（自动绑定）
   
   
   ```
   curl -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": "passw0rd",
           "public_ip": {
               "public_bind_type": "auto_assign"
           }
   }' https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/clusters -v -k
   ```
   如果返回状态码为200，则说明创建集群请求下发成功。
   
   
4. 调用[查询集群列表](https://support.huaweicloud.com/api-dws/ListClusters.html)接口获取集群信息。
   
   ```
   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,
           "action_progress": 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-4b",
           "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"
            },
           "public_endpoints": [
               {
                   "public_connect_info": "dws-demo.cn-north-4.myhuaweicloud.com",
                   "jdbc_url": "jdbc:postgresql://dws-demo.cn-north-4.myhuaweicloud.com/<YOUR_DATABASE_name>"
               }
            ],
           "endpoints": [
               {
                   "connect_info": "dws-demo.cn-north-4.myhuaweicloud.com",
                   "jdbc_url": "jdbc:postgresql://dws-demo.cn-north-4.myhuaweicloud.com/<YOUR_DATABASE_name>"
               },
            ] , 
           "updated": "2018-01-15T12:50:06",
           "created": "2018-01-15T12:50:06", 
           "recent_event": 1
           }
       ]
   }
   ```
   - status的状态如果为"CREATING"，则表示集群正处于创建中；若为"AVAILABLE"则表示集群创建成功。
   
   - dws-demo集群对应的UUID为7ba031f6-81f4-4670-ad20-c490b91877e5，记录该UUID，方便后续步骤使用。
   
   
   
   
5. 调用[查询集群详情](https://support.huaweicloud.com/api-dws/ListClusterDetails.html)接口查看集群详细内容。
   
   ```
   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
   ```
   获取响应如下所示：
   ```
   {
       "cluster": {
           "id": "7ba031f6-81f4-4670-ad20-c490b91877e5",
           "status": "AVAILABLE",
           "name": "dws-demo",
           "updated": "2018-01-15T12:50:06",
           "created": "2018-01-15T12:50:06",
           "user_name": "dbadmin",
           "sub_status": "NORMAL",
           "task_status": null,
           "action_progress": 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-4b",
           "port": 8000,
           "vpc_id": "219ab8a0-1272-4049-a383-8ad0b770fa11",
           "public_ip": {
               "public_bind_type": "auto_assign",
               "eip_id": "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574"
           },
           "public_endpoints": [
           {
                   "public_connect_info": "dws-demo.cn-north-4.myhuaweicloud.com",
                   "jdbc_url": "jdbc:postgresql://dws-demo.cn-north-4.myhuaweicloud.com/<YOUR_DATABASE_name>"
            }
            ],
           "endpoints": [
           {
                   "connect_info": "dws-demo.cn-north-4.myhuaweicloud.com",
                   "jdbc_url": "jdbc:postgresql://dws-demo.cn-north-4.myhuaweicloud.com/<YOUR_DATABASE_name>"
           },
           {
                   "connect_info": "192.168.0.12:8000",
                   "jdbc_url": "jdbc:postgresql://192.168.0.12:8000/<YOUR_DATABASE_name>"
           }
            ],
           "version": "1.1.0",
           "maintain_window": {
               "day": "Wed",
               "start_time": "18:00",
               "end_time": "22:00"
           }, 
           "recent_event": 1,
           "tags": null, 
           "parameter_group": {
                 "id": "157e9cc4-64a8-11e8-adc0-fa7ae01bbebc",               "name": "Default-Parameter-Group-dws ",               "status": "In-Sync"
           } 
       }
   }
   ```
   响应消息中还可以查询到集群的"public_endpoints"和"endpoints"等信息，集群创建成功后，可以使用"public_endpoints"或"endpoints"从外部进行集群访问。
   
   
6. 调用[创建快照](https://support.huaweicloud.com/api-dws/CreateSnapshot.html)接口创建快照。
   
   基于集群dws-demo创建一个名称为snapshotForDemoCluster的快照。
   ```
   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" 
     }
   }
   ```
   如果返回状态码为200，则说明快照创建请求下发成功，记录"id"，供后续查询快照详情时使用。
   
   
7. 调用[查询快照列表](https://support.huaweicloud.com/api-dws/ListSnapshots.html)接口查看快照是否创建成功。
   
   ```
   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
   ```
   如果响应消息中快照状态为"AVAILABLE"，则说明快照创建成功；若为"CREATING"，则表示快照正在创建中。
   ```
   { 
       "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" 
       } 
   }
   ```
   
   
8. 调用[恢复集群](https://support.huaweicloud.com/api-dws/RestoreCluster.html)接口使用快照恢复集群。
   
   将快照snapshotForDemoCluster恢复到名称为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
   ```
   如果返回状态码为200，则说明集群恢复成功，可通过[查询快照详情](https://support.huaweicloud.com/api-dws/ListSnapshotDetails.html)查看集群恢复状态。
   
   
9. 当快照不再需要时，调用[删除快照](https://support.huaweicloud.com/api-dws/DeleteSnapshot.html)接口删除快照。
   
   ```
   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
   ```
   如果返回状态码为202，则说明快照删除成功。
   
   
10. 当集群使用完成或不再需要时，调用[删除集群](https://support.huaweicloud.com/api-dws/DeleteCluster.html)接口删除集群。
    
    ```
    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
    ```
    如果返回状态码为202，则说明集群删除成功。