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="'


注意:

  1. globalApiKey需要用md5加密

  2. 要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

  1. 接口地址参数和上面表格的签名参数合并:

    {
      "a": "list",
      "c": "swarm",
      "m": "admin",
      "v": "1.2.5",
      "getJson": 1,
      "globalApiKey": "通讯密钥",
      "globalApiClientIp": "访问终端IP",
      "globalApiNonceStr": "随机字符串",
      "globalApiTimestamp": "时间戳"
    }
    
  2. 参数名ASCII码从小到大排序(字典序,PHP语言用ksort函数对参数名的数组进行排序),排序后的结果:

    {
      "a": "list",
      "c": "swarm",
      "getJson": 1,
      "globalApiClientIp": "访问终端IP",
      "globalApiKey":"通讯密钥",
      "globalApiNonceStr": "随机字符串",
      "globalApiTimestamp": "时间戳",
      "m": "admin",
      "v": "1.2.5"
    }
    
  3. 然后序列化为键值对格式的字符串:

    "a=list&c=swarm&getJson=1&globalApiClientIp={访问终端IP}&globalApiKey={通讯密钥}&globalApiNonceStr={随机字符串}&globalApiTimestamp={时间戳}&m=admin&v=1.2.5"
    
  4. 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

请求示例:

发起请求
curl -k "https://{你网站的ip或者域名}:9966/getClientIp"
返回结果
59.42.180.228
Copyright © 广州市万岁云计算有限公司 2020 all right reserved,powered by Gitbook文档最近一次修订时间: 2020-08-11 15:31:24

results matching ""

    No results matching ""