服务端 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 批量删除用户信息

鉴权方式

极光 REST API 采用 HTTP 基本认证 的验证方式。

基本作法为,HTTP Header(头)里加 Authorization:

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
  }
}'

HTTP 请求发出的请求是:

> 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请求超出频率限制"
}

频率优化建议

  • 均匀地分布请求到各时间窗口
  • 根据标签、用户ID 大量请求时,避免无效的标签和用户ID。
  • 如果大量针对标签、用户ID 的请求内容一致,可以每次调用可以填写多个接收者。

Copyright 2011-2020, jiguang.cn, All Rights Reserved.
粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

Documentation built with MkDocs.