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请求的方式

http请求分两种鉴权方式,选其中一种即可:

  1. 通过header传递 global-api-key 鉴权(推荐此方式)

  2. 通过url签名鉴权

方式一 通过header传递 global-api-key 鉴权 (推荐此方式)

直接在请求头上添加 global-api-key 字段,值为在配置文件 config.json 里的 globalApiKey 的值。

特别注意 如使用此方式,在生产环境上一定要使用https协议。

CURL请求事例:
curl -L -H "global-api-key: {globalApiKey的值}" "https://{你网站的ip或者域名}/?u=master&m=admin&c=swarm&a=list&v=99999&getJson=1"
JS Fetch请求事例:
fetch("https://{你网站的ip或者域名}/u=master&m=admin&c=swarm&a=list&v=99999&getJson=1", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "global-api-key": "globalApiKey的值"
  }
})
    .then((response) => response.json())
  .then((data) => {
    console.log("Success:", data);
  })
  .catch((error) => {
    console.error("Error:", error);
  });


方式二 通过url签名鉴权

签名生成步骤如下:

第一步

使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA

特别注意以下重要规则:

  • 参数名ASCII码从小到大排序(字典序,PHP语言用ksort函数对参数名的数组进行排序即可)
  • 参数名区分大小写
  • URLOS的接口可能会增加字段,验证签名时必须支持增加的扩展字段
第二步

并对stringA进行MD5运算,得到globalApiSign值。

例子

API:

a=list&c=swarm&m=admin

参数名ASCII码从小到大排序并用MD5加密:

MD5(a=list&c=swarm&getJson=1&globalApiKey=*^Ln!DLFk=a9i-uCgU8*BKLgqV#RIXxtQI.^Bt)@8%qFQ(ToNVEsCLV=qQZj%UW5)[H~IByaThZnyg)H73W13gG;P0TV&VehaZov%xL!!-R~U-4UuyOI3H(%w:e%S43#&globalApiNonceStr=abc&globalApiTimestamp=1585894268&m=admin&v=1.2.5)

得到globalApiSign:

7878247012a672e2d4cc27bb8aa6fdb6

最终请求url:

https://{你网站的ip或者域名}/?m=admin&c=swarm&a=list&v=1.2.5&globalApiNonceStr=abc&getJson=1&globalApiTimestamp=1585894268&globalApiSign=7878247012a672e2d4cc27bb8aa6fdb6

签名参数说明:

字段名 变量名 必填 类型 示例值 描述
时间戳 globalApiTimestamp String 1585894268 取当前的时间的时间戳
随机字符串 globalApiNonceStr String !DLFk=a9i-uCgU8
*BKLgqV#RIXxtQI.^
随机字符串,不长于32位
通讯密钥 globalApiKey String ^Ln!DLFk=a9i-uC
gU8
BKLgqV#RIX
xtQI.^Bt)@8%qF
Q(ToNVEsCLV=qQZj
通讯密钥,不短于60位,在URLOS系统设置里配置填写
JSON方式获取 getJson String 1 值一定是 1,返回JSON格式的数据
URLOS版本 v String 1.2.5 为了加以区分不同版本的URLOS接口,根据实际版本填写,最低版本为1.2.5。
是如果是版本99999,表示所有版本的api都可以使用


接口使用方法

  • 生成签名
  • 拼接请求url


生成签名

示例:

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

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

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

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

    "a=list&c=swarm&getJson=1&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文档最近一次修订时间: 2023-10-11 17:14:54

results matching ""

    No results matching ""