功能介绍

旨在为应用提供简单可用的消息对接能力，目前提供消息通道如下：

短信集成

该模块为应用提供短信对接能力，支持以下服务提供商：

  • 联通云-融合云信
  • 阿里云通信
  • 腾讯云通信
  • 华为云通信
  • 移动云通信
  • 智讯通

如上述提供商不满足需求，业务可实现com.kingengine.kems.sdk.mns.sms.service.SmsStrategyInterface完成扩展

模块引用说明

maven配置

<dependency>
     <groupId>com.kingengine.kems.sdk</groupId>
    <artifactId>kems-sdk-mns-sms</artifactId>
</dependency>

yml配置

完整配置说明参阅kems-sdk-mns-sms/src/main/resources/META-INF/spring-configuration-metadata.json

mns:
  sms:
    provider: aliyun
    plug:
      limit:
        object: sign
        period: 180
        count: 1
    # 联通云-融合云信配置
    wocn:
      url: xxx
      cpcode: xxx
      excode: xxx
      key: xxx
    # 腾讯云通信配置
    tencentyun:
      app-id: xxx
      app-key: xxx
      sign: xxx
    # 阿里云通信配置
    aliyun:
      region-id: xxx
      product: xxx
      domain: xxx
      access-key-id: xxx
      access-key-secret: xxx
      sign: xxx
    # 华为云配置
    huaweiyun:
      url: xxx
      appKey: xxx
      appSecret: xxx
      sender: xxx
      signature: xxx
    # 阿里云通信配置
    unicom:
      url: xxx
      loginName: xxx
      password: xxx
    # 阿里云通信配置
    chinamobile:
      url: xx
      appId: xx
      ecName: xx
      secretKey: xx
      sign: xx
    chinamobiletmp:
      url: xx
      appId: xx
      ecName: xx
      secretKey: xx
      sign: xx

业务调用

com.kingengine.kems.sdk.mns.sms.core.smsCore#send()查看详细参数说明

@Resource
private SmsCore smsCore;

@Test
void sendSms4WnCn() throws KeSdkException {
    WoCnSmsDto woCnSmsDto = new WoCnSmsDto();
    woCnSmsDto.setMobile("15070167413");
    woCnSmsDto.setTemplateId("66451");

    // 短信消息发送
    smsCore.sendSms(woCnSmsDto);
}

其他说明

必填参数

参数key 说明
mobile 接收对象电话号码
templateId 模板ID

模板参数集合

参数key与模板内容占位符保持一致。

假设模板内容content为：

您好！你的手机号${mobile}已欠费，请及时充值。

参数key 说明
${mobile} 13787655678

扩展参数集合

无。

邮件集成

该模块为应用提供邮件对接能力，支持以下服务提供商：

  • 微软exchange
  • QQ邮箱
  • 网易邮箱

如上述提供商不满足需求，业务可实现com.kingengine.kems.sdk.mns.mail.service.MailStrategyInterface完成扩展

模块引用说明

maven配置

<dependency>
     <groupId>com.kingengine.kems.sdk</groupId>
    <artifactId>kems-sdk-mns-mail</artifactId>
</dependency>

yml配置

完整配置说明参阅kems-sdk-mns-mail/src/main/resources/META-INF/spring-configuration-metadata.json

mns:
  mail:
  # 选择启用的短信提供商
    provider: microsoft
    qq:
      host: smtp.qq.com
      port: 463
      username: xxx
      password: xxx
      #是否开启auth认证
      auth: true
      #协议
      protocol: smtp
      #是否开启ssl
      sslEnable: true
    netease:
      host: smtp.163.com
      port: 463
      username: xxx
      password: xxx
      auth: true
      protocol: smtp
      sslEnable: true
    microsoft:
    #邮件服务器地址
      mailServer: xxx
      username: xxx
      password: xxx

业务调用

com.kingengine.kems.sdk.mns.mail.core.MailCore#send()查看详细参数说明

@Resource
private MailCore mailCore;

@Test
public void testMail() throws Exception {
    MailTemplateDTO mailDTO = new MailTemplateDTO();
    //邮箱支持填写多个，以“,”隔开
    mailDTO.setEmail("chenchunsheng@szkingdom.com,yiwenan@szkingdom.com");
    //设置类型为富文本
    mailDTO.setContentEnum(ContentEnum.RICH_TEXT);
    mailDTO.setContent("http://10.202.61.66:11111/KEDFSFile/M00/01/21/Cso9QmE4SG2AK0-HAAADxvLRAto8662329");
    ExtParam extParam = new ExtParam();
    extParam.setKey("Subject");
    extParam.setValue("测试邮件富文本");
    List<ExtParam> extParams = new ArrayList<>();
    extParams.add(extParam);
    mailDTO.setExtParams(extParams);
    List<TemplateParam> templateParams = new ArrayList<>();

    TemplateParam t1 = new TemplateParam();
    t1.setKey("{name}");
    t1.setValue("小马哥");
    TemplateParam t2 = new TemplateParam();
    t2.setKey("{age}");
    t2.setValue("20");
    templateParams.add(t1);
    templateParams.add(t2);
    mailDTO.setTemplateParams(templateParams);
    mailCore.send(mailDTO);
}

其他说明

必填参数

参数key 说明
email 接收对象邮箱
contentType 内容类型（枚举类型，参见com.kingengine.kems.sdk.mns.mail.enums.ContentEnum）
content 具体内容

模板参数集合

参数key与内容占位符保持一致。

假设模板内容content为：

您好！请于[time]去往{place}参加会议。

参数key 说明
[time] 下周五一点
{place} 六楼大会议室

扩展参数集合

区别于模板参数，为非必填项，业务方可以按需进行设置。

参数key 说明
subject 邮件主题

微信集成

该模块为应用提供微信对接能力。

模块引用说明

maven配置

<dependency>
     <groupId>com.kingengine.kems.sdk</groupId>
    <artifactId>kems-sdk-mns-wechat</artifactId>
</dependency>

yml配置

完整配置说明参阅kems-sdk-mns-wechat/src/main/resources/META-INF/spring-configuration-metadata.json

mns:
  wechat:
    access-token: 
      # 获取AccessToken策略，默认为default
      strategy: default
      # 获取AccessToken的远程地址
      url: xxx
    appid: xxx
    secret: xxx

业务调用

com.kingengine.kems.sdk.mns.wechat.core.WeChatCore#send()查看详细参数说明

@Resource
private WeChatCore weChatCore;

    @Test
    public void send() throws KeSdkException {
        WeChatTemplateMsgDTO dto = new WeChatTemplateMsgDTO();
        dto.setOpenId("ttlx1Ym8wCoFuNXQftI");
        dto.setTemplateId("_Eiby6s6fpUfSlfd_AG_hU6nplfvx6nkaM");

        TemplateParam templateParam = new TemplateParam();
        templateParam.setKey("{{first.DATA}}");
        templateParam.setValue("测试模板消息");
        List<TemplateParam> templateParams = new ArrayList<>();
        templateParams.add(templateParam);
        // 设置模板参数集合
        dto.setTemplateParams(templateParams);

        ExtParam extParam = new ExtParam();
        extParam.setKey("url");
        extParam.setValue("http://www.baidu.com");
        List<ExtParam> extParams = new ArrayList<>();
        extParams.add(extParam);
        // 设置扩展参数集合
        dto.setExtParams(extParams);

        // 微信消息发送
        weChatCore.send(dto);
    }

其他说明

必填参数

参数key 说明
openId 接收对象openID
template_id 模板ID，公众号控制台获取

模板参数集合

参数key与申请到的模板占位符保持一致，校验工作由微信服务器完成。

假设模板内容为：

{{first.DATA}}

客户姓名：{{keyword1.DATA}}

客户手机：{{keyword2.DATA}}

预约时间：{{keyword3.DATA}}

{{remark.DATA}}

参数key 说明
{{first.DATA}} 客户姓名
{{keyword1.DATA}} 客户手机
...... ......

扩展参数集合

区别于模板参数，为非必填项，业务方可以按需进行设置。

参数key 说明
url 点击消息跳转链接
miniAppId 小程序ID
miniAppPath 小程序页面路径

AccessToken获取策略

项目中关于AccessToken的使用，可能会有以下几种情况：

  1. 项目其他场景使用到AccessToken，已经实现过获取功能了；
  2. 多个测试项目使用同一个账号，统一从资源服务器获取；
  3. 临时测试，使用固定的AccessToken；
  4. 项目仅使用到模板消息功能。

综合以上几种情况，另外加上过期机制的考虑，模块提供了两种策略用以获取AccessToken，业务按需填写对应名称即可开启。

  • default：默认策略，从微信服务器获取。此时需要配置appid和secret。
mns:
  wechat:
    access-token: 
      strategy: default
    appid: xxx
    secret: xxx
  • remote：通过调用接口url来获取AccessToken，此时不需要配置appid和secret，但需要配置url。

    填写的url需满足以下要求：

    1. 支持get请求；

    2. 响应数据格式为json，内容为{accessToken: "123", expire: 1630996330498}，其中expire为时间戳。

  mns:
    wechat:
      access-token: 
        strategy: remote
        url: xxx

AccessToken策略扩展

业务可通过实现com.kingengine.kems.sdk.mns.wechat.service.IAccessTokenLoader接口完成扩展。

SDK获取AccessToken步骤：

  1. 调用IAccessTokenLoader#get()获取AccessToken；

  2. 判断expire

    2.1 小于当前时间戳，则直接使用；

    2.2 大于当前时间戳，则另外调用IAccessTokenLoader#refresh()获取。

企业微信集成

该模块为应用提供企业微信对接能力。

模块引用说明

maven配置

<dependency>
     <groupId>com.kingengine.kems.sdk</groupId>
    <artifactId>kems-sdk-mns-wecom</artifactId>
</dependency>

yml配置

mns:
  wecom:
    corpid: xxx
    app:
      - agentid: xxx
        corpsecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

业务调用

public class WeComCore {

    @Resource
    private WeComContext weComContext;

    @SneakyThrows
    public void send(WeComTemplateMsgDTO dto) {
        try {
            ValidatorUtils.validate(dto);
            weComContext.sendMsg(dto);
        } catch (MnsRuntimeException var3) {
            throw new MnsSdkException(var3.getResultCode(), var3.getMessage(), var3);
        } catch (Exception var4) {
            throw new KeSdkException(MnsResultMessage.UNKNOW_EXCEPTION, var4);
        }
    }
}

其他说明

必填参数

参数key 说明
objectSign 接收对象标识，即企业微信账号，@all表示给全部用户发送，给特定用户发送用\ 隔开

扩展参数集合

为非必填项，业务方可以按需进行设置。

参数key 说明
msgType 消息类型，字典值
safe 是否为保密消息
totag 接收标签

AccessToken获取策略

项目中关于AccessToken的使用，可能会有以下几种情况：

  1. 项目其他场景使用到AccessToken，已经实现过获取功能了；
  2. 多个测试项目使用同一个账号，统一从资源服务器获取；
  3. 临时测试，使用固定的AccessToken；

综合以上几种情况，另外加上过期机制的考虑，提供了策略用以获取AccessToken，业务按需填写对应名称即可开启。

  • 从企业微信服务器获取。此时需要配置corpid和app。
mns:
  wecom:
    corpid: xxx
    app:
      appid: xxx
      secret: xxx

微信小程序集成

该模块为应用提供微信小程序对接能力。

模块引用说明

maven配置

<dependency>
     <groupId>com.kingengine.kems.sdk</groupId>
    <artifactId>kems-sdk-mns-weapp</artifactId>
</dependency>

yml配置

完整配置说明参阅kems-sdk-mns-weapp/src/main/resources/META-INF/spring-configuration-metadata.json

mns:
  weapp:
    access-token: 
      # 获取AccessToken策略，默认为default
      strategy: default
      # 获取AccessToken的远程地址
      url: xxx
    appid: xxx
    secret: xxx

业务调用

com.kingengine.kems.sdk.mns.weapp.core.WeAppCore#send()查看详细参数说明

@Resource
    private WeAppCore weAppCore;

    @Test
    public void send() throws KeSdkException {
        WeAppTemplateMsgDTO dto = new WeAppTemplateMsgDTO();
        dto.setOpenId("ottlx1Ym8wCNoEoFuRZNXQf-lMtI");
        dto.setTemplateId("_Eiby6s6fpUbMuYfSlfd_AG_hU6nplfwlvx6nkaMwnY");

        List<TemplateParam> templateParams = new ArrayList<>();

        TemplateParam templateParam = new TemplateParam();
        templateParam.setKey("{{first.DATA}}");
        templateParam.setValue("测试模板消息");
        templateParams.add(templateParam);


        TemplateParam param1 = new TemplateParam();
        param1.setKey("miniAppId");
        param1.setValue("wx8c97da0efbfdda00");
        templateParams.add(param1);

        TemplateParam param2 = new TemplateParam();
        param1.setKey("miniAppPath");
        param1.setValue("/login");
        templateParams.add(param2);

        dto.setTemplateParams(templateParams);
        weAppCore.send(dto);
    }

其他说明

必填参数

参数key 说明
openId 接收对象openID
template_id 模板ID，公众号控制台获取
miniprogram_state 跳转小程序类型：developer为开发版；trial为体验版；formal为正式版；默认为正式版
lang 进入小程序查看”的语言类型，支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文)，默认为zh_CN

模板参数集合

参数key与申请到的模板占位符保持一致，校验工作由微信服务器完成。

假设模板内容为：

{{first.DATA}}

客户姓名：{{keyword1.DATA}}

客户手机：{{keyword2.DATA}}

预约时间：{{keyword3.DATA}}

{{remark.DATA}}

参数key (以实际为准) 说明
{{first.DATA}} 客户姓名
{{keyword1.DATA}} 客户手机
...... ......

扩展参数集合

区别于模板参数，为非必填项，业务方可以按需进行设置。

参数key 说明
page 点击模板卡片后的跳转页面，仅限本小程序内的页面。支持带参数,（示例index?foo=bar）。该字段不填则模板无跳转

AccessToken获取策略

项目中关于AccessToken的使用，可能会有以下几种情况：

  1. 项目其他场景使用到AccessToken，已经实现过获取功能了；
  2. 多个测试项目使用同一个账号，统一从资源服务器获取；
  3. 临时测试，使用固定的AccessToken；
  4. 项目仅使用到模板消息功能。

综合以上几种情况，另外加上过期机制的考虑，模块提供了两种策略用以获取AccessToken，业务按需填写对应名称即可开启。

  • default：默认策略，从微信服务器获取。此时需要配置appid和secret。
mns:
  weapp:
    access-token: 
      strategy: default
    appid: xxx
    secret: xxx
  • remote：通过调用接口url来获取AccessToken，此时不需要配置appid和secret，但需要配置url。

填写的url需满足以下要求：

  1. 支持get请求；

  2. 响应数据格式为json，内容为{accessToken: "123", expire: 1630996330498}，其中expire为时间戳。

mns:
weapp:
  access-token: 
    strategy: remote
    url: xxx

AccessToken策略扩展

业务可通过实现com.kingengine.kems.sdk.mns.weapp.service.WeAppIAccessTokenLoader接口完成扩展。

SDK获取AccessToken步骤：

  1. 调用WeAppIAccessTokenLoader#get()获取AccessToken；

  2. 判断expire

    2.1 小于当前时间戳，则直接使用；

    2.2 大于当前时间戳，则另外调用WeAppIAccessTokenLoader#refresh()获取。

怎么扩展提供商?

在sdk基础上进行扩展，能更方便的获得配套插件能力

短信扩展

  1. 依赖引入

    <dependency>
 <groupId>com.kingengine.kems.sdk</groupId>
 <artifactId>kems-sdk-mns-sms</artifactId>
</dependency>

  2. 实现接口com.kingengine.kems.sdk.mns.sms.service.SmsStrategyInterface

  3. 调整配置文件

    mns:
sms:
 # 自己扩展的提供商名字
 provider: xxx

邮件扩展

  1. 依赖引入

    <dependency>
 <groupId>com.kingengine.kems.sdk</groupId>
 <artifactId>kems-sdk-mns-mail</artifactId>
</dependency>

  2. 实现接口com.kingengine.kems.sdk.mns.mail.service.MailStrategyInterface

  3. 调整配置文件

    mns:
mail:
 # 自己扩展的提供商名字
 provider: xxx
Copyright © 2017-2023 深圳金证引擎科技有限公司 all right reserved，powered by Gitbook该文件最后修订时间： 2023-09-01 14:01:38

results matching ""

    No results matching ""