MobPush REST API 概述

特别提示：建议不要在客户端直接调用REST API。得到 Appkey 和 AppSecret 信息的人可能进行恶意的推送。

建议的使用方式是：调用RESTAPI 的代码放在开发者应用服务器上。开发者应用服务器对自己的客户端提供接口，开发者服务器收到来自客户端的请求后再调REST API 。

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

API 基本约束

• API 请求有 频率限制。
• API 请求有 黑名单机制。

API 资源列表

名称	资源	Base URL	描述
推送 API	POST /v3/push/createPush	api.push.mob.com	推送消息 API
批量推送 API	POST /v3/push/createMulti	api.push.mob.com	批量推送消息 API
标签别名 API	GET/POST /device-v3	api.push.mob.com	操作 tag, alias

鉴权方式

MobPush REST API 采用统一的验证方式。基本做法为，在HTTP Header（头）里加 sign

sign：md5(请求参数+MobAppSecret)

鉴权举例

如您的AppKey为 2f2d7a68f8a40，AppSecret为 9abee316611dd24f607feb9f2c496338，请求参数为 {"source":"webapi","appkey":"2f2d7a68f8a40","pushTarget":{"target":1},"pushNotify":{"plats":[1],"content":"推送的内容","type":1}}，则调用 Push API 时：

sign计算为 eb276f35cf6480169b2d3e2e509db680：

sign = md5({"source":"webapi","appkey":"2f2d7a68f8a40","pushTarget":{"target":1},"pushNotify":{"plats":[1],"content":"推送的内容","type":1}}9abee316611dd24f607feb9f2c496338)

使用 curl 命令调用如下：

curl --location --request POST 'http://api.push.mob.com/v3/push/createPush' \
--header 'Content-Type: application/json' \
--header 'key: 2f2d7a68f8a40' \
--header 'sign: eb276f35cf6480169b2d3e2e509db680' \
--data-raw '{"source":"webapi","appkey":"2f2d7a68f8a40","pushTarget":{"target":1},"pushNotify":{"plats":[1],"content":"推送的内容","type":1}}'

公共请求头

在使用 API 时会使用到如下公共请求头（Request Header）

参数	类型	必须	说明
Content-Type	string	是	必要参数，固定值application/json
key	string	是	MobTech提供的AppKey
sign	string	是	鉴权参数，鉴权规则

API 频率控制

MobPush API 对访问次数，具有频率控制。即一定的时间窗口内，API 允许调用的次数是有限制的。

请注意:

API 频率有限制，不意味着对终端用户的推送数量与速度有控制。简单地说，一次 API 调用可以是广播，推送送达你应用的所有用户。

频率定义

一个时间窗口内，当前定义为：1 分钟。每个 AppKey 的 API 调用数量。

免费版本各 API 频率参考接口限制。

收费版本根据终端用户规模的不同，具有不同级别的频率。如有需要，请发邮件到 support@mob.com 以进一步沟通协调。

超出频率限制

当一个请求遇到频率限制时，MobPush API 返回的 HTTP 返回码为 400，其含义是：推送频率过快。 此时返回内容里，是如下的信息：

{
    "status": 4906,
    "res": null,
    "error": "广播推送频率过快-每5分钟只能推送一条广播任务"
}

类似的status码还有4902、4904、4908、4910、4912，这里不再一一举例。

频率优化建议

• 均匀地分布请求到各时间窗口。
• 根据 rid 大量请求时，避免无效的 rid。
• 如果大量针对 alias，rid 的请求内容一致，每次调用可以填写多个接收者。具体请参考推送 API 说明。

IP 白名单

工作台可以绑定发起 REST API 请求的 IP 地址，未绑定之前所有 IP 均可进行 REST API 的调用，绑定后仅绑定的 IP 才有调用权限，可根据需求自行决定是否绑定。

黑名单

如果某应用被认为是恶意推送，或者其 API 调用非法，其 AppKey 会被加入黑名单。 加入黑名单的 AppKey 的 API 调用，都会被直接拒绝，其返回码为 400（请求被拒绝）。返回内容格式为：

{
    "status": 4802,
    "res": null,
    "error": "App[xxx]被加入黑名单"
}

如果您的应用被加入黑名单，请发邮件到 support@mob.com 以进一步沟通协调。