Http Rest API 开发文档 V3.0

百度"云推送"提供了一整套涵盖 "推送"、"统计"、"组管理" 等能力的RestAPI接口，使开发者能在自己的服务端使用百度"云推送"服务。

请求与响应格式

关于如何发送HTTP请求与服务端交互并处理响应，请参见：SDK开发指南

API参考

推送消息到单台设备

[ POST ] /rest/3.0/push/single_device

功能

根据给定的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已正确保存，且厂商审核已通过。
long_conn_thirdlist string 否 由厂商id组成的json数组字符串，如 "[1,4,5]"。 强制走长连接下发的厂商list，即如果设备实际厂商在该list中，则走长连接下发。厂商id对应关系：0:华为，1:小米，3:魅族，4:oppo，5:vivo，9:荣耀。

返回值

名称 类型 固定返回 描述
msg_id string 是 该条消息id
send_time number 是 消息的实际推送时间

response json 示例

{
    "request_id":123456789, 
    "response_params":
    {
        "msg_id":24234532453245,
        "send_time":1427174155
    }
}

推送广播消息

[ POST ] /rest/3.0/push/all

功能

向当前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
    }
}

推送组播消息

[ POST ] /rest/3.0/push/tags

功能

推送消息或通知给指定的标签

参数

参数名 类型 必需 限制 描述
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
    }
}

推送消息到给定的一组设备(批量单播)

[ POST ] /rest/3.0/push/batch_device

功能

推送消息给批量设备（批量单播）

参数

参数名 类型 必需 限制 描述
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应用推送时使用
long_conn_thirdlist string 否 由厂商id组成的json数组字符串，如 "[1,4,5]"。 强制走长连接下发的厂商list，即如果设备实际厂商在该list中，则走长连接下发。厂商id对应关系：0:华为，1:小米，3:魅族，4:oppo，5:vivo，9:荣耀。

返回值

名称 类型 必选 描述
msg_id string 是 该条消息ID
send_time number 是 消息的实际推送时间

response json 示例

{
    "request_id":123456789, 
    "response_params":
    {
        "msg_id":"24234532453245",
        "send_time":12345678
    }
}

查询消息的发送状态

[ GET | POST ] /rest/3.0/report/query_msg_status

功能

根据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
        }]
    }
}

查询定时消息的发送记录

/rest/3.0/report/query_timer_records

功能

根据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
            },
            ......
        ]
    }
}

查询指定分类主题的发送记录

[ GET | POST ] /rest/3.0/report/query_topic_records

功能

根据分类主题获取消息推送记录

参数

参数名 类型 必需 限制 描述
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
            },
            …
        ]
    }
}

查询标签组列表

[ GET | POST ] /rest/3.0/app/query_tags

功能

查询应用的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
            }, 
            ...
        ]
    }
}

创建标签组

[ POST ] /rest/3.0/app/create_tag

功能

创建一个空的标签组

参数

参数名 类型 必需 限制 描述
tag string 是 1~128字节，但不能为‘default’ 标签名称

返回值

名称 类型 描述
tag string 标签名称
result number 状态 0：创建成功； 1：创建失败；

response json 示例

{
    "request_id":123456789,
    "response_params":{
        "tag":"tag_name",
        "result":0
    }
}

删除标签组

[ POST ] /rest/3.0/app/del_tag

功能

删除一个已存在的tag

参数

参数名 类型 必需 限制 描述
tag string 是 1~128字节，但不能为‘default’ 标签名称

返回值

名称 类型 描述
tag string 标签名称
result number 状态 0：创建成功； 1：创建失败；

response json 示例

{
    "request_id":123456789,
    "response_params":{
        "tag":"tag_name",
        "result":0
    }
}

添加设备到标签组

[ POST ] /rest/3.0/tag/add_devices

功能

向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
        }, 
        ...
        ]
    }
}

将设备从标签组中移除

[ POST ] /rest/3.0/tag/del_devices

功能

从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
        }, 
        ...
        ]
    }
}

查询标签组设备数量

[ GET | POST ] /rest/3.0/tag/device_num

功能

查询某个tag关联的设备数量

参数

参数名 类型 必需 限制 描述
tag string 是 1~128字节 标签名称

返回值

名称 类型 描述
device_num number 标签中设备的数量

response json 示例

{
    "request_id":123456789,
    "response_params":{
        "device_num":1000
    }
}

查询定时任务列表

[ GET | POST ] /rest/3.0/timer/query_list

功能

查看还未执行的定时任务，每个应用可设置的有效的定时任务有限制(目前为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
            }, 
            ...
        ]
    }
}

取消定时任务

[ POST ] /rest/3.0/timer/cancel

功能

取消尚未执行的定时推送任务

参数

参数名 类型 必需 限制 描述
timer_id string 是 只有未被执行并且距离实际执行时间一分钟以上的定时任务才能被取消 定时任务ID

返回值

void，如果未产生异常信息，则表示删除成功。

response json 示例

{
    "request_id":12394838223,
}

查询分类主题列表

[ GET | POST ] /rest/3.0/topic/query_list

功能

查询推送过程中使用过的分类主题列表

参数

参数名 类型 必需 限制 描述
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,
              },
              ...
          ]
       }
    }
}

当前应用的设备统计信息

[ GET | POST ] /rest/3.0/report/statistic_device

功能

统计APP 设备数

参数

无

返回值

名称 类型 描述
total_num number 统计结果集的条数
result mapObject result属性是一个map对象，其中：
key为统计信息所在当天0点0分时间戳；
value为包含以下内容：
  • new_term：当天新增用户数；
  • del_term：当天解绑用户数；
  • online_term：当天在线用户数；
  • addup_term：当天累计终端数；
  • total_term：有效channelId总数，等于addup_term 减去 del_term；
    		•

    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    
             },
             ...
          }
     }
};

    查询分类主题统计信息

    [ GET | POST ] /rest/3.0/report/statistic_topic

    功能

    统计当前应用下一个分类主题的消息数量

    注：支持单播、批量单播。

    参数

    名称 类型 必需 限制 描述
    topic_id string 是 字母、数字及下划线组成，长度限制为1~128 一个已使用过的分类主题

    返回值

    名称 类型 描述
    total_num number 所发的分类主题总数
    result mapObject result属性是一个map对象，其中：
    key为统计信息当天的0点0分的时间戳；
    value为包含以下内容：
  • ack：当天消息到达数
    		•

    response json 示例

    {
     "request_id" : 500335275,
     "response_params" : {
         "total_num" : 120,   
         "result" : {       
            "1429977600" : { 
            "ack" : 111  
         },
         ...
       }
    }
}
    ©2025 Baidu | 京ICP证030173号
    首页· 合作案例· 文档中心· 下载SDK· 创建应用