文档首页/ 数据仓库服务 GaussDB(DWS)/ 更多文档/ API参考（阿布扎比区域）/ 快速入门

更新时间：2022-06-13 GMT+08:00

查看PDF

快速入门

本节通过调用一系列API，以集群管理为例，介绍使用GaussDB(DWS) API的基本流程。集群管理的流程如下：

调用认证鉴权获取用户的token，因为在后续的请求中需要将token放到请求消息头中作为认证。
调用查询节点类型接口获取支持的节点类型。
调用创建集群接口创建集群。
调用查询集群列表接口获取集群信息。
调用查询集群详情接口查看集群详细内容。
调用创建快照接口创建快照。
调用查询快照列表接口查看快照是否创建成功。
调用恢复集群接口使用快照恢复集群。
当快照不再需要时，调用删除手动快照接口删除快照。
当集群使用完成或不再需要时，调用删除集群接口删除集群。

前提条件

已创建VPC、子网和安全组，并获取VPC、子网和安全组的id，具体请参见创建VPC。
已获取IAM的Endpoint和GaussDB(DWS)的Endpoint。
已获取项目ID，具体请参见获取项目ID。

集群管理

假设已获取前提条件中的信息为如下值（实际操作中您需要根据实际情况替换）：

IAM的Endpoint：下面示例中以iam_endpoint代替
GaussDB(DWS) 的Endpoint：下面示例中以dws_endpoint代替
VPC的id：219ab8a0-1272-4049-a383-8ad0b770fa11
子网的id：d23ef2e9-8b90-49b3-bc4a-fd7d6bea6bec
安全组的id：12e3c23a-8710-4b75-95e4-5c8d7f68ef3c
项目ID：9bc552e6-19af-4326-800d-281a92984636

则可以通过如下步骤管理集群。

调用其他接口前，需要调用认证鉴权中的接口获取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": "ae-ad-1"
            }
        }
    }
}' -v -k

获取响应Header中“X-Subject-Token”的值即为Token，示例如下。

X-Subject-Token:MIidkgYJKoZIhvcNAQcCoIidgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...

使用如下命令将token设置为环境变量。
export Token={X-Subject-Token}
X-Subject-Token即为上一步骤获取到的token，示例如下。
```
export Token=MIidkgYJKoZIhvcNAQcCoIidgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...
```

调用查询节点类型接口获取支持的节点类型。

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"
                }
            ]
        }
    ]
}

调用创建集群接口创建集群。

创建集群配置样例信息如下：

集群名称：dws-demo
管理员用户名：dbadmin
管理员密码：Dws2017demo!
端口：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": "Dws2017demo!",
        "public_ip": {
            "public_bind_type": "auto_assign"
        }
}' https://{dws_endpoint}/v1.0/9bc552e6-19af-4326-800d-281a92984636/clusters -v -k

如果返回状态码为200，则说明创建集群请求下发成功。

调用查询集群列表接口获取集群信息。

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": "ae-ad-1",
        "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": "10.0.0.8:8000",
                "jdbc_url": "jdbc:postgresql://10.0.0.8:8000/<YOUR_DATABASE_name>"
            }
         ],
        "endpoints": [
            {
                "connect_info": "192.168.0.10:8000",
                "jdbc_url": "jdbc:postgresql://192.168.0.10:8000/<YOUR_DATABASE_name>"
            },
            {
                "connect_info": "192.168.0.12:8000",
                "jdbc_url": "jdbc:postgresql://192.168.0.12:8000/<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，方便后续步骤使用。

调用查询集群详情接口查看集群详细内容。

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": "ae-ad-1",
        "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": "10.0.0.8:8000",
                "jdbc_url": "jdbc:postgresql://10.0.0.8:8000/<YOUR_DATABASE_name>"
         }
         ],
        "endpoints": [
        {
                "connect_info": "192.168.0.10:8000",
                "jdbc_url": "jdbc:postgresql://192.168.0.10:8000/<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": "22:00",
            "end_time": "02: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”从外部进行集群访问。

调用创建快照接口创建快照。

基于集群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”，供后续查询快照详情时使用。

调用查询快照列表接口查看快照是否创建成功。

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" 
    } 
}

调用恢复集群接口使用快照恢复集群。

将快照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，则说明集群恢复成功，可通过查询快照详情查看集群恢复状态。

当快照不再需要时，调用删除手动快照接口删除快照。

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，则说明快照删除成功。

当集群使用完成或不再需要时，调用删除集群接口删除集群。

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，则说明集群删除成功。

上一篇：返回结果

下一篇：API说明

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消