公共接口文档

前言

本文档将向您介绍如何接入得力云公共服务平台。

准备工作

应用接入方在正式接入前，需要向得力云公共服务平台申请app_id和app_key作为身份的标识。

接入地址

访问规则

API调用方在每次调用公共服务平台的任何API时，需要在 HTTP Header 中加入以下字段

头部字段 格式 必传 参数说明
app_id 字符串 Y 应用id，需申请获得
timestamp 长整型 Y 13位时间戳， unixtime精确到毫秒
nonce 字符串 Y 6位随机字符串
sig 字符串 Y 签名字段，生成规则见下文

注意:

签名生成规则

  1. 将app_id,app_key,nonce,timestamp键和其值组成app_id=v1&app_key=v2&nonce=v3&timestamp=v4格式字符串待签名计算(键的顺序不能变更)

  2. 将上一步的得到的字符串进行MD5摘要，得到的结果就是sig字段的值

sig 字段计算示例:

app_id = "6682532562501148673"
app_key = "xVoQHBLyW2TIhjluqwZtFjra"
nonce = "YQOG3o"
timestamp = 1594169576000

/** 待签名的字符串: */
sigStr = "app_id=6682532562501148673&app_key=xVoQHBLyW2TIhjluqwZtFjra&nonce=YQOG3o&timestamp=1594169576000"

/** sig = MD5("app_id=v1&app_key=v2&nonce=v3&timestamp=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
请求参数 格式 必传 参数说明
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
请求参数 格式 必传 参数说明
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 - 隐式升级