更新时间:2024-05-17 GMT+08:00

快速入门

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

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

前提条件

集群管理

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

  • 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

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

  1. 调用其他接口前,需要调用认证鉴权中的接口获取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": "ap-southeast-1"
                }
            }
        }
    }' -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. 调用查询节点类型接口获取支持的节点类型。

    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. 调用创建集群接口创建集群。

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

    • 集群名称: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. 调用查询集群列表接口获取集群信息。

    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": "ap-southeast-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": "dws-demo.ap-southeast-1.myhuaweicloud.com",
                    "jdbc_url": "jdbc:postgresql://dws-demo.ap-southeast-1.myhuaweicloud.com/<YOUR_DATABASE_name>"
                }
             ],
            "endpoints": [
                {
                    "connect_info": "dws-demo.ap-southeast-1.myhuaweicloud.com",
                    "jdbc_url": "jdbc:postgresql://dws-demo.ap-southeast-1.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. 调用查询集群详情接口查看集群详细内容。

    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": "ap-southeast-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": "dws-demo.ap-southeast-1.myhuaweicloud.com",
                    "jdbc_url": "jdbc:postgresql://dws-demo.ap-southeast-1.myhuaweicloud.com/<YOUR_DATABASE_name>"
             }
             ],
            "endpoints": [
            {
                    "connect_info": "dws-demo.ap-southeast-1.myhuaweicloud.com",
                    "jdbc_url": "jdbc:postgresql://dws-demo.ap-southeast-1.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. 调用创建快照接口创建快照。

    基于集群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. 调用查询快照列表接口查看快照是否创建成功。

    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. 调用恢复集群接口使用快照恢复集群。

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

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

    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. 当集群使用完成或不再需要时,调用删除集群接口删除集群。

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