公共接口文档
前言
本文档将向您介绍如何接入得力云公共服务平台。
准备工作
应用接入方在正式接入前,需要向得力云公共服务平台申请app_id
和app_key
作为身份的标识。
接入地址
- 测试环境: http://s-psp.delicloud.com
- 生产环境: https://psp.delicloud.com
访问规则
API调用方在每次调用公共服务平台的任何API时,需要在 HTTP Header
中加入以下字段
头部字段 | 格式 | 必传 | 参数说明 |
---|---|---|---|
app_id | 字符串 | Y | 应用id,需申请获得 |
timestamp | 长整型 | Y | 13位时间戳, unixtime精确到毫秒 |
nonce | 字符串 | Y | 6位随机字符串 |
sig | 字符串 | Y | 签名字段,生成规则见下文 |
注意:
- 以上字段均为必填,如若缺失任一字段,则本次请求的ResponseCode会为
400
。 - 平台会对
timestamp
进行校验,落后当前时间10分钟以上的请求会被拒绝,ResponseCode为400
。 - 如若sig字段计算错误或者使用了未授权的
app_id
,那么本次请求的ResponseCode为401
。
签名生成规则
-
将
app_id
,app_key
,nonce
,timestamp
键和其值组成app_id=v1&app_key=v2&nonce=v3×tamp=v4
格式字符串待签名计算(键的顺序不能变更) -
将上一步的得到的字符串进行MD5摘要,得到的结果就是
sig
字段的值
sig
字段计算示例:
app_id = "6682532562501148673"
app_key = "xVoQHBLyW2TIhjluqwZtFjra"
nonce = "YQOG3o"
timestamp = 1594169576000
/** 待签名的字符串: */
sigStr = "app_id=6682532562501148673&app_key=xVoQHBLyW2TIhjluqwZtFjra&nonce=YQOG3o×tamp=1594169576000"
/** sig = MD5("app_id=v1&app_key=v2&nonce=v3×tamp=v4") */
sig = MD5(sigStr) = "13a4c40edbe73b778be3339ba51719ec"
文件服务
1. 文件上传接口
本接口用于上传文件,文件的最大尺寸为500MiB。如果上传时设置参数public为false,则只返回file_id。本接口有两种使用方式:表单上传和字节流上传
1)表单上传:设置 Content-Type=multipart/form-data,接口格式如下:
- 请求参数
POST /api/v1.0.0/file?https={https}&public={public}&client={client}&expire={expire} HTTP/1.1
Content-Type: multipart/form-data;
- 请求参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
public | 布尔值 | N | 是否公开,true 则返回public_url |
client | 字符串 | Y | 上传者签名,如果为设备,建议输入sn |
https | 布尔值 | N | 下载链接是否为https链接,true或未设置 则默认为https链接 |
expire | 数字 | N | 文件上传的过期时间,单位为ms,例如1分钟后过期,则设置为60000。文件的最大过期时间为6个月 |
file | 文件 | Y | 要上传的文件 |
2)字节流上传:设置 Content-Type=application/octet-stream,接口格式如下:
- 请求参数
POST /api/v1.0.0/file?https={https}&public={public}&client={client}&expire={expire}&name={name} HTTP/1.1
Content-Type: application/octet-stream;
- 请求参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
public | 布尔值 | N | 是否公开,true 则返回public_url |
client | 字符串 | Y | 上传者签名,如果为设备,建议输入sn |
https | 布尔值 | N | 下载链接是否为https链接,true或未设置 则默认为https链接 |
expire | 数字 | N | 文件上传的过期时间,单位为ms,例如1分钟后过期,则设置为60000。文件的最大过期时间为6个月 |
name | 字符串 | Y | 文件名称 |
- 返回结果
{
"code": 0,
"msg": "",
"data": {
"file_id": "31522343243234234",
"public_url": "https://file.delicloud.com/njfwefownfwnodwedw",
"due_time": "1595571950340"
}
}
- 返回结果说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
file_id | 字符串 | Y | 文件上传的唯一id |
public_url | 字符串 | N | 文件的下载地址 |
due_time | 字符串 | N | 文件的到期时间,格式为ms级别的时间戳 |
2. 文件查询接口
本接口用于查询文件的基本信息(包括下载地址和到期时间),如果文件上传时设置为公开,那么任何应用都可根据file_id查询到文件的信息。
如果设置为不公开,那么只有同一个appId的应用才可以查询到文件的信息。
- 请求
GET /api/v1.0.0/file/{file_id} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
file_id | 字符串 | Y | 文件上传的唯一id,上传文件接口返回 |
- 返回结果
{
"code": 0,
"msg": "",
"data": {
"file_id": "31522343243234234",
"public_url": "https://file.delicloud.com/njfwefownfwnodwedw",
"due_time": "1595571950340"
}
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
file_id | 字符串 | Y | 文件上传的唯一id |
public_url | 字符串 | N | 文件的下载地址 |
due_time | 字符串 | N | 文件的到期时间,格式为ms级别的时间戳 |
节假日及工作日服务
1. 查询年度休息日及工作日接口
本接口用于查询某年度休息日及工作日的情况,未在响应结果里说明的日期按照标准工作周期来决定。
- 请求
GET /api/1.0.0/holiday?year=${year} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
year | 整数 | N | 比如 2020,若未提供则默认查询当年情况 |
- 返回结果
{
"code": 0,
"msg": "",
"data": {
"year": 2020, // 年份
"holidays": [ // 本年度节假日列表
{
"code": "", // 节日代码
"name": "", // 节假日名称,比如“春节”
"days": [ // 本次节假日休息或补班的日子
{
"day": "",
"name": "", // 加假日当天的别称,比如“大年初二”
"type": "" // BREAK 休息日; WORK 工作日
}
]
}
]
}
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码 |
msg | 字符串 | N | 错误信息 |
2. 查询某日期是否为工作日接口
本接口用于查询某日期的休假情况,比如休息日、节日、周末及补班等。
- 请求
GET /api/1.0.0/holiday/day?date=${date} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
date | 字符串 | N | 比如 2020-07-01,若未提供则默认查询当天情况 |
- 返回结果
{
"code": 0,
"msg": "",
"data": {
"day": "", // 日期
"name": "", // 节假日当天的别称,比如“大年初三”
"type": "" // BREAK 休息日; WORK 工作日
}
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码 |
msg | 字符串 | N | 错误信息 |
天气服务接口
1. 查询今日的天气信息
本接口用于根据城市代码或经纬度参数来查询今日的天气信息
- 请求
GET /api/1.0.0/weather?location=${location}&city=${city} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
location | 字符串 | N | 城市的ADCode, 或者经度, 纬度格式的字符串, 优先级高于 city字段 |
city | 字符串 | N | 城市的名称, 可使用拼音或者汉字, 当 location 字段为空时,使用该字段进行查询 |
- 返回结果
{
"code": 0,
"msg": "",
"data": {
"temp": "4", // 预报温度
"icon_url": "http://file.delicloud.com/psp/weather/502.png", // 天气icon下载链接
"text": "霾", // 天气状况的文字描述
"wind360": "45", // 风向360角度
"humidity": "71", // 相对湿度
"precip": "0.0", // 降水量
"pressure": "1030", // 大气压强
"vis": "2", // 能见度
"cloud": "75", // 云量
"dew": "-2" // 露点温度
}
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码, 0 说明业务成功 |
msg | 字符串 | N | 错误信息 |
temp | 字符串 | N | 预报温度 |
icon_url | 字符串 | N | 天气icon的url下载地址 |
text | 字符串 | N | 天气状况的文字描述 |
wind360 | 字符串 | N | 风向360角度 |
humidity | 字符串 | N | 相对湿度 |
precip | 字符串 | N | 降水量 |
pressure | 字符串 | N | 大气压强 |
vis | 字符串 | N | 能见度 |
cloud | 字符串 | N | 云量 |
dew | 字符串 | N | -2 |
语音转换服务接口
1. 将文字转换为语音文件
本接口用于将一段文字转换为语音
- 请求
GET /api/1.0.0/tts?text=${text}&mode=${mode} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
text | 字符串 | Y | 待转换为语音文件的文本信息, 不得超过64个字符 |
mode | 数字 | N | 转换模式,0 表示普通转换, 1 表示姓名的转换, 默认为0, 传入其它值将为 |
- 返回结果
{
"code": 0,
"msg": "",
"data": {
"origin_str": "张三",
"mp3_address": "http://file.delicloud.xin/c7bf6b8aa97a62cabebb4aea86c299cf"
}
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码, 0 说明业务成功 |
msg | 字符串 | N | 错误信息 |
origin_str | 字符串 | Y | 输入文本 |
url | 字符串 | N | 语音文件的下载地址, 语音文件默认为mp3格式 |
消息推送服务接口
1. APP消息推送
本接口用于对于手机APP用户进行消息推送
- 请求
POST /api/1.0.0/message/app HTTP/1.1
-
请求体
{ // 消息内容 "content": { "template": "app_message_code", "template_params": { "name": "张三" }, "extra": { "url": "http://baidu.com" }, }, // 消息推送平台 "platforms": ["android", "ios"], // 消息推送目标 "target": { "identities": ["eplus_app_12312312", "eplus_app_4534534"], "tags": ["rich", "male"] } }
-
参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
template | 字符串 | Y | 消息模板的code |
template_params | JSON对象 | N | 用于填充消息模板的参数 |
extra | JSON对象 | N | 额外参数,会透传给APP |
platforms | JSON数组 | Y | 推送平台,目前仅支持 android, ios两个平台 |
identities | JSON数组 | N | 唯一推送目标,需要APP端事先注册 |
tags | JSON数组 | N | 标签推送目标,需要APP端事先注册 |
- 返回结果
{
"code": 0,
"msg": "",
"data": "6749459052564258817"
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码, 0 说明业务成功 |
msg | 字符串 | N | 错误信息 |
data | 字符串 | Y | 消息唯一id,用于后续查询消息内容和送达情况 |
2. 批量查询APP推送消息
本接口用于批量查询指定消息id的消息内容和送达情况
- 请求
GET /api/1.0.0/message/app?msgIdList=${msgIdList} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
msgIdList | 字符串 | Y | 消息id列表,将消息id用逗号隔开组成列表,最多不超过10条 |
- 返回结果
{
"code": 0,
"msg": "",
"data": [
{
"msg_id": "6748114075695177729",
"title": "欢迎使用得力e+",
"body": "欢迎使用得力e+, 戴钰朦!",
// 自定义数据
"payload": {
"jump_link": "delieplus://app/me",
"url": "http://baidu.com"
},
"android_send": "1",
"ios_send": "0"
}
]
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码, 0 说明业务成功 |
msg | 字符串 | N | 错误信息 |
msg_id | 字符串 | Y | 消息唯一id |
title | 字符串 | Y | 消息标题 |
body | 字符串 | Y | 消息内容 |
payload | JSON对象 | Y | 消息自定义数据 |
android_send | 数字 | Y | 安卓送达消息数量 |
ios_send | 数字 | Y | ios送达数量 |
3. 短信消息推送
本接口用于对指定手机进行短信推送
- 请求
POST /api/1.0.0/message/short-message HTTP/1.1
-
请求体
{ // 消息内容 "content": { "template": "SMS_204106750", "template_params": { "code": "213123" } }, // 需要推送短信的手机号列表 "target": [ { "mobile": "13419631980", "mobile_region": "86" } ] }
-
参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
template | 字符串 | Y | 消息模板的code |
template_params | JSON对象 | N | 用于填充消息模板的参数 |
mobile | 字符串 | Y | 推送的手机号 |
mobile_region | 字符串 | Y | 手机号区号 |
单次消息推送的手机号不能超过1000个
- 返回结果
{
"code": 0,
"msg": "",
"data": "6749459052564258817"
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码, 0 说明业务成功 |
msg | 字符串 | N | 错误信息 |
data | 字符串 | Y | 消息唯一id,用于后续查询消息内容和送达情况 |
2. 批量查询短信消息
本接口用于批量查询指定消息id的消息内容和送达情况
- 请求
GET /api/1.0.0/message/short-message?msgIdList=${msgIdList} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
msgIdList | 字符串 | Y | 消息id列表,将消息id用逗号隔开组成列表,最多不超过10条 |
- 返回结果
{
"code": 0,
"data": {
// 消息列表
"msg_detail_list": [
{
"body": "登录验证码",
"mobiles": [13419631980, 13419631978],
"msg_id": "6749459052564258817",
"result": 0
}
]
},
"msg": ""
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码, 0 说明业务成功 |
msg | 字符串 | N | 错误信息 |
msg_id | 字符串 | Y | 消息唯一id |
mobiles | JSON数组 | Y | 手机号列表 |
body | 字符串 | Y | 消息内容 |
result | 数字 | Y | 发送结果,0 表示待发送, 1 表示推送成功,2 表示推送失败 |
app 版本升级服务
1. 查询app升级接口
本接口用于查询 app 的可用升级,如果返回的数据中 data 为空说明无可用升级
- 请求
GET /api/1.0.0/app-upgrade/{app_code}version=${version} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
app_code | 字符串 | Y | app代码 |
version | 字符串 | N | app版本号,如果为空则默认为0.0.0 |
- 返回结果
{
"code": 0,
"msg": "",
"data": {
"app_code": "plus_apk",
"version": "1.0.1",
"url": "http://oss-cn-shanghai.aliyuncs.com/oss-1565578267643-40428198.apk", // apk下载地址
"checksum": "c2.0.1",// apk的校验代码
"size": 123456789, // apk的大小
"min_platform_version": 3.4, // app平台的最小版本
"max_platform_version": 1.2, // app平台的最大版本
"description": "1、消息模块增加了发起单人聊天功能,多人聊天室中增加了@功能; 2、通讯录中增加了管理员标记,可以快速定位管理员了; 3、修复了一段时间未登录后被挤下线的问题。", // 更新日志
"upgrade_type": "normal",
}
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码 |
msg | 字符串 | N | 错误信息 |
app_code | 字符串 | Y | app代号 |
version | 字符串 | Y | 升级版本 |
url | 字符串 | Y | apk下载地址 |
checksum | 字符串 | Y | apk校验值 |
size | 整型 | Y | apk大小 |
min_platform_version | 浮点数 | Y | 最小平台版本,例如应用的最小安卓版本为 5.0 |
max_platform_version | 浮点数 | Y | 最大平台版本,例如应用的最大安卓版本为 9.0 |
description | 字符串 | Y | 本次升级的更新日志 |
upgrade_type | 字符串 | Y | 升级类型, normal - 正常升级, force - 强制升级, explicit - 隐式升级 |
2. 分页查询app升级列表
本接口用于分页查询app的全部升级列表, 升级列表按版本号倒序排列
- 请求
GET /api/1.0.0/app/page/{app_code}?page={page}&size=${size} HTTP/1.1
- 参数说明
请求参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
app_code | 字符串 | Y | app代号 |
page | 数字 | Y | 分页查询的页码 |
size | 数字 | Y | 分页查询每页的数据量 |
- 返回结果
{
"code": 0,
"msg": "",
"data": {
"page": 0,
// 数据列表
"rows": [
{
"app_code": "push_apk",
"checksum": "c2.0.1",
"description": "1、消息模块增加了发起单人聊天功能,多人聊天室中增加了@功能; 2、通讯录中增加了管理员标记,可以快速定位管理员了; 3、修复了一段时间未登录后被挤下线的问题。",
"max_platform_version": 3.4,
"min_platform_version": 1.2,
"size": 123456789,
"upgrade_type": "normal",
"url": "http://oss-cn-shanghai.aliyuncs.com/oss-1565578267643-40428198.apk",
"version": "1.1.0"
}
],
"size": 0,
"total": 0,
"total_page": 0
}
}
- 参数说明
返回参数 | 格式 | 必传 | 参数说明 |
---|---|---|---|
code | 整数 | Y | 错误码 |
msg | 字符串 | N | 错误信息 |
page | 整数 | Y | 当前页码 |
size | 整型 | Y | 当前页码数据量 |
total | 整型 | Y | 总的数据量 |
total_page | 整型 | Y | 总页数 |
app_code | 字符串 | Y | appd代号 |
version | 字符串 | Y | 升级版本 |
url | 字符串 | Y | apk下载地址 |
checksum | 字符串 | Y | apk校验值 |
size | 整型 | Y | apk大小 |
min_platform_version | 浮点数 | Y | 最小平台版本,例如应用的最小安卓版本为 5.0 |
max_platform_version | 浮点数 | Y | 最大平台版本,例如应用的最大安卓版本为 9.0 |
description | 字符串 | Y | 本次升级的更新日志 |
upgrade_type | 字符串 | Y | 升级类型, normal - 正常升级, force - 强制升级, explicit - 隐式升级 |