API quản lý VPS

Giới thiệu chung / Chức năng (API)

  • Xem thông tin của client (người dùng)
  • Liệt kê các orders dịch vụ của người dùng
  • Xem thông tin của các orders
  • Tạo order mới tương tự với order đã có
  • Liệt kê các gói services (dịch vụ) của người dùng đăng ký
  • Xem thông tin chi tiết của một dịch vụ
  • Tạm ngưng dịch vụ
  • Liệt kê VMs của gói dịch vụ
  • Xem thông tin của VM
  • Stop (tắt) VM
  • Start (mở) VM

Yêu cầu / Chuẩn bị

  • Tài khoản client (người dùng) VNDATA
  • Công cụ sử dụng - CURL

Cú pháp / Lệnh API

curl -X <method> https://api.clients.vndata.vn/api/<action> -u "<user_email>:<user_pass>" -H "Content-Type: application/json"

Trong đó:

  • method: HTTP method thao tác với API (GET, POST, PUT, DELETE)
  • action: Thực hiện các hàm chức năng
  • user_email: Tài khoản người dùng để đăng nhập vào Website VNDATA
  • user_pass: Mật khẩu người dùng để đăng nhập vào Website VNDATA

API

  • For Windows OS: Đối với hệ điều hành Windows, khi chạy API qua terminal để định dạng kết quả trả về theo bố cục dễ đọc, có thể sử dụng công cụ jq để định dạng lại đầu ra của lệnh gọi API
curl -X <method> https://api.clients.vndata.vn/api/<action> -u "<user_email>:<user_pass>" -H "Content-Type: application/json" | jq
  • For Linux OS: Còn với hệ điều hành Linux, ta sử dụng công cụ json_pp
curl -X <method> https://api.clients.vndata.vn/api/<action> -u "<user_email>:<user_pass>" -H "Content-Type: application/json" | json_pp

1. Client details

  • Mô tả: Xem thông tin cụ thể của người dùng
  • HTTP request (method /action): GET /clients/
curl -X GET https://api.clients.vndata.vn/api/clients/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
   "message" : {
      "address1" : "61/3 Bình Giã, P. 13, Q. Tân Bình, TP. HCM",
      "address2" : "",
      "cardtype" : "Visa",
      "city" : "Hồ Chính Minh",
      "client_id" : "479",
      "country" : "VN",
      "countryname" : "Viet Nam",
      "datecreated" : "2023-04-03",
      "email" : "vantien3111@gmail.com",
      "firstname" : "Văn Tiến",
      "lastlogin" : "2024-01-08 21:40:50",
      "lastname" : "Hồ Văn Tiến",
      "phonenumber" : "+84 368548741",
      "postcode" : "",
      "state" : "TP. HCM",
      "status" : "Active"
   },
   "success" : true
}

2. List orders

  • Mô tả: Liệt kê tất cả những orders của người dùng
  • HTTP request (method /action): GET /orders/
curl -X GET https://api.clients.vndata.vn/api/orders/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
   "message" : [
      {
         "balance" : "Completed",
         "date_created" : "2023-05-09 09:34:09",
         "id" : "1498", --> Biến @order_id
         "invtotal" : "",
         "module" : "Chuyển khoản nhanh 247 quét QR",
         "status" : "Active",
         "total" : "0"
      },
      {
         "balance" : "Cancelled",
         "date_created" : "2023-04-03 10:58:30",
         "id" : "1353", --> Biến @order_id
         "invtotal" : "154000",
         "module" : "Chuyển khoản nhanh 247 quét QR",
         "status" : "Active",
         "total" : "154000"
      }
   ],
   "success" : true
}
  • Sau khi chạy lệnh liệt kê các orders này, ta sẽ có thể lấy được biến order_id tương ứng với từng order để thực hiện việc xem thông tin chi tiết của order ở phần 3
  • Theo kết quả trả về như trên thì 1498 là order_id tương ứng với ngày tạo 09/05/2023, 1353 là order_id tương ứng với ngày tạo 03/04/2023

3. Order details

  • Mô tả: Xem thông tin chi tiết của order
  • HTTP request (method /action): GET /orders/@order_id/
  • order_id: Là ID của order tương ứng
curl -X GET https://api.clients.vndata.vn/api/orders/@order_id/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
   "message" : [
      {
         "billingcycle" : "Monthly",
         "category_id" : "22",
         "catname" : "VPS Storage",
         "commitment_date" : "",
         "domain" : "nextcloud1",
         "id" : "2613",
         "name" : "VPS Stor-3",
         "password" : "o_AWEgJdAMY_",
         "product_id" : "124", --> Biến @product_id
         "status" : "Active",
         "username" : "client_479_13"
      }
   ],
   "success" : true
}
  • Sau khi chạy lệnh xem thông tin của order này, ta sẽ có thể lấy được biến product_id tương ứng với từng order để thực hiện việc tạo order mới ở phần 4
  • Theo kết quả trả về như trên thì 124 là product_id tương ứng với order_id

4. Create new order

  • Mô tả: Tạo order mới tương tự với order cũ trước đó
  • HTTP request (method /action): POST /orders/@product_id/
  • product_id: Là ID product (dịch vụ) của order tương ứng
curl -X POST https://api.clients.vndata.vn/api/orders/@product_id/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json" -d '{"cycle":"m","domain":"domain_name"}'
  • cycle: Chu kỳ thanh toán dịch vụ (m - hàng tháng, q - hàng quý, a - hàng năm)
  • domain: Tên domain của server (Lưu ý: Tên chỉ được chưa ký tự chữ cái và dấu “-” trong tên)
  • Kết quả trả về:
{
  "message": [
    {
      "billingcycle": "Monthly",
      "catname": "VPS Windows",
      "commitment_date": "",
      "domain": "traioi-test",
      "id": "2515",
      "name": "VPS W2 MT",
      "password": "FiUY_jOMpq5_",
      "product_id": "269",
      "status": "Pending",
      "username": "traioitq"
    }
  ],
  "success": true
}

5. List services

  • Mô tả: Liệt kê tất cả những gói dịch vụ đã đăng ký của người dùng
  • HTTP request (method /action): GET /services/
curl -X GET https://api.clients.vndata.vn/api/services/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
   "accounts" : [
      {
         "billingcycle" : "Monthly",
         "client_id" : "479",
         "companyname" : "",
         "component_form_name" : "",
         "component_value_name" : "",
         "currency_id" : "0",
         "domain" : "nextcloud1",
         "extra_details" : {
            "usage" : {
               "capped" : false,
               "current" : {
                  "data_received" : 0,
                  "data_sent" : 0
               },
               "current_unit" : "GB",
               "end" : "2024-01-22 00:00:00",
               "lasttime" : 0,
               "log" : [],
               "migrated" : true,
               "notified" : false,
               "previous" : "2023-11-22",
               "suspended" : false,
               "vmdata" : {
                  "20263" : {
                     "hourly" : [],
                     "lasttime" : "",
                     "netin" : 0,
                     "netout" : 0,
                     "rate" : "",
                     "total" : {
                        "data_received" : 0,
                        "data_sent" : 0
                     },
                     "uptime" : 0
                  }
               }
            }
         },
         "firstname" : "Văn Tiến",
         "group_id" : "0",
         "id" : "2613", --> Biến @service_id
         "lastname" : "Hồ Văn Tiến",
         "manual" : "0",
         "name" : "VPS Stor-3",
         "next_due" : "0000-00-00",
         "paytype" : "Regular",
         "product_id" : "124",
         "qty" : "1",
         "service_group_id" : "0",
         "status" : "Active",
         "total" : "0",
         "type" : "3"
      }
   ],
   "server_time" : 1704763856,
   "sorter" : {
      "perpage" : 10,
      "sorterpage" : 1,
      "sorterrecords" : "11",
      "totalpages" : 2
   },
   "success" : true
}
  • Sau khi chạy lệnh liệt kê các services này, ta sẽ có thể lấy được biến service_id tương ứng với từng service để thực hiện việc xem thông tin chi tiết của service ở phần 6
  • Theo kết quả trả về như trên thì 2613 là service_id tương ứng với gói service có tên domain là nextcloud1

6. Service details

  • Mô tả: Xem thông tin chi tiết một dịch vụ của người dùng
  • HTTP request (method /action): GET /services/@service_id/
  • service_id: là ID của dịch vụ tương ứng
curl -X GET https://api.clients.vndata.vn/api/services/@service_id/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
   "message" : {
      "billingcycle" : "Monthly",
      "billingtype" : "PrePay",
      "category_id" : "22",
      "category_name" : "VPS Storage",
      "client_id" : "479",
      "date_created" : "2023-12-22",
      "date_suspended" : "0000-00-00",
      "domain" : "nextcloud1",
      "next_due" : "0000-00-00",
      "order_id" : "2295",
      "password" : "o_AWEgJdAMY_",
      "product_name" : "VPS Stor-3",
      "status" : "Active",
      "vmid" : "20263",
      "vpsip" : "103.144.87.151"
   },
   "success" : true
}

7. Service suspend

  • Mô tả: Tạm ngưng dịch vụ
  • HTTP request (method /action): DELETE /services/@service_id/
curl -X DELETE https://api.clients.vndata.vn/api/services/@service_id/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
  "info": [
    "Function has been scheduled for execution"
  ],
  "server_time": 1700992130,
  "success": true
}

8. List VMs in service

  • Mô tả: Liệt kê tất cả những VM (server / VPS) có trong gói dịch vụ cụ thể
  • HTTP request (method /action): GET /services/@service_id/vms/
curl -X GET https://api.clients.vndata.vn/api/services/@service_id/vms/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
  "message": [
    {
      "cpu": 0,
      "cpus": 2,
      "disk": 0,
      "diskread": 0,
      "diskwrite": 0,
      "maxdisk": 32212254720,
      "maxmem": 4294967296,
      "mem": 2906828532,
      "name": "traioi-test",
      "netin": 140834582,
      "netout": 889222,
      "pid": 2812130,
      "serial": 1,
      "status": "running",
      "uptime": 4901,
      "vmid": 60227 --> Biến @vmid
    }
  ],
  "success": true
}
  • Sau khi chạy lệnh liệt kê các VMs này, ta sẽ có thể lấy được biến vmid tương ứng với từng VM để thực hiện việc xem thông tin chi tiết của VM ở phần 9
  • Theo kết quả trả về như trên thì 60227 là vmid tương ứng

9. VM details

  • Mô tả: Xem thông tin chi tiết về VM
  • HTTP request (method /action): GET /services/@service_id/vms/@vmid/
  • vmid: Là ID của VM trong gói dịch vụ
curl -X GET https://api.clients.vndata.vn/api/services/@service_id/vms/@vmid/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
  "message": {
    "cpu": 0,
    "cpus": 2,
    "disk": 0,
    "diskread": 0,
    "diskwrite": 0,
    "maxdisk": 32212254720,
    "maxmem": 4294967296,
    "mem": 2907001821,
    "name": "traioi-test",
    "netin": 140966111,
    "netout": 889354,
    "pid": 2812130,
    "serial": 1,
    "status": "running",
    "uptime": 5008,
    "vmid": 60227
  },
  "success": true
}

10. Stop VM

  • Mô tả: OFF (tắt) VM
  • HTTP request (method /action): POST /services/@service_id/vms/@vmid/stop/
curl -X POST https://api.clients.vndata.vn/api/services/@service_id/vms/@vmid/stop/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
  "message": "Stop VM successful",
  "success": true
}

11. Start VM

  • Mô tả: ON (mở) VM
  • HTTP request (method /action): POST /services/@service_id/vms/@vmid/start/
curl -X POST https://api.clients.vndata.vn/api/services/@service_id/vms/@vmid/start/ -u "<user_email>:<user_pass>" -H "Content-Type: application/json"
  • Kết quả trả về:
{
  "message": "Start VM successful",
  "success": true
}

Trong bài viết này là cách hướng dẫn mọi người có thể quản lý dịch vụ, VPS của mình thông qua API