百度"云推送"提供了一整套涵盖 "推送"、"统计"、"组管理" 等能力的RestAPI接口,使开发者能在自己的服务端使用百度"云推送"服务。
关于如何发送HTTP请求与服务端交互并处理响应,请参见:SDK开发指南
功能
根据给定的channel_id推送消息给单个设备
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
channel_id | string | 是 | 必须为端上初始化channel成功之后返回的channel_id | 唯一对应一台设备 |
msg_type | number | 否 | 取值如下:0:消息;1:通知。默认为0 | 消息类型必须与extra_msg_type互斥其中一个是1另外一个是0 |
msg | string | 是 | 详情见消息/通知数据格式 | 消息内容,json格式 |
extra_msg_type | number | 否 | 取值如下:0:消息;1:通知。默认为0 | 消息类型必须与msg_type互斥其中一个是1另外一个是0 |
topic_id | string | 否 | 1-128个字符:数字,字母,下划线的组合 | 消息topic,可标识一批设备推送 |
extra_msg | string | 否 | 详情见消息/通知数据格式 | 消息内容,json格式 |
msg_expires | number | 否 | 0~604800(86400*7),默认为5小时(18000秒) | 相对于当前时间的消息过期时间,单位为秒 |
deploy_status | number | 否 | 取值为:1:开发状态;2:生产状态; 若不指定,则默认设置为生产状态。 | 设置iOS应用的部署状态,仅iOS应用推送时使用 |
channel_type | number | 否 | 取值如下:0:默认通道;1:私信通道。默认为0 | 该字段为1时推送小米、OPPO代理消息时会查询用户第三方绑定的信息,若用户在进行绑定时存储了im_channel(私信通道),消息下发时使用该通道,若查不到im_channel信息则使用默认通道下发。注意:确保im_channel已正确保存,且厂商审核已通过。 |
返回值
名称 | 类型 | 固定返回 | 描述 |
---|---|---|---|
msg_id | string | 是 | 该条消息id |
send_time | number | 是 | 消息的实际推送时间 |
response json 示例
{
"request_id":123456789,
"response_params":
{
"msg_id":24234532453245,
"send_time":1427174155
}
}
功能
向当前app下所有设备推送一条消息
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
msg_type | number | 否 | 取值如下:0:消息;1:通知。默认为0 | 消息类型必须与extra_msg_type互斥其中一个是1另外一个是0 |
msg | string | 是 | 详情见消息/通知数据格式 | 消息内容,json格式 |
extra_msg_type | number | 否 | 取值如下:0:消息;1:通知。默认为0 | 消息类型必须与msg_type互斥其中一个是1另外一个是0 |
extra_msg | string | 否 | 详情见消息/通知数据格式 | 消息内容,json格式 |
msg_expires | number | 否 | 0~604800(86400*7),默认为5小时(18000秒) | 消息过期时间,单位为秒 |
deploy_status | number | 否 | 取值为:1:开发状态;2:生产状态; 若不指定,则默认设置为生产状态。 | 设置iOS应用的部署状态,仅iOS应用推送时使用 |
send_time | number | 否 | 指定的实际发送时间,必须在当前时间60s以外,1年以内 | 定时推送,用于指定的实际发送时间 |
返回值
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
msg_id | string | 是 | 该条消息ID |
timer_id | string | 否 | 定时任务ID |
send_time | number | 是 | 消息的实际推送时间 |
response json 示例
{
"request_id":123456789,
"response_params":
{
"msg_id":"24234532453245",
"send_time":1428156644
}
}
功能
推送消息或通知给指定的标签
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
type | number | 是 | 目前固定值为 1 | 推送的标签类型 |
tag | string | 是 | 已创建的tag名称 | 标签名 |
msg_type | number | 否 | 取值如下:0:消息;1:通知。默认为0 | 消息类型必须与extra_msg_type互斥其中一个是1另外一个是0 |
msg | string | 是 | 详情见消息/通知数据格式 | 消息内容,json格式 |
extra_msg_type | number | 否 | 取值如下:0:消息;1:通知。默认为0 | 消息类型必须与msg_type互斥其中一个是1另外一个是0 |
extra_msg | string | 否 | 详情见消息/通知数据格式 | 消息内容,json格式 |
msg_expires | number | 否 | 0~604800(86400*7),默认为5小时(18000秒) | 消息过期时间,单位为秒 |
deploy_status | number | 否 | 取值为:1:开发状态;2:生产状态 若不指定,则默认设置为生产状态。 | 设置iOS应用的部署状态,仅iOS应用推送时使用 |
send_time | number | 否 | 指定的实际发送时间,必须在当前时间60s以外,1年以内 | 定时推送,用于指定的实际发送时间 |
返回值
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
msg_id | string | 是 | 该条消息ID |
timer_id | string | 否 | 定时任务ID |
send_time | number | 是 | 消息的实际推送时间 |
response json 示例
{
"request_id":123456789,
"response_params":
{
"msg_id":"24234532453245",
"send_time": 1428156644
}
}
功能
推送消息给批量设备(批量单播)
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
channel_ids | string | 是 | 一组channel_id(最多为一万个)组成的json数组字符串 | 对应一批设备 |
msg_type | number | 否 | 取值如下:0:消息;1:通知。默认为0 | 消息类型必须与extra_msg_type互斥其中一个是1另外一个是0 |
msg | string | 是 | 详情见消息/通知数据格式 | 消息内容,json格式 |
topic_id | string | 否 | 1-128个字符:数字,字母,下划线的组合 | 消息topic,可标识一批设备推送 |
extra_msg_type | number | 否 | 取值如下:0:消息;1:通知。默认为0 | 消息类型必须与msg_type互斥其中一个是1另外一个是0 |
extra_msg | string | 否 | 详情见消息/通知数据格式 | 消息内容,json格式 |
msg_expires | number | 否 | 1~86400,默认为1天(86400秒) | 消息过期时间,单位为秒 |
topic_id | string | 否 | 字母、数字及下划线组成,长度限制为1~128 | 分类主题名称 |
deploy_status | number | 否 | 取值为:1:开发状态;2:生产状态; 若不指定,则默认设置为生产状态。 | 设置iOS应用的部署状态,仅iOS应用推送时使用 |
返回值
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
msg_id | string | 是 | 该条消息ID |
send_time | number | 是 | 消息的实际推送时间 |
response json 示例
{
"request_id":123456789,
"response_params":
{
"msg_id":"24234532453245",
"send_time":12345678
}
}
功能
根据msg_id获取消息推送报告
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
msg_id | string | 是 | 推送接口返回的msg_id,支持一个由msg_id组成的json数组 | 消息ID |
返回值
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
total_num | number | 是 | 结果数量 |
result | JsonArray | 是 | result是数组对象,每项内容为一条消息的状态 |
result的元素中的每项内容包含以下字段:
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
msg_id | string | 是 | 该条消息ID |
status | number | 是 | 取值如下:0:已发送;1:未发送;2:正在发送;3:失败; |
success | number | 是 | 成功到达数 |
send_time | number | 是 | 消息的实际推送时间 |
response json 示例
{
"request_id":123456789,
"response_params":{
total_num:10,
result:[{
"msg_id":"24234532453245",
"status":0,
"success":10000,
"send_time":1472354868
}]
}
}
功能
根据timer_id获取消息推送记录
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
timer_id | string | 是 | 推送接口返回的timer_id | 定时任务ID |
start | number | 否 | 整数,默认为0 | 指定返回记录的起始索引位置 |
limit | number | 否 | 整数:[1,100],默认100 | 返回的记录条数 |
range_start | number | 否 | 指定查询起始时间范围,以服务端实际推送时间为准;默认为七天前的0点时间 | unix时间戳 |
range_end | number | 否 | 指定查询截止时间范围,以服务端实际推送时间为准;默认时间为当前时间 | unix时间戳 |
返回值
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
timer_id | string | 是 | 定时任务ID |
result | JsonArray | 是 | result是数组对象,每项内容为该定时任务所产生的一条消息的状态 |
result的元素中的每项内容包含以下字段:
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
msg_id | string | 是 | 消息ID |
status | number | 是 | 取值如下:0:已发送;1:未发送;2:正在发送;3:失败; |
send_time | number | 是 | 消息的实际推送时间 |
response json 示例
{
"request_id":123456789,
"response_params":
{
"timer_id":1011,
"result":[
{
"msg_id":"24234532453245",
"status":0,
"send_time":147456789
},
......
]
}
}
功能
根据分类主题获取消息推送记录
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
topic_id | string | 是 | 字母、数字及下划线组成,长度限制为1~128 | 分类主题名称 |
start | number | 否 | 整数,默认为0 | 返回记录的索引位置 |
limit | number | 否 | 整数:[1,100],默认100 | 返回的记录条数 |
range_start | number | 否 | 指定查询起始时间范围,以服务端实际推送时间为准;默认为七天前的0点时间 | unix时间戳 |
range_end | number | 否 | 指定查询截止时间范围,以服务端实际推送时间为准;默认时间为当前时间 | unix时间戳 |
返回值
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
topic_id | string | 是 | 消息发送时指定的分类主题 |
result | JsonArray | 是 | result是一个数组对象,每项内容为该分类主题下的一条消息的相关信息 |
result的元素包含以下字段:
名称 | 类型 | 必选 | 描述 |
---|---|---|---|
msg_id | string | 是 | 消息id |
status | number | 是 | 取值如下:0:已发送;1:未发送;2:正在发送;3:失败; |
send_time | number | 是 | 消息实际推送时间 |
response json 示例
{
"request_id":123456789,
"response_params":
{
"topic_id":"1011",
"result":[
{
"msg_id":"24234532453245",
"status":0,
"send_time":147456789
},
…
]
}
}
功能
查询应用的tag
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
tag | string | 否 | 1-128字节,不传则获取应用下所有标签信息 | 标签名称 |
start | number | 否 | 整数,默认为0 | 指定返回记录的起始索引位置 |
limit | number | 否 | 整数:[1,100],默认100 | 返回的记录条数 |
返回值
名称 | 类型 | 描述 |
---|---|---|
total_num | number | Tag总数 |
result | JsonArray | result内容是一个数组对象,每项内容表示一个Tag的详细信息 |
result的元素包含以下字段:
名称 | 类型 | 描述 |
---|---|---|
tid | number | 标签ID |
tag | string | 标签名 |
info | string | 用于进一步描述标签的附件信息 |
type | number | 标签类型(已废弃,请勿依赖该字段进行开发) |
createtime | number | 标签创建时间,unix时间戳 |
Response json 示例
{
"request_id":123456789,
"response_params":{
"total_num":100,
"tags":[
{
"tid":1000,
"tag":"tag1",
"info":"tag1",
"type":0,
"createtime":140233424
},
...
]
}
}
功能
创建一个空的标签组
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
tag | string | 是 | 1~128字节,但不能为‘default’ | 标签名称 |
返回值
名称 | 类型 | 描述 |
---|---|---|
tag | string | 标签名称 |
result | number | 状态 0:创建成功; 1:创建失败; |
response json 示例
{
"request_id":123456789,
"response_params":{
"tag":"tag_name",
"result":0
}
}
功能
删除一个已存在的tag
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
tag | string | 是 | 1~128字节,但不能为‘default’ | 标签名称 |
返回值
名称 | 类型 | 描述 |
---|---|---|
tag | string | 标签名称 |
result | number | 状态 0:创建成功; 1:创建失败; |
response json 示例
{
"request_id":123456789,
"response_params":{
"tag":"tag_name",
"result":0
}
}
功能
向tag中批量添加设备
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
tag | string | 是 | 1~128字节,但不能为‘default’ | 标签名称 |
channel_ids | string | 是 | 一组channel_id(最少1个,最多为10个)组成的json数组字符串 | 对应一批设备 |
返回值
名称 | 类型 | 描述 |
---|---|---|
devices | Array | 每个元素表示对应的一个channel_id是否删除成功 |
devices中每个元素包含以下内容
名称 | 类型 | 描述 |
---|---|---|
channel_id | string | 设备ID |
result | number | 状态 0:添加成功; 1:添加失败; |
response json 示例
{
"request_id":123456789,
"response_params":{
"devices":[
{
"channel_id":"43848320940932",
"result":0
},
{
"channel_id":"48302948302432043",
"result":1
},
...
]
}
}
功能
从tag中批量解绑设备
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
tag | string | 是 | 1~128字节,但不能为‘default’ | 标签名称 |
channel_ids | string | 是 | 一组channel_id(最多为10个)组成的json数组字符串 | 对应一批设备 |
返回值
名称 | 类型 | 描述 |
---|---|---|
devices | Array | 每个元素表示对应的一个channel_id是否添加成功 |
devices中每个元素包含以下内容
名称 | 类型 | 描述 |
---|---|---|
channel_id | string | 设备ID |
result | number | 状态 0:删除成功;1:删除失败; |
response json 示例
{
"request_id":123456789,
"response_params":{
"devices":[
{
"channel_id":"43848320940932",
"result":0
},
{
"channel_id":"48302948302432043",
"result":1
},
...
]
}
}
功能
查询某个tag关联的设备数量
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
tag | string | 是 | 1~128字节 | 标签名称 |
返回值
名称 | 类型 | 描述 |
---|---|---|
device_num | number | 标签中设备的数量 |
response json 示例
{
"request_id":123456789,
"response_params":{
"device_num":1000
}
}
功能
查看还未执行的定时任务,每个应用可设置的有效的定时任务有限制(目前为10个)。
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
timer_id | string | 否 | 推送接口返回的timer_id唯一标识一个定时推送任务 | 如果指定该参数,将仅返回该timer_id对应定时任务的相关信息 |
start | number | 否 | 整数,默认为0 | 指定返回记录的起始索引位置 |
limit | number | 否 | 整数:[1,10],默认10 | 返回的记录条数 |
返回值
名称 | 类型 | 描述 |
---|---|---|
total_num | number | 定时推送任务的总数量 |
result | JsonArray | result是数组对象,每项表示一个定时任务的相关信息 |
result中每个对象包含以下内容:
名称 | 类型 | 描述 |
---|---|---|
timer_id | string | 发送定时消息时返回的timer_id |
msg | string | 发送消息的内容 |
send_time | number | 消息的实际推送时间 |
msg_type | number | 消息类型:0:透传消息;1:通知;2:带格式的消息;3:富媒体消息; |
range_type | number | 消息发送范围: 0:tag组播;1:广播;2:批量单播;3:标签组合;4:精准推送;5:LBS推送;6:系统保留;7:单播; |
response json 示例
{
"request_id":123456789,
"response_params":{
"total_num":10,
"result":[
{
"timer_id":1000,
"msg":"message body",
"msg_type":0,
"range_type":2,
"send_time":147456789
},
...
]
}
}
功能
取消尚未执行的定时推送任务
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
timer_id | string | 是 | 只有未被执行并且距离实际执行时间一分钟以上的定时任务才能被取消 | 定时任务ID |
返回值
void,如果未产生异常信息,则表示删除成功。
response json 示例
{
"request_id":12394838223,
}
功能
查询推送过程中使用过的分类主题列表
参数
参数名 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
start | number | 否 | 整数,默认为0 | 指定返回记录的起始索引位置 |
limit | number | 否 | 整数:[1,20],默认20 | 返回的记录条数 |
返回值
名称 | 类型 | 描述 |
---|---|---|
total_num | number | 所使用过的分类主题总数 |
result | JsonArray | result属性是一个json数组,数组中每项内容表示一个分类主题的相关信息 |
result中每个对象包含以下内容:
名称 | 类型 | 描述 |
---|---|---|
ack_cnt | number | 总的到达数,-1代表数据未ready |
ctime | number | 第一次发送时间 |
mtime | number | 最后一次发送时间 |
push_cnt | number | 总的推送目标数 |
topic_id | string | 分类主题名称 |
Response json 示例
{
"request_id":123456789,
"response_params":{
"total_num":10,
"topics":[
{
"topic_id":"1000",
"ctime":1421247101,
"mtime":1421247101,
"push_cnt":2000,
"ack_cnt":1000,
},
...
]
}
}
}
功能
统计APP 设备数
参数
无
返回值
名称 | 类型 | 描述 |
---|---|---|
total_num | number | 统计结果集的条数 |
result | mapObject | result属性是一个map对象,其中: key为统计信息所在当天0点0分时间戳; value为包含以下内容: |
response json 示例
{
"request_id" : 500348335,
"response_params" : {
"total_num" : 180,
"result" : {
"1429977600" : {
"new_term" : 2,
"del_term" : 115,
"online_term" : 178,
"addup_term" : 103,
"total_term" : 193
},
...
}
}
};
功能
统计当前应用下一个分类主题的消息数量
注:支持单播、批量单播。
参数
名称 | 类型 | 必需 | 限制 | 描述 |
---|---|---|---|---|
topic_id | string | 是 | 字母、数字及下划线组成,长度限制为1~128 | 一个已使用过的分类主题 |
返回值
名称 | 类型 | 描述 |
---|---|---|
total_num | number | 所发的分类主题总数 |
result | mapObject | result属性是一个map对象,其中: key为统计信息当天的0点0分的时间戳; value为包含以下内容: |
response json 示例
{
"request_id" : 500335275,
"response_params" : {
"total_num" : 120,
"result" : {
"1429977600" : {
"ack" : 111
},
...
}
}
}