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

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

通过header传递 global-api-key 鉴权（推荐此方式）
通过url签名鉴权

直接在请求头上添加 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 gU8BKLgqV#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

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

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

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

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

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

"a=list&c=swarm&getJson=1&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

API使用说明

API使用说明

配置通讯密钥

采用cli命令的方式

采用http请求的方式

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

CURL请求事例：

JS Fetch请求事例：

方式二通过url签名鉴权

签名生成步骤如下：

第一步

第二步

例子

签名参数说明：

接口使用方法

生成签名

拼接请求url

获取终端IP

请求示例：

发起请求

返回结果

results matching ""

No results matching ""

API使用说明

配置通讯密钥

采用cli命令的方式

采用http请求的方式

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

CURL请求事例：

JS Fetch请求事例：

方式二 通过url签名鉴权

签名生成步骤如下：

第一步

第二步

例子

签名参数说明：

接口使用方法

生成签名

拼接请求url

获取终端IP

请求示例：

发起请求

返回结果

results matching ""

No results matching ""

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

方式二通过url签名鉴权