服务端 REST API 概述

UMS 提供遵从 REST 规范的 HTTP API，以供开发者远程调用 UMS 提供的服务。

REST API 基本约束

API 被设计为符合 HTTP，REST 规范。
如无特殊说明，调用参数值应转码为：UTF-8，URL 编码。
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 的请求内容一致，可以每次调用可以填写多个接收者。