淘宝开放平台

登录
文档中心 > 商家经营工具-开发指引

商家经营工具-开发指引

聚石塔通信服务使用介绍

更新时间：2024/08/01 访问次数：71727

一、开通聚石塔通信服务


1. 登录聚石塔控制台->资源视图->产品及服务中选择->通信服务。



注意：部份开发者因曾经开通过短信服务，若在产品列表没有显示短信服务，可以在组件中心-通信服务进入控制台。   

2. 进入通信服务产品页面、勾选对应的短信服务开通协议，点击立即开通，即可进行通信服务控制台。



二、短信模板申请

 您在调用聚石塔短信接口时，需要输入相应的短信模板参数，申请短信模板有两种途径：

 1. 进入控制台 选择短信服务->配置管理，页面中点击“配置短信模板”，申请需要的短信模板。



2. 通过新增TOP接口taobao.jst.sms.template.create实现短信模版创建，调用接口时需要传入sessionKey。建议开发者申请商家通用的短信模版，供商家选择使用。 


三、短信签名申请

针对系统短信，您可以自定义签名发送短信，聚石塔不对短信签名进行管控。

针对营销短信，您需要进行签名报备，开通营销短信签名权限后，再采用以下两种方式进行签名报备：

1. 进入控制台 选择短信服务->配置管理，页面点击“配置短信签名”，申请需要的短信签名，并提交审核，您的申请不会超过2个工作日即可完成审核。



2. 如果客户需要报备的签名数量较多，可以通过新增TOP接口taobao.jst.sms.signname.create实现申请短信签名，调用接口时需要传入sessionKey。若该签名归属商家，需传商家账户授权sessionKey，若该签名归属服务商，需传服务商账户授权sessionKey。


四、短信发送

4.1 创建应用并获取短信服务API接口权限


4.1.1 登录开放平台首页，点击右上角【进入控制台】按钮。


4.1.2 创建应用（如果已经创建应用请忽略），在商家经营工具类目下 选择对应的业务类型进行创建应用。


4.1.3 如果已经创建好应用，在控制台页面选择对应的应用进入管理页面。

在淘宝开发平台的应用管理页面选择您应用的“应用管理”进入应用详情，获得稍后发送接口所需的App Key和App Secret。



4.1.4 检查app是否具有 “功能场景”列表中——“聚石塔短信服务”权限。如果已经获取“聚石塔短信服务权限包”，则表示您的App key允许调用接口发送短信发送；如果未获得“聚石塔短信服务权限包”权限，则申请权限；若您在appkey的权限能力列表中没有发现“聚石塔短信服务权限包”，请在聚石塔提交工单。



4.1.5 获取发送的SDK

在淘宝开发平台的应用管理选择左侧菜单中的SDK下载，选择对应语言的SDK。



4.2 调用接口


申请聚石塔短信服务权限包后，下载最新sdk,并调用taobao.jst.sms.message.direct.batchsend( 聚石塔新的短信发送接口 )，支持批量发送多个号码，以英文逗号分隔，最大支持200个手机号码，点击查看接口文档以及调用示例代码。

字段描述：

A:url为短信内容中传入的淘短链，请使用taobao.jst.sms.message.shorturl.create生成淘短链，该接口生成的淘短链可以直接唤起手淘，为了提升商家发送短信店铺转化率，建议在短信内容中加入淘短链推广地址，点击查看接口文档以及调用示例代码

用户调用短信发送接口后，可以通过短信记录查询或者接收消息状态报告等方式查看短信发送状态，推荐使用消息推送方式接收消息状态报告。


五、短信记录查询


调用接alibaba.aliqin.ta.sms.num.query口查询某一条短信发送是否成功及其发送状态情况，帮助服务商运营同学及时了解每一条短信的状态,点击查看接口文档以及调用示例代码。


六、接收消息状态报告


1. 注册聚石塔环境中的应用

（PS：不同与刚刚发送时候注册的电商应用信息，此处的应用指运行在聚石塔沙箱中的后端应用程序。）

https://console.cloud.tmall.com/home#/



2. 为聚石塔应用订阅指定消息

用户调用短信发送接口成功后，聚石塔短信服务会将短信发送状态报告通过消息同步服务实时推送到用户的消息队列消息队列 RocketMQ，用户可订阅消息同步服务接收聚石塔短信服务实时推送的消息状态报告.未获取到聚石塔短信服务权限包，需要先申请权限包后才能进行订阅。

登录聚石塔控制台(https://console.cloud.tmall.com/home#/)->消息同步。




订阅“聚石塔短消息发送结果报告”和 “短信上行”。



3. 给聚石塔应用分配获取消息的权限及获取聚石塔应用的AccessKeyID

切换至聚石塔应用列表页面。



进入应用详情。



点击“关联资源”授权MQ权限。





点击右上角的“设置”获取应用的AccessKeyID和AccessKeySecret。



4. 进入RocketMQ控制台，获取消息其他信息



点击控制台的RocketMq的实例信息进入实例详情。


 

通过实例详情页获取实例id和endpoint。



通过Topic管理获取Topic名称。



通过Group管理新增一个Group。



5. 下载回执SDK

下面将以http方式为例说明，（tcp方式必须运行在聚石塔的沙箱（ECS或容器）中，本地调试只能http方式。


<dependency>
    <groupId>com.aliyun.mq</groupId>
    <artifactId>mq-http-sdk</artifactId>
    <version>1.0.2</version>
</dependency>


https://github.com/aliyunmq/mq-http-java-sdk/blob/master/README.md


6.配置代码


https://github.com/aliyunmq/mq-http-samples/blob/101-dev/java/src/main/java/Consumer.java?spm=a2c4g.11186623.2.15.451b56278cVHQx&file=Consumer.java


public static void main(String[] args) {       

MQClient mqClient = new MQClient(
         // 实例详情页获取endpoint上图有说明
         "${HTTP_ENDPOINT}",
        // 聚石塔应用的AccessKeyID
         "${ACCESS_KEY}",
        // 聚石塔应用AccessSecretKey
         "${SECRET_KEY}"
    );
    
    // 所属的 Topic名称
    final String topic = "${TOPIC}";
    // 您在控制台创建的 (Group ID)
    final String groupId = "${GROUP_ID}";
    // Topic所属实例ID，默认实例为空
    final String instanceId = "${INSTANCE_ID}";
    
    final MQConsumer consumer;
    if (instanceId != null && instanceId != "") {
        consumer = mqClient.getConsumer(instanceId, topic, groupId, null);
    } else {
        consumer = mqClient.getConsumer(topic, groupId);
    }
    
    // 在当前线程循环消费消息，建议是多开个几个线程并发消费消息
    do {
       List<Message> messages = null;
        
       try {
         // 长轮询消费消息
         // 长轮询表示如果topic没有消息则请求会在服务端挂住3s，3s内如果有消息可以消费则立即返回
         messages = consumer.consumeMessage(
             3,// 一次最多消费3条(最多可设置为16条)
             3// 长轮询时间3秒（最多可设置为30秒）
         );
     } catch (Throwable e) {
           e.printStackTrace();
           try {
             Thread.sleep(2000);
           } catch (InterruptedException e1) {
             e1.printStackTrace();
           }
     }
     // 没有消息
     if (messages == null || messages.isEmpty()) {
         System.out.println(Thread.currentThread().getName() + ": no new message, continue!");
         continue;
     }
        
     // 处理业务逻辑
     for (Message message : messages) {
         System.out.println("Receive message: " + message);
     }
        
     // Message.nextConsumeTime前若不确认消息消费成功，则消息会重复消费
     // 消息句柄有时间戳，同一条消息每次消费拿到的都不一样
     {
        List<String> handles = new ArrayList<String>();
        for (Message message : messages) {
           handles.add(message.getReceiptHandle());
        }
        
        try {
            consumer.ackMessage(handles);
        } catch (Throwable e) {
            // 某些消息的句柄可能超时了会导致确认不成功
            if (e instanceof AckMessageException) {
            AckMessageException errors = (AckMessageException) e;   
            System.out.println("Ack message fail, requestId is:" + errors.getRequestId() + ", fail handles:");
            if (errors.getErrorMessages() != null) {
               for (String errorHandle :errors.getErrorMessages().keySet()) {
                   System.out.println("Handle:" + errorHandle + ", ErrorCode:" + errors.getErrorMessages().get(errorHandle).getErrorCode()+ ", ErrorMsg:" + errors.getErrorMessages().get(errorHandle).getErrorMessage());
               }
            }
            continue;
        }
        e.printStackTrace();   
       }
      }
    } while (true);
  }  
}


附录：短信上行数据结构

短信发送结果报告数据结构


短信发送结果报告数据结构。

 

 

 

FAQ

关于此文档暂时还没有FAQ
有用(5) 我要提问
返回
顶部