V Cloud

V Cloud 平台 API 指南

概述

我们给开发者提供API来查询服务商信息，服务类型信息，服务信息以及订单信息。V Cloud market 命令行工具和服务商SDK节点会通过这些API与平台进行交互。

创建服务商信息

提示

强烈建议使用服务模版管理服务注册信息

POST /api/v1/service/provider

请求body

{
	"name": "provider-name",
	"id": "provider-name",
	"walletAddress": "ATxxxxxxxxxxxxxxxxxxaaddfsawrEDAs",
	"apiHost": "some-ip-domain-host",
	"category2ID": {
		"category-name-1": "category-id-1"
	}
}
名称 类型 必须 说明
name string True 服务商名称，需唯一
id string True 同服务商名称
walletAddress string True 服务商VSYS 钱包地址
apiHost string True api 主机地址
category2ID dict False 服务种类名称与服务种类ID的映射

查询服务商信息

GET /api/v1/service/provider?

查询变量

名称 类型 说明
id string 服务商id
name string 同上，服务商名称，需唯一
walletAddress string 服务商钱包地址
current number 当前页面数
pageSize number 页面显示数据大小

返回

Status: 200 OK

{
    "list": [
        {
            "name": "provider-name",
            "walletAddress": "ATzxxxxxxxxxxxxxxxxxxxxxxebud",
            "signAddress": "ATzxxxxxxxxxxxxxxxxxxxxxxebud",
            "id": "provider-name",
            "apiHost": "http://localhost:3001",
            "category2ID": {
                "Container-Service": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
                "Container-Service-Working": "a242e27a-5bba-4e2c-a7f4-92cced21ff71"
            }
        }
    ],
    "pagination": {
        "total": 1,
        "current": 1,
        "pageSize": 10
    }
}

服务商品目中list的变量

list 数组中包含多个服务商信息。以下是一个服务商所包含的变量。

名称 类型 说明
name string 服务商名称
walletAddress string 服务商vsys钱包地址
signAddress string 上传服务模版时用于签名的地址
id string 服务商ID，与 name变量相同
apiHost string 用于获取UserService的服务商主机地址
category2ID dict 服务种类名称与服务种类ID的映射
pagination中的变量
名称 类型 说明
total number 该请求服务商信息的总数
current number 当前页面数
pageSize number 页面数大小

获取服务商信息

GET  /api/v1/service/provider/:id

返回

Status: 200 OK

{
    "name": "v-kube-service",
    "walletAddress": "ATxxxxxxxxxxxxxxxxxxxxxebud",
    "signAddress": "ATxxxxxxxxxxxxxxxxxxxxxebud",
    "id": "v-kube-service",
    "apiHost": "http://localhost:3001",
    "category2ID": {
        "Container-Service": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
        "Container-Service-Working": "a242e27a-5bba-4e2c-a7f4-92cced21ff71"
    }
}

请参考 服务商信息解释

创建服务种类

提示

强烈建议使用服务模版管理服务注册信息

POST /api/v1/service/category

请求 Body

{
	"provider": "provider-name",
	"name": "category-name",
	"serviceOptions": {
		"custom-field-1": "custom-value-1"
	},
	"description": "some-description",
	"name2ID": {
		"service-type-name-1": "service-type-id-1"
	}
	"apiHost": "service-type-backup-api-host"
}
名称 类型 必须 说明
provider string True 该服务种类所属服务商
name string True 服务种类名称，在一个服务商中应该名称唯一
serviceOptions dict False 该服务种类提供的服务选项
description string False 服务种类描述，可让用户明白所提供服务或使用方法
name2ID dict False 服务名称与服务ID的映射
apiHost string False 该服务种类下具体服务的备用API地址

查询服务种类信息

GET /api/v1/service/category?

查询变量

名称 类型 说明
ids string[] 服务种类ID的字符串数组
provider string 服务商名称
name string 服务种类名称
current number 当前页面数
pageSize number 页面显示数据大小

返回

Status: 200 OK

{
    "list": [
        {
            "categoryID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
            "provider": "provider-name",
            "name": "Container-Service",
            "serviceOptions": {
                "custom-options-1": [
                    "value-1",
                    "value-2",
                    "value-3",
                ],
                "custom-options-2": [
                    "value-1",
                    "value-2"
                ]
            },
            "description": "Deploy docker images to k8s cluster",
            "name2ID": {
                "Container Service": "af91f22a-ffcf-4e8c-9a83-f1f6bcc8bf6e"
            },
            "apiHost": ""
        },
    ],
    "pagination": {
        "total": 2,
        "current": 1,
        "pageSize": 10
    }
}
服务种类list中的变量
名称 类型 说明
categoryID string 服务种类ID
provider string 该服务种类所属服务商名称
name string 服务种类名称
serviceOptions dict 字符串对字符串数组的字典，为服务选项名称与其值的映射
description string 服务种类描述
name2ID dict 字符串对字符串的字典，服务名称与其ID的映射
apiHost string 该服务种类的备用API地址

pagination 结构体的变量请参考

获取服务种类

GET /api/v1/service/category/:id

返回

Status: 200 OK

{
    "categoryID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
    "provider": "provider-name",
    "name": "Container-Service",
    "serviceOptions": {
        "custom-options-1": [
            "value-1",
            "value-2",
            "value-3",
        ],
        "custom-options-2": [
            "value-1",
            "value-2"
        ]
    },
    "description": "Deploy docker images to k8s cluster",
    "name2ID": {
        "Container Service": "af91f22a-ffcf-4e8c-9a83-f1f6bcc8bf6e"
    },
    "apiHost": ""
}

返回数据解释请参考服务种类变量

创建具体服务

POST /api/v1/service/category

请求 Body

{
	"name": "service-type-name",
	"durationToPrice": [
		{
			"price": 100,
			"charingOptions": {
				"custom-field-1": "custom-value"
			},
			"duration": {
				1: 1
				20: 0.99
				100: 0.89
			}
		}
	],
	"provider": "provider-name",
	"refundable": true,
	"categoryID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
	"category": "category-name-1",
	"serviceOptions": {
		"custom-field-1": [
			"custom-value-1",
			"custom-value-2",
			"custom-value-3"
		]
	},
	"serviceAPI": {
		"start": "some-lua-script",
		"stop": "some-lua-script",
		"refund": "some-lua-script",
		"normal": {
			"api-name": "/api/v1/some/function"
		},
		"secret": {
			"api-name": "/api/v1/some/secret/func"
		}
	},
	"description": "go-charger",
	"apiHost": "11.22.88.4"
}
名称 类型 必须 说明
name string True 服务名称，在该服务种类下需唯一
durationToPrice object True 基础价格，以及服务时长与打折系数的映射
provider string True 服务商名称
refundable bool True 该服务是否可退款
categoryID string True 该服务所属服务种类ID
category string True 该服务所属服务种类名称
serviceOptions dict False 该服务的服务选项
serviceAPI object False 购买服务后可用的API
description string False 服务描述
apiHost string False 购买服务后，给用户使用的API地址

durationToPrice的变量

名称 类型 必须 说明
price number False 每小时价格(VSYS)
chargingOptions map[string]string False 使基础价格不一样的服务选项
duration map[int]float False 服务时长与打折系数的映射

serviceAPI的变量

名称 类型 必须 说明
start string False 服务启动的lua脚本, script has to be url encoded.
stop string False 服务关闭的lua脚本, script has to be url encoded.
refund string False 自定义的退款脚本, script has to be url encoded.
normal map[string]string False API名称与API路径的映射. 给用户购买服务后使用
secret map[string]string False API名称与API路径的映射. 给用户购买服务后使用。但需要用户提供secret

查询服务

GET /api/v1/service/type?

查询服务变量

名称 类型 说明
ids string[] ID的字符串数组
provider string 服务商名称
category string 基于服务种类名称获取服务
name string 基于服务名称获取服务
minPrice float 基于最低基础价获取服务
maxPrice float 基于最高基础价获取服务
current number 当前页面数
pageSize number 页面数据大小

返回

Status: 200 OK

{
    "list": [
        {
            "id": "af91f22a-ffcf-4e8c-9a83-f1f6bcc8bf6e",
            "name": "Container Service",
            "durationToPrice": [
                {
                    "price": 100,
                    "chargingOptions": {
                        "custom-options-1": "value-1"
                    },
                    "duration": {
                        "100": 0.9,
                        "200": 0.85
                    }
                },
                {
                    "price": 200,
                    "chargingOptions": {
                        "custom-options-1": "value-2"
                    },
                    "duration": {
                        "100": 0.9,
                        "200": 0.85
                    }
                },
                {
                    "price": 500,
                    "chargingOptions": {
                        "custom-options-1": "value-3"
                    },
                    "duration": {
                        "100": 0.9,
                        "200": 0.85
                    }
                },
            ],
            "provider": "provider-name",
            "refundable": true,
            "categoryID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
            "category": "Container-Service",
            "serviceOptions": {
                "custom-options-1": [
                    "value-1",
                    "value-2",
                    "value-3",
                ],
                "custom-options-2": [
                    "value-1",
                    "value-2"
                ]
            },
            "serviceAPI": {
                "start": "",
                "stop": "",
                "refund": "",
                "normal": {},
                "secret": {}
            },
            "description": "Documentation for user to use this service: http:xxxxxxx",
            "apiHost": ""
        },
    ],
    "pagination": {
        "total": 1,
        "current": 1,
        "pageSize": 10
    }
}

list中服务的变量

名称 类型 说明
id string 服务ID
name string 服务名称
durationToPrice object[] 基于不同收费服务选项的不同基础价格
provider string 该服务所属服务商名称
refundable bool 是否可退款
categoryID string 该服务所属服务种类ID
serviceOptions dict 该服务可提供的服务选项, 变量解释请参考服务种类变量
serviceAPI object 支持的API服务。用户只可见normal 和 secret变量内容.
description string 服务描述包含付款流程以及服务使用方式
apiHost string 该服务的API地址

durationToPrice数组中的object变量

名称 类型 说明
price number 每小时的基础价格
chargingOptions dict 决定基础价格收费选项
duration dict 服务时长与收费打折系数的映射

serviceAPI变量

名称 类型 说明
normal dict 可用API服务名称与路径的映射，不需认证
secret dict 可用API服务名称与路径的映射，需认证

上传服务模版

GET /api/v1/template/add

平台节点会读取请求body中的yaml服务模版并在平台注册服务信息. 服务模版解释 请参考。

查询订单信息

GET /api/v1/order?

查询订单变量

名称 类型 说明
id string 订单ID
startFrom number 订单查询起始时间
endAt number 订单查询结束时间
serviceID string 与该服务ID相关的订单
service string 与该服务名称相关的订单
address string 与该地址（下单人）相关的订单
recipient string 与该服务商地址相关的订单
statuses[] string[] 与该状态字符串数组相关的订单
serviceActivated bool user service是否启用
userServiceStartFrom number 订单中user service的查询起始时间
userServiceEndAt number 订单中user service的查询结束时间
serviceStatuses[] string[] 包含这些user service状态的订单
current number 当前页面数
pageSize number 页面数据大小

返回

{
    "list": [
        {
            "createdAt": 1622793531,
            "updatedAt": 1622801453,
            "duration": 1,
            "serviceExpiredDate": 0,
            "amount": 9.5,
            "amountPaid": 9.5,
            "serviceID": "53bc15ca-e6f8-42ef-a814-8c5f14d22b79",
            "service": "xxxxx Service",
            "serviceCategoryID": "a242e27a-5bba-4e2c-a7f4-92cced21ff71",
            "provider": "xxxx provider",
            "address": "AU2xxxxxxxxxxxxxxxxxxxxPXGp5sj",
            "recipient": "ATxxxxxxxxxxxxxxxxxxiiEouTebud",
            "id": "d9ae2543-3185-4839-bc56-f885aa879881",
            "serviceOptions": {
                "custom-option-1": "value-1",
                "custom-option-2": "value-1"
            },
            "status": "OrderFiled",
            "lastPaymentTS": 1622793555,
            "PaidTS": 1622793555,
            "FiledTS": 1622793555,
            "completeTS": 1622801452,
            "refundTS": 0,
            "publicKey": "",
            "serviceActivated": false,
            "serviceActivateTS": 1622793555,
            "endAt": 1622801341,
            "serviceStatus": "ServiceDone",
            "serviceRunningTS": 1622797741,
            "serviceAbortTS": 0,
            "serviceDoneTS": 1622801452,
            "magic": ""
        }
    ],
    "pagination": {
        "total": 1,
        "current": 1,
        "pageSize": 10
    }
}

list中order的变量

名称 类型 说明
createdAt number 数据库中创建的时间
updatedAt number 数据库中最后更新的时间
duration number 服务时长（小时）
serviceExpiredDate number 用户定义的服务结束时间
amount number 需付总额
amountPaid number 剩余需付金额
serviceID string 该订单的下定服务ID
service string 该订单的服务名称
serviceCategoryID string 该订单的服务种类ID
provider string 提供服务的服务商名称
address string 创建订单的用户地址
recipient string 服务商收款地址
id string 订单ID
serviceOptions object 请参考 服务种类变量解释
status string 订单状态
lastPaymentTS numner 用户最后付款时间
paidTS number 用户完成订单付款时间
filedTS number 服务商完成资源准备时间
completeTS number 订单完成时间
refundTS number 订单退款时间
publicKey number 用于加密服务商资源信息的公钥
serviceActivated bool user service 状态是否启用
serviceActivatedTS number user service 状态启用时间
endAt number user service 服务结束时间
serviceStatus string user service 服务状态
serviceRunningTS number 服务启动计时时间
serviceAbortTS number 服务中止时间
serviceDoneTS number 服务完成时间
magic string DEPRECIATED

获取订单信息

GET /api/v1/order/id/:id

返回信息请参考 订单变量

创建订单

提示

用户需要使用VSYS钱包中的地址私钥来签名请求，则请求才会成功。

请求 Body

{
	"amount": 10.0,
	"address": "ATxxxxxxxxxxxxxsdflkjkdkdkdk",
	"duration": 1,
	"serviceExpiredDate": 16903049433,
	"serviceID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
	"serviceOptions": {
		"custom-field": "value-1"
	}
}
名称 类型 必须 说明
amount float True 订单购买的金额
address string False 购买该订单的地址
duration number False 购买服务的时长,必须有其中一项 duration &serviceExpiredDate
serviceExpiredDate number False 用户定义的服务结束时间
serviceID string True 服务ID
serviceOptions dict False 用户所选服务选项
上次更新: 2021/6/17 上午7:15:15