淘宝开放平台-消息通知机制-主动通知业务详解

二、请求参数
m 名称 o app_ .c key
user
是 否必需
Y
N
bao time
Y
Hale Waihona Puke Baidu
o stamp
.ta id
N
sign
Y
描述
TOP 分配给应用的 key
用户 id（即 user_id，这里要和 nick 区分开来） 1、如果不传 user，app 所有用户的消息都会发送到一个连接通道上。 2、如果传了 user，只有这个 user 的消息会发送到这个通道上，其他用户的消息都不会推送给 app 。 3、如果 app 提供的是 saas 类型的服务，最好不要传 user，这样可以节约服务器资源，系统编写设计上 也非常简单。 4、如果是为每一个商家单独部署的 app，则可以传递 user 参数，这样只有商家自己的数据才会推送。 时间戳，格式为 yyyy-MM-dd HH:mm:ss，例如：2008-01-25 20:23:30。淘宝 API 服务端允许客户端请求时 间误差为10分钟。 请求的连接标识，多连接时使用，详情请参考本节 七、多连接支持 对请求的所有输入参数进行签名结的果，具体签名方式参考这里。
m 下一节 主动通知-发起请求 o 一、APP（应用）订阅主动通知 .c 1、访问 http://open.taobao.com/index.htm ，登录后，选择应用（APP）进入主动通知管理页面，如下图所示： o 2、点击“确认试用”，进入下图 a 1) 开发者根据自己的需求，选择需要的消息类型以及消息状态。 b 2) 如果勾选上沙箱设置，在沙箱环境下也可以接收主动通知消息，而不需要在沙箱环境重新设计，方便沙箱测试。 .tao 二、授权接收指定用户
2）实现方式 （1）同步订单不再纠结
消息推送模式出现以前，同步订单主要通过增量 API 进行增量消息捕捉，然后进行订单同步，会有两个问题：A、大促期间如双 十一瞬间消息增量过多，增量 API 时间片切的再小，仍然不能有效获取增量信息；B、增量 API 如果时间片选择较小会导致 API 调用量过 高，时间片选择过大，会导致数据延迟，达不到数据实时同步的目的。使用主动推送后，不在需要为了实时的获取到数据而频繁的调用 api， 当有消息产生以后应用程序会立刻收到这个数据。
1）应用程序接受用户的请求。 2）应用程序发起一个或者多个 REST API 的请求，得到 API 的响应结果，连接断开。 3）应用程序对结果做一些处理，把结果展示给用户。
2、主动通知方式
om 三、主动通知价值 .c 1、实时：每次数据的变化基本都在毫秒内返回给应用程序。
2、提升用户体验：开发者可以基于数据的实时性到达，满足用户对数据苛刻的实时展示需求，而且可以提供一些更加人性化的实时
在完成第一步后还不能接收到任何用户的消息数据，因为数据属于用户，必须获得用户（卖家）的授权允许才能接收用户的数据。所 以首先要获取卖家授权即取得 sessionkey ，再调用 taobao.increment.customer.permit 授权获取指定用户的消息。
在 APP 运行的过程中，如果 APP 不再需要接收某个用户的消息，可以调用 taobao.increment.customer.stop 取消 。也可以调用
业务逻辑处理，建议：接收数据的线程和处理数据的线
2 消息
息内容并处
"msg":业务数据}} 程最好分开，不要影响接收度。
02 03 01 02 03 04
----- ----- 记 录 2 app 消 息 丢
弃情况 -------
- ----- 断 开 1 客户端连接
----- ----- 服 务 1 端断开连接
m taobao.increment.customers.get 查看当前授权接收了那些用户的消息数据。 lzn 主动通知-发起请求
一、连接到服务端 二、请求参数 三、服务端响应 四、消息处理 五、连接断开 六、断开重连 七、多连接支持 八、203消息说明 下一节 主动通知-产生消息
一、连接到服务端
app 有消息丢弃。服务端发现 app 的连接断开后会记录 下来 app 的消息丢弃情况。203消息详细处理方法请参 考如下 八 、203消息说明
.c -------
{"packet":{"code"
-----客户端 :101"}}
主动重连
连接到达最大时间
ao -------
{"packet":{"code"
主动通知-介绍
一、主动通知简介 二、主动通知和 REST API 区别 三、主动通知价值 四、成功案例 下一节 主动通知-开通
一、主动通知简介
主动通知 API 是一种实时向客户端推送数据变化信息，降低 ISV 获取淘宝数据成本的长连接消息通知 API。比如：对于一个卖家，他 的交易可能任何时刻都会产生，此时卖家就需要及时知道每一笔新创建的订单，紧接着做发货等处理。
b 变化的数据）。 o 5、成本降低：开发者不在需要不停的轮循 API 获取最新的数据，只需要等待数据到达。尤其在随着用户量增加，轮循的成本会更大，
而且会形成恶性循环，轮循过程中会出现 API 调用错误，错误越多轮循更加频繁。最终对 TOP 对开发者造成很大的压力和开销。
.ta 6、稳定：每天消息的推送成功率在99.995%以上。
7、易用：只需要发起一个 HTTP 请求，就可以不停的接收数据，同时官方提供了 sdk，开发者只需要简单实现接口，处理业务数据。
m 四、成功案例 n 1、客道 CRM（订单同步）
1）业务场景及需求
lz 给客户提供订单同步功能，当卖家的订单创建以后需要及时的获取到卖家的订单，然后让卖家处理接下来的发货等流程。
o 服务，提高用户体验满意度。 3、多种业务数据类型：目前有商品、退款、交易、酒店、机票等消息数据，随着开发者的需求增多，会开放出来更多的业务数据类
a 型。方便开发者满足不同的用户需求。 4、数据订阅方式多样化：可以指定需要那些用户的数据，也可以指定需要某个属性满足某种条件的数据（如：只需要某些商品 id
网络不太好，或者 app 接收消息太慢。导致服务端有大
建立一个到主动通知 API 请求，相当于发起一个存活期很长的 HTTP 请求（目前的存活期是24小时），应用程序不停的从 HTTP 响应中 增量的获取结果，简单的可以认为应用程序在用 HTTP 的方式下载一个无限大的文件。
正式环境请求地址：http://stream.api.taobao.com/stream 沙箱环境请求地址：http://stream.api.tbsandbox.com/stream 客户端发起一个 HTTP POST 请求，TOP 服务端将保持住这个请求24小时。如果在连接过程中出现请求参数错误、服务端处理错误、网络 出现异常情况，服务端会断开连接。错误信息可以从 HTTP 相应头中的 errmsg 键值获得。 有些 HTTP 的客户端包只有在服务端关闭掉连接后才返回整个响应结果。这样的客户端不能用于发起 HTTP 长连接请求。需要使用能增量 的给应用程序返回响应结果的 HTTP 客户端包，比如：jdk 自带的 HttpURLConnection，或者 Apache 的 HttpClient 。另也可以使用我们的 sdk(java sdk .net sdk),sdk 包应用管理证书页面可下载，使用说明 点这里。
----- ----- 服 务 1 端断开连
接。 -----
- ----- 断 开 1 旧的连接
-----
理
-------
{"packet":{"code"
-----调 api :203,"msg":{"begin":13
m 获取丢失消 13743932379,
o 息
"end":1313745387904}}}
请求失败原因。
3）http code 为403，说明服务端在发布，应用程序可以休眠一段时间继续发起请求。
2、http 错误码说明
c
服务
app 端行
ode
端行为 为
--------
-------
- ------接受连 ----- 准 备 读 :
2接
取数据
消息体举例 {"packet":{"code" 200,"msg":"connec
含义 连接成功（服务端接受连接并且连接保持24小时）
00
tedtop
comet027111.cm4"}
}
-----
-------
{"packet":{"code"
服务端发送心跳包，防止连接被断开。msg 中的次
- ----- 发 送 -----重新发 :201,"msg":10}}
数表示从连接被接收到当前发送这个心跳包之间的这段
-----等待重 :102,"msg":60}}
b 连
服务端在升级。 msg 表示服务端升级大概需要的时 间，单位：秒。app 在这段时间之后重新连接服务端，并 且使用增量 api 把这段时间内丢失的消息获取到。
o -------
{"packet":{"code"
.ta -----等待重 :103, "msg":5}}
4）价值 客道 CRM 于2011 年双十二启用消息推送机制，目前，接入消息推送的超级卖家及大型卖家超过两百家，大多数卖家为类目 TOP10 卖 家，典型卖家如：朵朵云、芳草集、NALA、GXG 等。接入卖家日均产生订单数量约15 万单，消息推送数量约200 万条目。
主动通知-开通
一、APP（应用）订阅主动通知 二、授权接收指定用户
（2）节约服务器资源 节省服务器资源，消息推送模式采用长连接方式，消息主动推送到服务器，改变来原有主动请求增量 API 的方式，这样对于本身数
据同步服务的开发成本和服务器多线程请求的成本都有大幅度下降，也不需要担心种种由于频繁请求导致被屏蔽的问题；
3）业务结构： 消息推送目前为应用的开发提供了良好的结构支持，目前开发者不再需要关心数据的获取，可以将主要精力都放在后端的业务功能的 开发上。对于与原有的增量 API 方式相比，使用消息推送后的客道系统的内部耦合性更低，目前已经实现了增量 API 与消息推送双引擎的 模式。
三、服务端响应
m 1、检查 http 的响应 code，有以下几种情况 n 1）http code 为200，说明服务端接受了请求，应用程序可以正常读取消息。 lz 2）http code 为400，说明请求参数错误，服务端没有接受请求，应用程序从 http header 中读取 key=errmsg 的信息，查看具体的
连或马上重
连
-------
{"packet":{"code"
-----结束连 :104}}
m 接
lzn-------
{"packet":{"code"
由于某些原因服务端出现了一些问题，需要断开客 户端。msg 表示建议 app 在多少 s 之后发起新的请求连接， app 可以选择马上发起新的连接请求，也可以在一段时间 后发起连接请求
2 心跳包
起连接
时间，共发送了多少个业务消息包，app 需要设置读取超
01
时时间为1分钟左右，如果超过1分钟都没读到数据，说
明网络可能有问题了，app 需要重新发起连接
-----
-------
{"packet":{"code"
业务消息包。app 只需取出业务消息包内容，并作
- ----- 推 送 -----获取消 :202,
传统的做法：只能不停的以很短的间隔轮循 API 获取最新的交易。
m 主动通知做法：在创建交易后会客户端会非常及时的得到有新的交易创建了，然后通过 API 去获取这笔交易的详情，而不再需要以很 o 短的间隔轮询获取最新的订单。 .c 二、主动通知和 REST API 区别 o 连接到主动通知 API 需要发起一个持久打开的 HTTP 连接请求，这种方式的请求和普通的 REST API 的 HTTP 请求对于应用程序处理会 a 有很大的不同。比如：某个应用程序提供查看订单的功能。 lznm.taob 1、REST API的方式：
由于客户端发起了重复的连接请求，服务端会把前 一个连接主动断开。app 在新的连接上接收消息，并且把 前一个连接上剩余的消息接收完。（可能104包不是之前 连接上最后的包，所以最好在写代码的时候读到 null 后 才结束）
由于 app 的消息量太大，但是 app 的与 TOP 之间的
- ----- 断 开 -----检查网 :105}}