Rest API 使用指南

协议描述


请求URL结构为:

http://接口域名/v2/class/method?params


字段名
用途
备注
接口域名   
接口域名
统一使用openapi.xg.qq.com
v2
表示当前api的版本号
class
提供的接口类别
method
每个接口大类提供的具体操作接口
如查询、设置、删除等
params
以GET方式调用接口时传递的参数
包括通用参数和api相关特定参数。所有的参数都必须为utf8编码,params字符串应进行url encode

注:以POST方式调用接口时,参数应以POST参数形式传递,内容要求同params字段。HTTP HEADER中“Content-type”字段要设置为“application/x-www-form-urlencoded


通用参数


各接口url结构的params字段有共同参数


参数名 类型 是否必要 参数描述
access_id
uint
应用的唯一标识符,在提交应用时管理系统返回。可在xg.qq.com管理台查看
timestamp
uint

本请求的unix时间戳,用于确认请求的有效期默认情况下,请求时间戳与服务器时间(北京时间)偏差大于600秒则会被拒绝

valid_time
uint

配合timestamp确定请求的有效期,单位为秒,最大值为600。若不设置此参数或参数值非法,则按默认值600秒计算有效期

sign
string 内容签名


备注:内容签名生成规则:


A)提取请求方法method(GET或POST);

B)提取请求url信息,包括Host字段的IP或域名和URI的path部分,注意不包括Host的端口和Path的querystring。请在请求中带上Host字段,否则将视为无效请求。比如openapi.xg.qq.com/v2/push/single_device或者10.198.18.239/v2/push/single_device;

C)将请求参数(不包括sign参数)格式化成K=V方式,注意:计算sign时所有参数不应进行urlencode;

D)将格式化后的参数以K的字典序升序排列,拼接在一起,注意字典序中大写字母在前;

E)拼接请求方法、url、排序后格式化的字符串以及应用的secret_key;

F)将E形成字符串计算MD5值,形成一个32位的十六进制(字母小写)字符串,即为本次请求sign(签名)的值;

Sign=MD5($http_method$url$k1=$v1$k2=$v2$secret_key); 该签名值基本可以保证请求是合法者发送且参数没有被修改,但无法保证不被偷窥。


例如: POST请求到接口http://openapi.xg.qq.com/v2/push/single_device,有四个参数,access_id=123,timestamp=1386691200,Param1=Value1,Param2=Value2,secret_key为abcde。

则上述E步骤拼接出的字符串为POSTopenapi.xg.qq.com/v2/push/single_deviceParam1=Value1Param2=Value2access_id=123timestamp=1386691200abcde,注意字典序中大写在前。

计算出该字符串的MD5为ccafecaef6be07493cfe75ebc43b7d53,以此作为sign参数的值



通用返回结果


示例


{
   “ret_code”:0,
   “err_msg”:”ok”,
   “result”:{“status”:0}
}



字段定义如下

参数名 类型 是否必要 描述
ret_code
int

返回码
err_msg
string
请求出错时的错误信息
result
json

请求正确时,若有额外数据要返回

,则结果封装在该字段的json中。若无额外数据,则可能无此字段

特别注意:

1)参数和值都是大小写敏感,如没有特别注明,都是小写

2)所有的K和V须urlencode,避免里面有“&”或“=”之类字符影响解析


通用返回码


描述如下


含义
可采取措施
0
调用成功

-1 参数错误
检查参数配置
-2 请求时间戳不在有效期内
检查设备当前时间
-3 sign校验无效
检查Access ID和Secret Key(注意不是Access Key)
2 参数错误
检查参数配置
14 收到非法token,例如iOS终端没能拿到正确的token

Android Token长度为40位

iOS Token长度为64位

15 信鸽逻辑服务器繁忙
稍后重试
19 操作时序错误。例如进行tag操作前未获取到deviceToken

没有获取到deviceToken的原因:

1.没有注册信鸽或者苹果推送

2.provisioning profile制作不正确

20 鉴权错误,可能是由于Access ID和Access Key不匹配
检查Access ID和Access Key
40 推送的token没有在信鸽中注册

检查token是否注册

48 推送的账号没有绑定token

检查account和token是否有绑定关系

见推送指南:绑定/设置账号

见热门问题解答:账号和设备未绑定的解答

63 标签系统忙

检查标签是否设置成功

见推送指南:设置标签

71 APNS服务器繁忙
苹果服务器繁忙,稍后重试
73 消息字符数超限
iOS目前是1000字节左右,苹果的额外推送设置如角标,也会占用字节数
76 请求过于频繁,请稍后再试
全量广播限频为每3秒一次
78 循环任务参数错误

100 APNS证书错误。请重新提交正确的证书
证书格式是pem的,另外,注意区分生产证书、开发证书的区别
其他 其他错误


推送Android平台


message参数值应为如下所述的json字符串,其总长度不能超过4096字节。

推送通知定义示例(默认展示在手机或设备通知栏)


{"content":"this is content","title":"this is title", "vibrate":1}


完整定义


{
"title ":"xxx", // 标题,必填
"content ":"xxxxxxxxx",  // 内容,必填
"accept_time": //表示消息将在哪些时间段允许推送给用户,选填
[
{
“start”:{“hour”:”13”,“min”:”00”},
 ”end”: {“hour”:”14”,“min”:”00”} 
},
{
“start”:{“hour”:”00”,”min”:”00”},
 ”end”: {“hour”:”09”,“min”:”00”} 
}
],

"n_id":0, //通知id,选填。若大于0,则会覆盖先前弹出的相同id通知;若为0,展示本条通知且不影响其他通知;若为-1,将清除先前弹出的所有通知,仅展示本条通知。默认为0
"builder_id":0,  // 本地通知样式,必填
"ring":1,	// 是否响铃,0否,1是,下同。选填,默认1
"ring_raw":"ring",	// 指定应用内的声音(ring.mp3),选填
"vibrate":1, // 是否振动,选填,默认1
"lights":1// 是否呼吸灯,0否,1是,选填,默认1
"clearable":1,  // 通知栏是否可清除,选填,默认1
"icon_type":0 //默认0,通知栏图标是应用内图标还是上传图标,0是应用内图标,1是上传图标,选填
"icon_res":"xg",// 应用内图标文件名(xg.png)或者下载图标的url地址,选填
"style_id":1 //Web端设置是否覆盖编号的通知样式,默认1,0否,1是,选填
"small_icon":"xg"指定状态栏的小图片(xg.png),选填
"action":{ // 动作,选填。默认为打开app
        "action_type  ": 1, // 动作类型,1打开activity或app本身,2打开浏览器,3打开Intent
		"activity ": "xxx"
		"aty_attr ": // activity属性,只针对action_type=1的情况
			{
			 "if":0,   // 创建通知时,intent的属性,如:intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED);
			 "pf":0,   // PendingIntent的属性,如:PendingIntent.FLAG_UPDATE_CURRENT
			}   
        "browser": {"url": "xxxx ","confirm": 1},  // url:打开的url,confirm是否需要用户确认        
        “intent”: “xxx”
 
      },
  

"custom_content":{ // 用户自定义的key-value,选填
        "key1": "value1",
        "key2": "value2"
      }
}


透传消息定义示例(可以由app识别的任意透传消息命令,比推送通知更灵活


{"content":"this is content","title":"this is title"}


完整定义


{
"title":"xxx", // 标题,选填
"content ":"xxxxxxxxx",  // 内容,选填
"accept_time": //表示消息将在哪些时间段允许推送给用户,选填
[
{
“start”:{“hour”:”13”,“min”:”00”},
 ”end”: {“hour”:”14”,“min”:”00”} 
},
{
“start”:{“hour”:”00”,”min”:”00”},
 ”end”: {“hour”:”09”,“min”:”00”} 
}
],

"custom_content":{ // 用户自定义的key-value,选填
        "key1": "value1",
        "key2": "value2"
      }
}

推送iOS平台


message参数应为APNS规定的payload(也是一个json字符串),详细定义参考APNS官方手册。

信鸽在其基础上仅增添了两保留字段xg和accept_time。payload不能超过256字节。需要注意的是accept_time字段不会传递给APNS,因此不占用payload容量。


示例


{"aps":{"alert":"gogogo"}}


复杂示例


{
    "aps" : {   //  apns规定的key-value
        "alert" : {
            "body" : "Bob wants to play poker",
            "action-loc-key" : "PLAY"
        },
        "badge" : 5,
        “category” : “INVITE_CATEGORY”,
},
"accept_time":[ //允许推送给用户的时段,选填。accept_time不会占用payload容量
{
"start":{"hour":"13","min":"00"},
        "end": {"hour":"14","min":"00"} 
},
{
"start":{"hour":"00","min":"00"},
         "end": {"hour":"09","min":"00"} 
}
] // 仅0~9点和13~14点这两个时段可推送
    "custom1" : "bar",   // 合法的自定义key-value,会传递给app
"custom2" : [ "bang",  "whiz" ],  // 合法的自定义key-value,会传递给app
"xg" : "oops"  // 错误!xg为信鸽系统保留key,其value会被信鸽系统覆盖,应避免使用
}



推送接口


单个设备

url路径

http://接口域名/v2/push/single_device?params



请求参数:除了通用参数外,还包括如下参数


参数说明

参数名 类型 必需 默认值 描述
device_token
string


针对某一设备推送,token是设备的唯一识别 ID
message_type
uint


消息类型:1:通知 2:透传消息。iOS平台请填0
message
string


参见1.4、1.5两节
expire_time
uint
3天 消息离线存储时间(单位为秒),最长存储时间3天。若设置为0,则使用默认值(3天)
send_time
string
立即 指定推送时间,格式为year-mon-day hour:min:sec 若小于服务器当前时间,则会立即推送
multi_pkg
uint
0 0表示按注册时提供的包名分发消息;1表示按access id分发消息,所有以该access id成功注册推送的app均可收到消息。本字段对iOS平台无效
environment
uint
仅iOS必需
向iOS设备推送时必填,1表示推送生产环境;2表示推送开发环境。推送Android平台不填或填0


响应结果:在通用返回结果参数中,result字段的json为空。

返回:本接口不返回push id



批量设备



  • 首先,需要创建批量消息



url路径


http://接口域名/v2/push/create_multipush?params



请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
message_type
uint


消息类型:1:通知 2:透传消息
message
string


参见1.4、1.5两节
expire_time
uint
3天

消息离线存储时间(单位为秒),最长存储时间3天。若设置为0,则使用默认值(3天)。

在超时时间内,可以发起此消息的批量推送。

multi_pkg
uint

0表示按注册时提供的包名分发消息;1表示按access id分发消息,所有以该access id成功注册推送的app均可收到消息
environment
uint
仅iOS必需

向iOS设备推送时必填,1表示推送生产环境;2表示推送开发环境。推送Android平台不填或填0


响应结果:在通用返回结果参数中,result字段的json如下


{
   “push_id”:string (表示给app下发的任务id)
}




  • 其次,按照已创建的批量推送消息推送给多个设备



url路径

http://接口域名/v2/push/device_list_multiple?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
device_list
string

Json数组格式,每个元素是一个token,string类型,单次发送token不超过1000个

例:[“token1”,”token2”,”token3”]

push_id
uint

创建批量推送消息 接口的返回值中的 push_id


响应结果:在通用返回结果参数中,result字段的json为空



全量设备


后台对本接口的调用频率有限制,两次调用之间的时间间隔不能小于3秒


url路径


http://接口域名/v2/push/all_device?params



请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
message_type
uint

消息类型:1:通知 2:透传消息。iOS平台请填0
message
string

参见1.4、1.5两节
expire_time
uint

3天 消息离线存储时间(单位为秒),最长存储时间3天。若设置为0,则使用默认值(3天)
send_time
string

立即 指定推送时间,格式为year-mon-day hour:min:sec 若小于服务器当前时间,则会立即推送
multi_pkg
uint

0 0表示按注册时提供的包名分发消息;1表示按access id分发消息,所有以该access id成功注册推送的app均可收到消息。本字段对iOS平台无效
environment
uint
仅iOS必需

向iOS设备推送时必填,1表示推送生产环境;2表示推送开发环境。推送Android平台不填或填0
loop_times
uint


循环任务执行的次数,取值[1, 15]
loop_interval
uint


循环任务的执行间隔,以天为单位,取值[1, 14]。loop_times和loop_interval一起表示任务的生命周期,不可超过14天

响应结果:在通用返回结果参数中,result字段的json示例如下

{
   “push_id”:string (表示给app下发的任务id,如果是循环任务,返回的是循环父任务id)
}



标签


可以针对设置过标签的设备进行推送。如:女、大学生、低消费等任意类型标签。


标签推送url路径


http://接口域名/v2/push/tags_device?params


请求参数:除了通用参数外,还包括如下参数

参数名
类型 必需 默认值 描述
message
string

参见1.4、1.5两节
message_type
uint
1 消息类型:1:通知 2:透传消息。iOS平台请填0
tags_list
json

[“tag1”,”tag2”,”tag3”]
tags_op
string

取值为AND或OR
expire_time
uint
3天
消息离线存储时间(单位为秒),最长存储时间3天。若设置为0,则使用默认值(3天)
send_time
string

立即
指定推送时间,格式为year-mon-day hour:min:sec 若小于服务器当前时间,则会立即推送
multi_pkg
uint

0 0表示按注册时提供的包名分发消息;1表示按access id分发消息,所有以该access id成功注册推送的app均可收到消息。本字段对iOS平台无效
environment
uint
仅iOS必需

向iOS设备推送时必填,1表示推送生产环境;2表示推送开发环境。推送Android平台不填或填0
loop_times
uint


循环任务执行的次数,取值[1, 15]
loop_interval
uint


循环任务的执行间隔,以天为单位,取值[1, 14]。loop_times和loop_interval一起表示任务的生命周期,不可超过14天

响应结果:在通用返回结果参数中,result字段的json示例如下


{
   “push_id”:string (表示给app下发的任务id,如果是循环任务,返回的是循环父任务id)
}





单个帐号


设备的账户或别名由终端SDK在调用推送注册接口时设置,详情参考终端SDK文档。


url路径


http://接口域名/v2/push/single_account?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
account
string


针对某一账号推送,帐号可以是qq号,邮箱号,openid,手机号等各种类型
message_type
uint

1 消息类型:1:通知 2:透传消息
message
string


参见1.4、1.5两节
expire_time
uint

3天 消息离线存储时间(单位为秒),最长存储时间3天。若设置为0,则使用默认值(3天)
send_time
string

立即 指定推送时间,格式为year-mon-day hour:min:sec 若小于服务器当前时间,则会立即推送
multi_pkg
uint

0 0表示按注册时提供的包名分发消息;1表示按access id分发消息,所有以该access id成功注册推送的app均可收到消息
environment
uint
仅iOS必需

向iOS设备推送时必填,1表示推送生产环境;2表示推送开发环境。推送Android平台不填或填0

响应结果:在通用返回结果参数中,result字段的json为空。本接口不返回push id




批量帐号


设备的账户或别名由终端SDK在调用推送注册接口时设置,详情参考终端SDK文档。


url路径

http://接口域名/v2/push/account_list?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
account_list
string


Json数组格式,每个元素是一个account,string类型,单次发送account不超过100个。例:[“account1”,”account2”,”account3”]
message_type
uint


消息类型:1:通知 2:透传消息
message
string


参见1.4、1.5两节
expire_time
uint
3天
消息离线存储时间(单位为秒),最长存储时间3天。若设置为0,则使用默认值(3天)
multi_pkg
uint
0 0表示按注册时提供的包名分发消息;1表示按access id分发消息,所有以该access id成功注册推送的app均可收到消息
environment
uint
仅iOS必需

向iOS设备推送时必填,1表示推送生产环境;2表示推送开发环境。推送Android平台不填或填0

响应结果:在通用返回结果参数中,result字段的json为每个account发送返回码。本接口不返回push id


注:

如果推送目标帐号数量很大(比如≥10000),推荐使用account_list_multiple接口,用户请自行比较异同


首先,(如同推送批量设备需要创建批量消息:


url路径


http://接口域名/v2/push/create_multipush?params


请求参数:除了通用参数外,还包括如下参数

参数 类型 必需 默认值 参数描述
message_type
uint


消息类型:1:通知 2:透传消息
message
string


参见1.4、1.5两节
expire_time
uint

消息离线存储多久,单位为秒,最长存储时间3天。在超时时间内,可以发起此消息的批量推送
multi_pkg
uint

0表示按注册时提供的包名分发消息;1表示按access id分发消息,所有以该access id成功注册推送的app均可收到消息
environment
uint
仅iOS必需

向iOS设备推送时必填,1表示推送生产环境;2表示推送开发环境。推送Android平台不填或填0

其次,选择推送批量帐号:

url路径

http://接口域名/v2/push/account_list_multiple?params


请求参数:除了通用参数外,还包括如下参数

参数 类型 必需 默认值 描述
account_list
string


Json数组格式,每个元素是一个account,string类型,单次发送account不超过1000个。例:[“account1”,”account2”,”account3”]
push_id
uint


创建批量推送消息 接口的返回值中的 push_id

响应结果:在通用返回结果参数中,result字段的json为空


标签设置/删除接口


  • 批量设置标签

url路径

http://接口域名/v2/tags/batch_set


请求参数:除了通用参数外,还包括如下参数

参数 类型 必需 默认值 描述
tag_token_list
string
json字符串,包含若干标签-token对,后台将把每一对里面的token打上对应的标签。每次调用最多允许设置20对,每个对里面标签在前,token在后。注意标签最长50字节,不可包含空格;真实token长度至少40字节。示例(其中token值仅为示意): [[”tag1”,”token1”],[”tag2”,”token2”]]

响应结果:在通用返回结果参数中,result字段的json为空



  • 批量删除标签


url路径

http://接口域名/v2/tags/batch_del


请求参数:除了通用参数外,还包括如下参数

参数 类型 必需 默认值 描述
tag_token_list
string
json字符串,包含若干标签-token对,后台将为每一对里面的token删除对应的标签。每次调用最多允许设置20对,每个对里面标签在前,token在后。注意标签最长50字节,不可包含空格;真实token长度至少40字节。示例如下(其中token值仅为示意): [[”tag1”,”token1”],[”tag2”,”token2”]]

响应结果:在通用返回结果参数中,result字段的json为空



账号映射删除接口



单清

删除应用中某个account映射的某个token

url路径

http://接口域名/v2/application/del_app_account_tokens?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 参数描述
account string 账号,可以是邮箱号、手机号、QQ号等任意形式的业务帐号
device_token
string
token,设备的唯一识别ID

响应结果:在通用返回结果参数中,result字段的json如下


{
     “tokens”:[“token1”,”token2”]
}
即显示删除device_token后该account映射的剩余token



全清

删除应用中某account映射的所有token

url路径


http://接口域名/v2/application/del_app_account_all_tokens?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 参数描述
account string 账号

响应结果:在通用返回结果参数中,result字段的json为空





查询接口



查询消息/设备/帐号


1. 查询群发消息发送状态

url路径

http://接口域名/v2/push/get_msg_status?params


请求参数:除了通用参数外,还包括如下参数

参数 类型 必需 默认值 描述
push_id
json


[

{“push_id”: string}, {“push_id”:“xxxx”},

]


响应结果:在通用返回结果参数中,result字段的json形式为:

{
   “list”: [
     {
         “push_id”: “27ABC5486977”
         “status”: 0(未处理)/1(推送中)/2(推送完成)/3(推送失败)
         “start_time”:”year-mon-day hour:min:sec“
         “finished”:xxxx  (已发送)
         “total”:xxxxx   (共需要发送)
       },
   ] 
}


2. 查询应用覆盖的设备(token总数

url路径

http://接口域名/v2/application/get_app_device_num?params


请求参数:本接口仅包括公共参数

响应结果:在通用返回结果参数中,result字段的json形式为:


{
   “device_num”: 34567(设备数)
}


若请求应用列表中某个应用信息非法,则不会在result中返回结果



3. 查询应用的某个token的信息(查看是否有效

url路径

http://接口域名/v2/application/get_app_token_info?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
device_token
string

响应结果:在通用返回结果参数中,result字段的json如下:

{
"isReg":1,(1为token已注册,0为未注册)
"connTimestamp":1426493097, (最新活跃时间戳)
"msgsNum":2(该应用的离线消息数)
}


4. 查询应用某帐号映射的token(查看帐号-token对应关系

url路径

http://接口域名/v2/application/get_app_account_tokens?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
account
string
帐号

响应结果:在通用返回结果参数中,result字段的json如下

{
     “tokens”:[“token1”,”token2”]
}



查询标签



1. 查询应用设置的标签

url路径

http://接口域名/v2/tags/query_app_tags?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
start
uint

0 开始值
limit
uint

100 限制数量

响应结果:在通用返回结果参数中,result字段的json格式如下

{
   “total”: 2, //应用的tag总数,注意不是本次查询返回的tag数
   “tags”:[“tag1”,”tag2”]
}


2. 查询应用的某个设备上设置的标签

url路径

http://接口域名/v2/tags/query_token_tags?params


请求参数:除了通用参数外,还包括如下参数

参数 类型 必需 默认值 描述
device_token
string

响应结果:在通用返回结果参数中,result字段的json格式如下

{
     “tags”:[“tag1”,”tag2”]
}


3. 查询应用某个标签下关联的设备数

url路径

http://接口域名/v2/tags/ query_tag_token_num?params


请求参数:除了通用参数外,还包括如下参数

参数 类型 必需 默认值 描述
tag
string

响应结果:在通用返回结果参数中,result字段的json格式如下

{
     “device_num”:589874
}



查询SDK版本号



接口定义:查询app内信鸽的SDK版本。该接口为终端接口。


Android:

com.tencent.android.tpush.common.Constants.PUSH_SDK_VERSION


iOS:

XGSetting.h里面的XG_SDK_VERSION宏



任务删除/取消接口


1. 删除群发推送任务的离线消息


后悔药,针对有任务ID(push ID),并且已发送任务可以删除离线消息


url路径

http://接口域名/v2/push/delete_offline_msg?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
push_id
string
待删除离线消息的任务ID

响应结果:在通用返回结果参数中,result字段的json为空


2. 取消尚未触发的定时群发任务

后悔药,针对尚未发送的任务,需要任务ID


url路径


http://接口域名/v2/push/cancel_timing_task?params


请求参数:除了通用参数外,还包括如下参数

参数名 类型 必需 默认值 描述
push_id
string
要取消的任务ID
响应结果:在通用返回结果参数中,result字段的json格式如下


{
   “status”: 0, //0为成功,其余为失败
}





目录

回到顶部