API使用说明

API使用说明

！！！接口不支持异步请求，建议在后端使用！！！

API有两种使用方式：1.cli命令、2.http请求

配置通讯密钥

登录运行URLOS的主机，在 /data/urlos/master-config/config.jsonc 中自添加 “globalApiKey”，不短于60位，如：

{
    "globalApiKey": "*^Ln!DLFk=a9i-uCgU8*BKLgqV#RIXxtQI.^Bt)@8%qFQ(ToNVEsCLV=qQZj" // 示例，实际使用请自定义字符串
}

采用cli命令的方式

采用cli命令的方式使用接口，必须要登录到安装有URLOS的主机中运行命令。运行命令的方式为：

docker exec -i urlos sh -ce 'urlos.sh "{API}&globalApiSign={md5(globalApiKey)}&getJson=1" "{要post提交的数据}"'

示例

请求方式：GET
接口地址：m=admin&c=swarm&a=list

docker exec -i urlos sh -ce 'urlos.sh "a=list&c=swarm&m=admin&globalApiSign=b50e45d2bf0a6fd436a0ade287a82f62&getJson=1"'

请求方式：POST
接口地址：m=admin&c=swarm&a=add

docker exec -i urlos sh -ce 'urlos.sh "a=add&c=swarm&m=admin&globalApiSign=b50e45d2bf0a6fd436a0ade287a82f62&getJson=1" "name=test001&nodeIpRange=192.168.111.0/24&uid=1&storageDir=/data/&storageDirConfirm=/data/"'

或

docker exec -i urlos sh -ce 'urlos.sh "a=add&c=swarm&m=admin&globalApiSign=b50e45d2bf0a6fd436a0ade287a82f62&getJson=1" "BASE64:eyJuYW1lIjoidGVzdDAwMSIsIm5vZGVJcFJhbmdlIjoiMTkyLjE2OC4xMTEuMC8yNCIsInVpZCI6MSwic3RvcmFnZURpciI6Ii9kYXRhLyIsInN0b3JhZ2VEaXJDb25maXJtIjoiL2RhdGEvIn0="'

注意：

globalApiKey需要用md5加密

要post的数据有两种格式：一种是序列化为查询字符串格式、一种是BASE64加密格式。例子：原数据为JSON格式：

{
     "name": "test001",
     "nodeIpRange": "192.168.111.0/24",
     "uid": 1,
     "storageDir": "/data/",
     "storageDirConfirm": "/data/"
 }

1）将提交的数据序列化为查询字符串格式：

 "name=test001&nodeIpRange=192.168.111.0/24&uid=1&storageDir=/data/&storageDirConfirm=/data/"

2）用BASE64加密:

先将原数据转为字符串：

'{"name":"test001","nodeIpRange":"192.168.111.0/24","uid":1,"storageDir":"/data/","storageDirConfirm":"/data/"}'

然后加密字符串为BASE64：

BASE64('{"name":"test001","nodeIpRange":"192.168.111.0/24","uid":1,"storageDir":"/data/","storageDirConfirm":"/data/"}');

最终提交的数据格式为”BASE64:{已加密字符串}”：

 "BASE64:eyJuYW1lIjoidGVzdDAwMSIsIm5vZGVJcFJhbmdlIjoiMTkyLjE2OC4xMTEuMC8yNCIsInVpZCI6MSwic3RvcmFnZURpciI6Ii9kYXRhLyIsInN0b3JhZ2VEaXJDb25maXJtIjoiL2RhdGEvIn0="

采用http请求的方式

签名参数

字段名	类型	描述	必填	示例值
globalApiClientIp	string	访问终端IP	是	192.168.1.2
globalApiTimestamp	string	时间戳	是	1585894268
globalApiNonceStr	string	随机字符串	否
globalApiKey	string	通讯密钥，在URLOS系统设置里配置填写	是
getJson	string	获取返回的数据为JSON格式，固定值为1	是	1
v	string	用以区分不同版本的URLOS接口，根据实际版本填写，最低版本为1.2.5	是	1.2.5

接口使用方法

生成签名
拼接请求url

生成签名

示例：

示例中接口地址为：m=admin&c=swarm&a=list

将接口地址的参数和上面表格的签名参数合并：

{
  "a": "list",
  "c": "swarm",
  "m": "admin",
  "v": "1.2.5",
  "getJson": 1,
  "globalApiKey": "通讯密钥",
  "globalApiClientIp": "访问终端IP",
  "globalApiNonceStr": "随机字符串",
  "globalApiTimestamp": "时间戳"
}

参数名ASCII码从小到大排序（字典序，PHP语言用ksort函数对参数名的数组进行排序），排序后的结果：

{
  "a": "list",
  "c": "swarm",
  "getJson": 1,
  "globalApiClientIp": "访问终端IP",
  "globalApiKey":"通讯密钥",
  "globalApiNonceStr": "随机字符串",
  "globalApiTimestamp": "时间戳",
  "m": "admin",
  "v": "1.2.5"
}

然后序列化为键值对格式的字符串：

"a=list&c=swarm&getJson=1&globalApiClientIp={访问终端IP}&globalApiKey={通讯密钥}&globalApiNonceStr={随机字符串}&globalApiTimestamp={时间戳}&m=admin&v=1.2.5"

md5加密键值对格式的字符串得到签名globalApiSign：
```
{
  "globalApiSign": "81d57813115a3dcf9d45d4c02f182526"
}
```

拼接请求url

示例中的接口地址为：m=admin&c=swarm&a=list

最终的请求参数如下：

{
    "a": "list",
    "c": "swarm",
    "m": "admin",
    "v": "1.2.5",
    "getJson": 1,
    "globalApiNonceStr": "随机字符串", // 此处的随机字符串跟签名里的随机字符串一致
    "globalApiTimestamp": "时间戳", // 此处的时间戳跟签名里的时间戳一致
    "globalApiSign": "81d57813115a3dcf9d45d4c02f182526" // 签名字符串
}

然后序列化为键值对格式的字符串，加上域名拼接后，最终请求url如下：

https://{你网站的ip或者域名}:9966/?m=admin&c=swarm&a=list&v=1.2.5&globalApiNonceStr={随机字符串}&getJson=1&globalApiTimestamp={时间戳}&globalApiSign=81d57813115a3dcf9d45d4c02f182526

获取终端IP

接口说明：获取终端IP
接口地址：https://{你网站的ip或者域名}:9966/getClientIp
请求方式：GET

请求示例：

发起请求

curl -k "https://{你网站的ip或者域名}:9966/getClientIp"

返回结果

59.42.180.228