API:ShortURL


概览


Shorturl是 SUBMAIL 的短网址 API。

使用 Shorturl API 可以获取、创建、编辑或删除您的短网址。

shorturl API 使用 HTTP 规范中的 GET, POST, PUT, DELETE 方法对短网址进行操作,使用 GET 方法获取单个或全部短网址、POST 方法创建新的短网址并提交至 SUBMAIL 人工审核、PUT 方法更新或编辑一个短网址,或使用 DELETE 方法删除一个短网址。

短网址引擎支持 SUBHOOK 异步推送状态,短网址在后台人工审核后,会使用 SUBHOOK 进行主动推送状态。



URL


<主> https://service.mysubmail.com/shorturl


支持格式


格式URL
jsonhttps://service.mysubmail.com/shorturl.json(默认)
xmlhttps://service.mysubmail.com/shorturl.xml


http 请求方式


GET获取全部短网址,或获取指定的单个短网址
POST创建一个新的短网址
PUT编辑或更新一个短网址
DELETE删除一个短网址


是否需要授权


参阅 API 授权和验证机制


ShortURl GET 方法(获取短网址列表)请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的短网址应用ID
short_urlstring必需短网址
要获取单个模板,请将在此参数中提交您要查询的具体短网址。为空则获取所有的短网址。
rowsint可选100单次返回数据的行数
请将该值控制在10-1000之间,若指定了一个无效的 rows 参数,API 将默认返回 100行数据
offsetint可选0数据偏移指针
该值可以指定返回数据的偏移指针,例:假如单次请求包含150条数据,rows参数采用50行,此时需要查询第51-100行的数据,请将 offset 参数设为1(即数据偏移50行)即可得到第51-100行的数据,offset=2时,将返回第101-150行数据,以此类推
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙 数字签名
参阅 API 授权与验证机制 > 授权和验证方式


ShortURl POST 方法(创建短网址)请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的短网址应用ID
url string必需默认目标网址。
您需要处理成短网址的长网址。
groupstring可选短网址群组ID
itemstring可选自定义标记。
手机号码,国际手机号码,邮件地址,或任意字符串,此参数通常配合 短网址群组功能使用。(最大长度不能超过32位)
domainstring可选link.wiki域名选择。
SUBMAIL提供的域名选择:link.wiki、suburl.cn、yc2.co、v2c.co、sw2.co
企业版支持自定义域名设置。
access_passwordstring可选访问密码。
access_limitint可选访问次数限制。
expireint可选设置短链接过期时间,按小时计算。默认7天后过期。
routesjsonString可选短网址路由。
此参数支持对桌面端,移动端,app,机器人的路由跳转操作
具体参数示列请参考ShortUrl Routes参数说明
tagstring可选此参数用于标记一次 API 请求(最大长度不超过 64 位)
添加了 tag 参数的 API 请求,会在所有的 SUBHOOK 事件中携带此参数。
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙 数字签名
参阅 API 授权与验证机制 > 授权和验证方式


ShortURl PUT 方法(更新短链接)请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的短网址的应用 ID
short_urlstring必需目标短网址
urlstring可选目标网址
pausestring可选短网址模板是否暂停使用。
参数为true或者false
itemstring可选自定义标记。
手机号码,国际手机号码,邮件地址,或任意字符串,此参数通常配合 短网址群组功能使用。(最大长度不能超过32位)
access_passwordstring可选访问密码
access_limitint可选访问次数限制
expireint可选设置短网址过期时间,按小时计算
tagstring可选此参数用于标记一次 API 请求(最大长度不超过 32 位)
添加了 tag 参数的 API 请求,会在所有的 SUBHOOK 事件中携带此参数。
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙 数字签名
参阅 API 授权与验证机制 > 授权和验证方式


ShortURL DELETE 方法(删除短网址)请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的短网址应用 ID
short_urlstring必需需要删除的目标短网址
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙 数字签名
参阅 API 授权与验证机制 > 授权和验证方式


ShortURL Routes参数说明


routes参数json结构说明

routes

desktop :可选参数。设置桌面端操作系统点击跳转的目标url,如果此参数不传则跳转到默认设置目标url。
windows :可选参数。设置windows操作系统点击跳转的目标url,如果此参数不传则跳转到默认设置目标url。
mac :可选参数。设置mac操作系统点击跳转的目标url,如果此参数不传则跳转到默认设置目标url。
linux :可选参数。设置linux操作系统点击跳转目标url,如果此参数不传则跳转到默认设置目标url。
mobile:可选参数。设置移动端操作系统点击跳转目标url,如果此参数不传则跳转到默认设置目标url。
device:可选参数。如果此参数不传则跳转到默认设置目标url。
ios:可选参数。设置ios操作系统点击跳转目标url,如果此参数不传则跳转到默认设置目标url。
android:可选参数。设置android操作系统点击跳转目标url,如果此参数不传则跳转到默认设置目标url。
others:可选参数。设置除ios,android操作系统外点击跳转目标url,如果此参数不传则跳转到默认设置目标url。
app:可选参数。设置微信以及支付宝点击跳转目标url,如果此参数不传则跳转到对应手机操作系统设置的目标跳转url。
wechat:可选参数。设置微信app内点击跳转目标url,如果此参数不传则跳转到对应手机操作系统设置的目标跳转url。
alipay:可选参数。设置支付宝app内点击跳转目标url,如果此参数不传则跳转到对应手机操作系统设置的目标跳转url。
robot:可选参数。设置机器人点击跳转目标地址,如果此参数不传则跳转到默认设置目标url。


routes参数json字符串示列

    {
        "desktop": {
            "windows": "https://www.mysubmail.com/windows",
            "mac": "https://www.mysubmail.com/mac",
            "linux": "https://www.mysubmail.com/linux"
        },
        "mobile": {
            "device": {
                "ios": "https://www.mysubmail.com/ios",
                "android": "https://www.mysubmail.com/android",
                "others": "https://www.mysubmail.com/others"
            },
            "app": {
                "wechat": "https://www.mysubmail.com/chs/store",
                "alipay": "https://www.mysubmail.com/slinks"
            }
        },
        "robot": "https://www.mysubmail.com/robot"
    }


代码示例


使用 CURL GET方法获取模板列表


发送 CURL
curl -s "https://service.mysubmail.com/shorturl?appid=your_appid&signature=your_appkey"


返回
{
    "status": "success",
    "urls": [
        {
            "short_url": "http://link.wiki/anPi5G",
            "long_url": "http://mysubmail.cn/developer",
            "items": "",
            "access_password": "0",
            "access_limit": "0",
            "pause": "false",
            "routes": {
              "desktop": {
                "windows": "https://www.mysubmail.com/windows",
                "mac": "https://www.mysubmail.com/mac",
                "linux": "https://www.mysubmail.com/linux"
                         },
              "mobile": {
                "device": {
                  "ios": "https://www.mysubmail.com/ios",
                  "android": "https://www.mysubmail.com/android",
                  "others": "https://www.mysubmail.com/others"
                        },
               "app": {
                 "wechat": "https://www.mysubmail.com/chs/store",
                 "alipay": "https://www.mysubmail.com/slinks"
                      }
                        },
              "robot": "https://www.mysubmail.com/robot"
                      },
            "qrcode": "http://suburl.cn/qrcode?url=httxxxink.wiki/KSWfb5",
            "tag": "test2",
            "create_at": "2019-07-17 10:28:11",
            "review_status": "2",
            "review_status_description": "通过审核",
            "expire_by_hours": "168",
            "expire_at": "2019-07-24 10:28:11"
        },
        {
            "short_url": "http://sw2.co/bTOCOG",
            "long_url": "http://www.baidu.com",
            "items": "",
            "access_password": "0",
            "access_limit": "0",
            "pause": "false",
             "routes": {
              "desktop": {
                "windows": "https://www.mysubmail.com/windows",
                "mac": "https://www.mysubmail.com/mac",
                "linux": "https://www.mysubmail.com/linux"
                         },
              "mobile": {
                "device": {
                  "ios": "https://www.mysubmail.com/ios",
                  "android": "https://www.mysubmail.com/android",
                  "others": "https://www.mysubmail.com/others"
                        },
               "app": {
                 "wechat": "https://www.mysubmail.com/chs/store",
                 "alipay": "https://www.mysubmail.com/slinks"
                      }
                        },
              "robot": "https://www.mysubmail.com/robot"
                      },
            "qrcode": "http://suburl.cn/qrcode?url=httxxxink.wiki/KSWfb5",
            "tag": "",
            "create_at": "2019-07-17 09:57:47",
            "review_status": "2",
            "review_status_description": "通过审核",
            "expire_by_hours": "168",
            "expire_at": "2019-07-24 09:57:47"
        }
    ]
}


使用 CURL POST方法提交短网址


发送 CURL
curl -d "appid=your_appid&signature=your_appkey&url=https://www.api.submail.cn&group=09ae645ddd5200915&item=test&routes={"desktop":{"windows":"https://www.mysubmail.com/windows","mac":"https://www.mysubmail.com/mac","linux":"https://www.mysubmail.com/linux"},"mobile":{"device":{"ios":"https://www.mysubmail.com/ios","android":"https://www.mysubmail.com/android","others":"https://www.mysubmail.com/others"},"app":{"wechat":"https://www.mysubmail.com/wechat","alipay":"https://www.mysubmail.com/alipay"}},"robot":"https://www.mysubmail.com/robot"}"。" https://service.mysubmail.com/shorturl.json


返回
{
    "status": "success",
    "short_url": "http://link.wiki/KSWfb5",
    "long_url": "https://blog.csdn.net/fdipzone/article/details/42463727/32132131、321///23123/32132133213",
    "routes": {
        "desktop": {
            "windows": "https://www.mysubmail.com/windows",
            "mac": "https://www.mysubmail.com/mac",
            "linux": "https://www.mysubmail.com/linux"
        },
        "mobile": {
            "device": {
                "ios": "https://www.mysubmail.com/ios",
                "android": "https://www.mysubmail.com/android",
                "others": "https://www.mysubmail.com/others"
            },
            "app": {
                "wechat": "https://www.mysubmail.com/chs/store",
                "alipay": "https://www.mysubmail.com/slinks"
            }
        },
        "robot": "https://www.mysubmail.com/robot"
    },
    "qrcode": "http://suburl.cn/qrcode?url=httxxxink.wiki/KSWfb5",
    "expire_at": "2021-04-01 16:33:42"
}

qrcode:为目标短网址生成的二维码地址。



使用 CURL PUT 方法修改短网址


发送 CURL
curl --data "appid=your_appid&signature=your_appkey&short_url=http://link.wiki/iM/GuvPeD&url=https://www.mysubmail.com&pause=true&item=submail&expire=100" -X put https://service.mysubmail.com/shorturl.json


返回
{
    "status":"success"
}


使用 CURL DELETE 方法删除短网址


发送 CURL
curl --data "appid=your_appid&signature=your_appkey&short_url=http://link.wiki/iM/GuvPeD" -X delete  https://service.mysubmail.com/shorturl.json


返回
{
    "status":"success"
}


review_status 短网址状态描述


review_status : 0未提交审核
review_status : 1正在审核
review_status : 2审核通过
review_status : 3未通过审核


返回值


请求成功
{
      "status":"success"
}


请求失败
{
      "status":"error",
      "code":"1xx",
      "msg":"error message"
}


错误代码


参阅 API 错误代码