消息服务说明

文档ID: 401854
页面标识: 120a69028f0e9ea69145644317ae8bcd1614263915925
更新时间: 1728700280814
浏览量: 14857

---

1.前期准备

首先需要入驻快手电商开放平台成为开发者，并在开发者账号下创建应用。注意：消息推送可能存在消息丢失和重复(平台漏推、app接收不及时、重复推送等异常情况)，建议开通消息推送的同时，也通过api定时拉取来兜底（要保证幂等），保证数据完整性。 详情请看《入驻指南》

2.消息 接收方式

2.1开启应用消息接收功能

2.1.1 打开应用中心，选择需要消息推送的应用

2.1.2 选则左侧 消息管理，进入消息通道 配置



2.1.3 打开推送服务开关



2.2 配置应用消息接收地址

2.2.1 填写推送网址

并点保存；保存的时候平台会向该推送网址发一条测试的消息"{"test":true}"，因此推送网址需要满足第2.4点中接收消息的条件才可以保存成功。

2.3 应用订阅消息

2.3.1 订阅需要的事件消息

2.3.2 保存之后立即生效

2.4 应用接收消息

接收消息url务必满足下面条件，系统检测不满足条件会暂停发送消息：

（1）接收消息url需要支持POST方法

（2）接收消息url返回的http 返回码为200

（3）接收消息url返回json串: {"result": 1}

消息至少会推送一次，请开发者自行做幂等，平台会对应用的url进行心跳检测，url不可达时会暂停对其发送消息。心跳检测会持续向url发送测试消息:    {"test":true}, 同样需要应用返回消息接收成功。发送消息后会等待消息回执，超时时间为3000ms，若接受消息url在3000ms内还未返回回执消息，则会因为超时导致消息发送失败，消息将进行重试，重试机制可见本文当第5点。

3.消息接收接口说明

3.1 消息内容

消息格式：Json
    单条消息内容：

字段	类型	说明	示例
eventId	String	消息唯一id	267_2345_147402
bizId	Long	业务id如订单id、退款单id、商品id	201560025620985
userId	Long	商家id	12342323
openId	String	商家openId	dafagkncislgga
appKey	String	应用Id	ks669064233797003102
event	String	消息标示	kwaishop_order_addOrder
info	String	消息内容，业务内容Json串，详见消息文档参数	"{"oid":201560025620985,"sellerId":12342323}"
createTime	Long	创建时间	1591274070333
test	Boolean	是否心跳测试事件	true

3.2 消息回执接口定义

请求方式：POST
    Header:  text/plain;charset=utf-8
    Body: 加密内容
    返回参数（JSON）:

字段	类型	是否必须	说明
result	int	是	返回1表示消息接收成功

3.3 消息接收代码示例

@RestController
@RequestMapping("/event")
public class EventController {
    @RequestMapping(value = "/accept", method = RequestMethod.POST)
    public Map<String, Object> acceptEvent(@RequestBody String eventsEncoded) {
        String events = PlatformEventSecurityUtil.decode(eventsEncoded, privateKey);
        //events为明文，这里加入自己代码逻辑

        //返回成功
        Map<String, Object> result = new HashMap<>();
        result.put("result", 1);
        return result;
    }
}

PS: 建议接收到消息后做异步处理(先返回成功，再异步处理消息)，不要处理完内部逻辑后再返回结果，提高消息处理性能。

3.4 消息解密

快手电商开放平台发送的消息体采用AES加密, 每个应用在开通消息订阅功能时会生成唯一AES私钥。解密密钥获取路径应用中心 -> 详情 -> 查看， 如下图：

解密方法：

/**
 * 参数说明：
 * message:带解密的密文
 * privateKey: 加密密钥
 **/
String decodeMessage = PlatformEventSecurityUtil.decode(message, privateKey);

/**
 * 方法详情   
 **/ 
 private static final String CIPHER_ALGORITHM = "AES/CBC/PKCS5Padding";
 private static final String KEY_ALGORITHM = "AES";
 private static final String CHARSET = "UTF-8";
 public static String decode(String message, String privateKey) throws KsMerchantApiException {
        try {
            if (KsStringUtils.isBlank(message) || KsStringUtils.isBlank(privateKey)) {
                throw new KsMerchantApiException("decode param is blank");
            }
            Cipher cipher = Cipher.getInstance(CIPHER_ALGORITHM);
            byte[] key = Base64.decodeBase64(privateKey);
            SecretKeySpec keySpec = new SecretKeySpec(key, KEY_ALGORITHM);
            cipher.init(Cipher.DECRYPT_MODE, keySpec, new IvParameterSpec(new byte[16]));
            return new String(cipher.doFinal(Base64.decodeBase64(message)), CHARSET);
        } catch (Exception e) {
            throw new KsMerchantApiException("decode message fail", e);
        }
    }

使用Base64反编码密钥和消息体，使用反编码之后的密钥对反编译后的消息体进行AES解密即可

4.消息测试说明

操作完以上步骤后，如果想要验证是否能正常接收到消息，可以通过消息测试工具来验证。

4.1 选择要测试的消息

具体操作路径：文档中心 - 消息文档，选择已经订阅且想测试的消息(如新增商品消息)，选择 在线测试工具

4.2 利用消息测试中具测试

5.消息重推机制

消息推送失败后，有两种重推机制

1.自动重推：快手电商开放平台发送消息给到设定的推送地址后，如果遇到失败(返回失败、网络异常等)，会自动重试5次，时间间隔为5, 10, 20, 30, 60分钟。

2.手动重推：开发者可以到“消息管理-消息查询”里手动操作需要重推的消息。