消息推送中心ISV使用手册

一、推送方式

网站向接入商推送实时的业务变更消息,保持数据的一致性以及同步,满足接入商业务需求,避免轮询。

1、接入商注册时,需要提供:

ISV通过“通道配置”配置连接方式。如果是选择“websocket”,开放平台会提供sdk,下载地址,具体使用方式在此文下方可见,如果是“httpCallBack”需确保这个地址通过外网能够访问到,在收到消息后返回http status code 200即可.

2、会员身份标识:

B2B开放平台使用网站会员的memberId来做消息所属会员的身份标识

3、流程说明:

对接入商ISV关心的用户(有授权关系),仅当与这会员相关的业务发生变更,且有订阅这个消息,才会推送消息给接入商。

推送的数据消息,将以http post或者websocket的方式向该推送地址发起调用,把数据推送给接入商。

接入商如果通过SDK方式接收消息,在成功收到后,SDK会自动发送回执,如果自己接收消息,则需要自行发送回执。

接收失败时,消息中心会自动重发N次(一般3次)。如果还是失败,则将消息保存入库,接收方可通过补偿API来拉取接收失败的消息。失败消息一般保存3个月,请及时拉走,超过3个月以上的消息会被丢弃。

二、推送格式

消息数据以Json格式发送,消息提供统一的模板;不同业务的消息,仅通过消息类型来区分,具体的业务消息内容,参考各个业务消息说明。

推送数据字段说明

推送中心发送的post请求,包含二个参数,编码格式统一为UTF-8,统一按照key/value格式推送:

1.键为message,值为消息的json串。对接方获取这个参数的值,然后通过json的反序列化,就得到了消息模型

2.键为_aop_signature,值为签名,针对消息的一个签名,可防篡改

消息模板字段说明

属性 说明 备注
msgId 消息ID,消息唯一性标识 如210239
gmtBorn 消息推送时间 1970.1.1到现在的毫秒数
data 具体推送的业务消息数据,json格式,字段说明,参考各个业务消息说明 如{"key1":"value1"}
userInfo memberId
type 消息类型,每个业务消息都唯一对应一个类型,参考业务消息的类型定义
extraInfo 扩展字段,暂未启用 如{"key1":"value1"}

消息模板json示例

message = {
"msgId":"12345",
"gmtBorn":"1392711616045",
  "data":{
    "key1":  "value1"
  },
  "userInfo":"memeberId",
  "type":"messageType"
}
            							

消息签名说明

仅对消息内容进行签名计算,签名算法同开放平台的算法,内容是key+value(即message+json串)

消息签名示例

# key=message
# value= message对应的json串
    String[] datas = new String[1];
    datas[0] = key + value;
    byte[] signature = SecurityUtil.hmacSha1(datas, toBytes(appSecretKey));
return encodeHexStr(signature);
            							

推送成功说明

isv收到消息之后,只要设置返回的response http status code =200就认为是消息消费成功; 如果http status code!=200,就认为是消息消费失败,推送中心后续会重试,默认重试3次

三、消息补偿API

针对推送失败的消息,我们提供补偿API机制,让isv能够主动来查询失败消息列表,做一些补偿的逻辑。

提供两种方式:

1、游标式获取失败的消息列表:

游标式获取失败的消息列表,获取的消息默认自动会做消费成功的确认。所以下次以相同条件调用获取的是剩下的数据,直至返回数据为空。

游标式获取失败的消息列表API:

https://open.1688.com/api/api.htm?ns=cn.alibaba.open&n=push.cursor.messageList&v=1

2、查询式获取失败的消息列表:

查询式获取发送的消息列表,获取的消息不会自动确认消费成功的状态,需要调用方手动调用确认api来确认。需注意,确认后,会影响分页返回的数据

查询式获取失败的消息列表API:

https://open.1688.com/api/api.htm?ns=cn.alibaba.open&n=push.query.messageList&v=1

失败消息批量确认Api:

https://open.1688.com/api/api.htm?ns=cn.alibaba.open&n=push.message.confirm&v=1

四、消息规范

未例:订单状态变化消息

消息业务说明: 订单状态发生变化的消息推送

消息类型: ORDER_STATUS_CHANGE

业务消息内容:

属性 说明 备注
orderID 订单产品ID
lastStatus 上一次订单状态
currentStatus 当前订单状态
msgSendTime 消息发送时间 消息发送的时间
userInfo 用户登录id 卖家memberId

消息内容示例

message={
    "data": {
        "currentStatus": "FINISH",
        "lastStatus": "FUND_PROCESSING",
        "orderChangeTime": "2015-06-24 19:33:26",
        "orderId": "60020931694988"
    },
"userInfo": "cn1803950",
       "type": " ORDER_STATUS_CHANGE ",
}
            							

五、SDK使用

现支持java, sdk会负责自动重连,消息确认等,用户只需要关心业务逻辑。处理消息时请实现以下接口 JAVA接口使用说明

public interface TunaMessageHandler {

 /**
    * 消息通道客户端收到消息后,会回调该方法处理具体的业务,处理结果可以通过以下两种方式来表述:
  
    * @return false:消息处理失败,消息通道将会择机重发消息,true:消息处理成功。不会再重发。
    * @throws Exception 消息处理失败,消息通道将会择机重发消息
    */    
   public boolean onMessage(TunaMessage message) throws Exception;
 
}
            							

JAVA示例:

String url = "ws://message.1688.com/websocket";
          //1688环境为ws://message.1688.com/websocket,
         TunaClient client = new TunaClient("appkey", "secret", url);
         TunaMessageHandler mhandler = new TunaMessageHandler() {
         @Override
         public boolean onMessage(TunaMessage message) throws Exception {
            boolean success = true;
            try {
/*说明,服务端推送的消息分为2种,
业务数据和系统消息,类型分别SERVER_PUSH和SYSTEM,
其中系前者是业务消息,
后者是系统消息,如appkey与secret不匹配等。*/
 
if(TunaMessageType. SERVER_PUSH.name().equals(message.getType())){//如果是业务数据
//此处填写业务逻辑,数据存储在message.getContent()中
 
}
            } catch (Exception e) {
              
            }
            return success;
            }
         };
         client.setTunaMessageHandler(mhandler);
         client.connect();
      }
        
 
//在应用关闭时:执行 client.shutdown();
 
            							

推送消息为平台最新的通知公告消息,我们建议您在查收到该消息后,对消息内容进行详细了解后,尽快给予相应应对措施,及时与我们进行沟通反馈。谢谢您的关注。