服务端 REST API 概述
最近更新:2022-5-21
服务端 REST API 概述
UMS 提供遵从 REST 规范的 HTTP API,以供开发者远程调用 UMS 提供的服务。
REST API 基本约束
API 资源列表
名称 | 资源 | 描述 |
---|---|---|
普通消息发送 | POST https://api.ums.jiguang.cn/v1/broadcast | 广播发送 |
POST https://api.ums.jiguang.cn/v1/sent | 其他发送方式 | |
模板消息发送 | POST https://api.ums.jiguang.cn/v1/template/broadcast | 广播发送 |
POST https://api.ums.jiguang.cn/v1/template/sent | 其他发送方式 | |
消息撤回 | POST https://api.ums.jiguang.cn/v1/retract/{msgid} | 撤回一条消息 |
用户管理 | POST https://api.ums.jiguang.cn/v1/user/opt | 批量添加、更新用户信息 |
POST https://api.ums.jiguang.cn/v1/user/delete | 批量删除用户信息 | |
素材管理 | POST https://api.ums.jiguang.cn/v1/material | 对素材进行管理,上传或下载 |
获取通道 token | GET https://api.ums.jiguang.cn/v1/token?type={type} | 获取各个通道的鉴权token |
鉴权方式
极光 REST API 采用 HTTP 基本认证 的验证方式。
基本做法为,HTTP Header(头)里加 Authorization:
Authorization: Basic ${base64_auth_string}
Authorization: Basic ${base64_auth_string}
此代码块在浮窗中显示
Header 名称是 "Authorization",值是 base64 转换过的 "username:password" 对(中间有个冒号)。在 UMS API 的场景里,username 是 ChannelKey,密码是 MasterSecret。这二者可以在 UMS Web 控制台基础设置-渠道信息中查看。
base64_auth_string 的生成算法为:base64(ChannelKey:MasterSecret)
注:在调用用户管理的 API 时,还可以使用专门的 AccessKey 和 MasterSecret 进行鉴权
鉴权举例
你的 ChannelKey 是 "7d431e42dfa6a6d693ac2d04", MasterSecret 是 "5e987ac6d2e04d95a9d8f0d1",则发送模板消息时,使用 curl 命令的话,是这样写:
curl --insecure -X POST -v https://api.ums.jiguang.cn/v1/template/sent -H "Content-Type: application/json"
-u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"
-d '
{
"template_id":10001,
"template_para":{"user":"xxx","url":"xxx"},
"app_para":{
"platform":"ios",
"time_to_live":9999,
"big_push_duration":10,
"apns_production":true
},
"aud_xxx": xxx,
"option": {
"sendno": "test_mail",
"expire_time": 1602523317,
"owner":"admin",
"black_id":1234,
"white_id":1234,
"priority":2
}
}'
curl --insecure -X POST -v https://api.ums.jiguang.cn/v1/template/sent -H "Content-Type: application/json"
-u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"
-d '
{
"template_id":10001,
"template_para":{"user":"xxx","url":"xxx"},
"app_para":{
"platform":"ios",
"time_to_live":9999,
"big_push_duration":10,
"apns_production":true
},
"aud_xxx": xxx,
"option": {
"sendno": "test_mail",
"expire_time": 1602523317,
"owner":"admin",
"black_id":1234,
"white_id":1234,
"priority":2
}
}'
此代码块在浮窗中显示
HTTP 请求发出的请求是:
> POST https://api.ums.jiguang.cn/v1/template/sent HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
> POST https://api.ums.jiguang.cn/v1/template/sent HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
此代码块在浮窗中显示
API 频率控制
UMS API 对访问次数具有频率控制。即一定的时间窗口内,API 允许调用的次数是有限制的。
频率定义
一个时间窗口内,每个 AppKey 的 API 调用数量。
VIP 版本各 API 频率如下表,免费版本为共享通道,频次比 VIP 低:
API 类型 | 频率 | 说明 |
---|---|---|
广播发送消息 | 100 条/天 | 普通消息、模板消息的发送共享频率,超频将报错 1015029 |
其他方式发送消息 | 600 次/分钟 | 普通消息、模板消息的发送共享频率,超频将报错 1015030 |
用户管理 | 600 次/分钟 | 添加、更新、删除 API 共享频率,超频将报错 1015030 |
如需升级 VIP,或将 VIP 频次提升到更高,请联系商务。
超出频率限制
当一个请求遇到频率限制时,UMS API 将返回对应的错误码,示例如下:
{
"code": 1015030,
"message": "api请求超出频率限制"
}
{
"code": 1015030,
"message": "api请求超出频率限制"
}
此代码块在浮窗中显示
频率优化建议
- 均匀地分布请求到各时间窗口
- 根据标签、用户ID 大量请求时,避免无效的标签和用户ID。
- 如果大量针对标签、用户ID 的请求内容一致,可以每次调用可以填写多个接收者。
文档内容是否对您有帮助?