MAS应用服务器webservice接口用户手册.doc

IM移动信息机Web Service API接口用户手册

MAS服务器Web Service API接口
用户手册

V1.0

嘉讯软件
2006-3

修订记录

ID
修订历史
修改人
日期

初稿V1.0
陈铁钢
2006-4-1

修改稿V1.1
高乐平
2006-12-12

1 简介
本协议用于IM与 通过API接入IM的客户端的数据传输通讯。

缩略语清单：
client：所有通过Web Service 接口接入 IM 的客户端
IM(Information Machine)：信息机, 本文中特指短信API移动服务端
1.1 API原理
Web Service api 短信收发使用原理请参照 IM产品发布时附带的文件《IM移动信息机API2.0开发手册》。本文档不再重复阐述。
本文档解决的是 Web Service API使用方式说明。
1.2 Web Service接口API功能概述
1） MT短信发送；
2） MO短信接收；
3） 状态报告接口；
2 访问sm webservice服务地址
WSDL：http://127.0.0.1/axis/services/SMsg?wsdl
地址：http://127.0.0.1/axis/services/SMsg
注意：这里127.0.0.1只是示例，实指用户IM机器的IP地址。
在IE中任意输入以上两个url地址，如可以访问到服务（没有出现异常），则表示sm webservice服务已正常启动，可以进行以下开发
3 创建sm webservice 接口
在web页面中登陆信息机，进入系统管理—接口管理新增页面如下图

1． 选择接口类型为 web service 接口
2． 如果不需要回执回执要求一项选择为不支持回执
3． 短信回执目标url 一项为客户端被动接收回执的URL，根据用户自己需要填写
4． mo目标url 一项为客户端被动接收MO的URL，根据用户自己需要填写接口说明
5． 如果不需要回执和mo，短信回执目标url和mo目标url可填空
6． 接口状态选运行状态，否则短信无法发送成功
7． 其他几项用户根据自己需要填写

4 Web Service接口方法说明

4.1 sendSM方法

方法说明：发送一条MT短信到一个手机号码/手机号码集。

public String sendSM(String apicode,
String loginName,
String loginPwd,
String mobiles,
String content,
String smID
)
参数说明：

参数
描 述
apicode
接口编码(必填)
loginName
接口创建时的接口登录名(必填)
loginPwd
接口创建时的接口登录密码(必填)
mobiles
短信发送的目的手机号码。可以填写多个，但必须以英文分号隔开(必填)如：“13500000000,13500000001” (必填)
Content
短信内容，超过260个字符部分会被截断(必填)
smID
短信ID，0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回复。缺省值0。（可为空）

4.2 sendWAPPUSHSM方法
方法说明：发送一条MT WAPPUSH短信到一个手机号码/手机号码集。

public String sendSM(String apicode,
String loginName,
String loginPwd,
String mobiles,
String title,
String url,
String smID
)
参数说明：

参数
描 述
apicode
接口编码(必填)
loginName
接口创建时的接口登录名(必填)
loginPwd
接口创建时的接口登录密码(必填)
mobiles
短信发送的目的手机号码。可以填写多个，但必须以英文分号隔开(必填)如：“13500000000,13500000001” (必填)
title
短信标题。
url
WAP Push短信的URL，为“”或null时则发送常规短信。(必填)
smID
短信ID，0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回复。缺省值0。（可为空）

4.3 sendSM方法

方法说明：发送一条MT短信到一个手机号码/手机号码集。

public String sendSM(String apicode,
String loginName,
String loginPwd,
String mobiles,
String content,
long smID
)
参数说明：

参数
描 述
apicode
接口编码(必填)
loginName
接口创建时的接口登录名(必填)
loginPwd
接口创建时的接口登录密码(必填)
mobiles
短信发送的目的手机号码。可以填写多个，但必须以英文分号隔开(必填)如：“13500000000,13500000001” (必填)
Content
短信内容，超过260个字符部分会被截断(必填)
smID
短信ID，0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回复(必填)
4.4 sendSM方法
方法说明：发送一条MT短信到一个手机号码/手机号码集。

public String sendSM(String apicode,
String loginName,
String loginPwd,
String mobiles,
String content,
long smID，
long srcID
)
参数说明：

参数
描 述
apicode
接口编码(必填)
loginName
接口创建时的接口登录名(必填)
loginPwd
接口创建时的接口登录密码(必填)
mobiles
短信发送的目的手机号码。可以填写多个，但必须以英文分号隔开(必填)如：“13500000000,13500000001” (必填)
Content
短信内容，超过260个字符部分会被截断(必填)
smID
短信ID，0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回复。(必填)
srcID
终端源地址,缺省值为smID.(可为空)
4.5 sendSM方法

方法说明：发送一条MT短信到一个手机号码/手机号码集。

public String sendSM(String apicode,
String loginName,
String loginPwd,
String mobiles,
String content,
long smID,
String url
)
参数说明：

参数
描 述
apicode
接口编码(必填)
loginName
接口创建时的接口登录名(必填)
loginPwd
接口创建时的接口登录密码(必填)
mobiles
短信发送的目的手机号码。可以填写多个，但必须以英文分号隔开(必填)如：“13500000000,13500000001” (必填)
Content
短信内容，超过260个字符部分会被截断(必填)
smID
短信ID，0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回复。(必填)
url
WAP Push短信的URL，为“”或null时则发送常规短信。.(可为空)

4.6 sendSM方法

方法说明：发送一条MT短信到一个手机号码/手机号码集。

public String sendSM(String apicode,
String loginName,
String loginPwd,
String mobiles,
String content,
long smID,
long srcID,
String url
)
参数说明：

参数
描 述
apicode
接口编码(必填)
loginName
接口创建时的接口登录名(必填)
loginPwd
接口创建时的接口登录密码(必填)
mobiles
短信发送的目的手机号码。可以填写多个，但必须以英文分号隔开(必填)如：“13500000000,13500000001” (必填)
Content
短信内容，超过260个字符部分会被截断(必填)
smID
短信ID，0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回复。(必填)
srcID
终端源地址,缺省值为smID.(可为空)
url
WAP Push短信的URL，为“”或null时则发送常规短信。.(可为空)

4.7 sendSM方法
方法说明：发送一条MT WAPPUSH短信到一个手机号码/手机号码集。

public String sendSM(String apicode,
String loginName,
String loginPwd,
String mobiles,
String content,
String smID,
String srcID,
String url
)
参数说明：

参数
描 述
apicode
接口编码(必填)
loginName
接口创建时的接口登录名(必填)
loginPwd
接口创建时的接口登录密码(必填)
mobiles
短信发送的目的手机号码。可以填写多个，但必须以英文分号隔开(必填)如：“13500000000,13500000001” (必填)
Content
短信内容，超过260个字符部分会被截断(必填)。
smID
短信ID，0到99999999中的某一整数。确保唯一后可以用来找到对应的回执、回复。(必填)
srcID
终端源地址,缺省值为smID.(可为空)
url
WAP Push短信的URL，为“”或null时则发送常规短信。.(可为空)

注意：
WAP PUSH 短信 URL 不能大于110字节，url和内容总长不能超过120字节。如果url超过110字节，则IM接收后可能做异常处理不予发送，如果总长超过120字节，则发送时标题内容将被截取。
5 客户端调用方法（MT发送短信）
摘要：本章详细介绍了如何使用客户端组件提交发送短信请求
采用Java语言开发，支持目前主流的各种平台，包括Windows、Unix、Linux操作系统
实例程序参考DemoFrame.java
/**
* 短信平台客户端编程实例
*
* 描述:
* 开发语言为JAVA，该说明适用于JAVA程序员
* 该实例适用于windows, Linux, 所有UNIX(可安装JDK1.3以上版本和JCE)操作系统，不能用于手持设备。
* 注:如果使用JDK1.4以上版本不需要额外安装JCE。如果使用JDK1.3x，请安装JCE。
* 该实例采用了Apache组织的axis项目的库完成SOAP协议Over HTTP功能，版本是1.1RC2，
* 你也可以采用其他你所熟悉的SOAP兼容库。
* Apache AXIS的详细介绍请参见http://ws.apache.org/axis/
* 通过SSL发送短信的实现参照该方式自行解决
* 该程序的逻辑说明请参见短信平台客户端开发的相关文档
* 该程序只作为参考实现，未考虑运行效率，请客户端开发者根据自己的实际情况修改，
* 例如尽量减少网络连接请求次数等
* 版本: 1.0.0
*/

l 使用步骤:（以下仅供参考）
1) 利用axis的wsdl2java工具生成java客户端程序（建议使用axis 1_2以上版本）
命令行为: java -cp "<axis_jar_lib>" org.apache.axis.wsdl.WSDL2Java <your_wsdl_url>
例如：假设axis-1_2装在E:\ProgramFiles
java -cp "E:\ProgramFiles\axis-1_2\lib\axis.jar;E:\ProgramFiles\axis-1_2\lib\axis-ant.jar;E:\ProgramFiles\axis-1_2\lib\commons-discovery.jar;E:\ProgramFiles\axis-1_2\lib\commons-logging.jar;E:\ProgramFiles\axis-1_2\lib\jaxrpc.jar;E:\ProgramFiles\axis-1_2\lib\log4j-1.2.8.jar;E:\ProgramFiles\axis-1_2\lib\saaj.jar;E:\ProgramFiles\axis-1_2\lib\wsdl4j-1.5.1.jar" org.apache.axis.wsdl.WSDL2Java http://127.0.0.1:8080/axis/services/SMsg?wsdl –p client
(* -p 后面为生成的java类的包名，用户可根据需要自己定义)
注意：127.0.0.1：8080实际填写是IM机器的IP地址。
2) 在c根目录下生成client文件夹，里面有java客户端代理程序
SMsg.java，
SMsgService.java，
SMsgServiceLocator.java
SMsgSoapBindingStub.java
3) 将这几个java类导入你的开发工程,
4) 如实例程序DemoFrame.java所示的进行调用
SMsgService service=new SMsgServiceLocator();
SMsg client=service.getSMsg();
String result=client.sendSM(apiCode,loginName,loginPwd,mobiles,content,,smId);
5）切记要引入lib目录下的jar文件
6 接收MO和状态报告的前置条件
6.1 前置条件
确保API用户已经创建webservice接口，API与上行相关的信息，有以下几点：

Ø 短信回执目标url：此为您的上行接收逻辑的名称，如http://localhost:8080/im/UPReceiver.asp
Ø Mo目标url：此为您的上行接收逻辑的名称，如http://localhost:8080/im/UPReceiver.asp

7 接收MO上行短信
摘要：本章详细介绍了如何接收用户手机的上行短信
7.1 上行短信的XML定义
<?xml version="1.0" encoding="UTF-8"?>
<im apicode="1" >
<sms>
<deliver mobile="13512345678" sm_id="1" content="请假一天"/>
<deliver mobile="13512349999" sm_id="1" content="请假3天"/>
</sms>
</im>

节点说明：
节 点
描 述
apicode
接口编号
mobile
发送短信的手机号码
sm_id
MO短信的短信ID
content
短信内容

1)移动服务器端的上行组件将上行短信组织成XML，然后根据API调用程序所在地址主动提交给特定的jsp文件处理。
2)服务端每次最多只返回200个MO短信。
7.2 如何接收上行XML
在此以java（jsp）为例:

<%@ page contentType="text/html; charset=GBK" %>
<html>
<head>
<title>
jsp1
</title>
</head>
<body bgcolor="#ffffff">
<h1>
begin
</h1>
<%
ServletInputStream sin = request.getInputStream();
byte[] buf = new byte[51200];
int index = 0;
while (true) {
int ch = sin.read();
if (ch == -1) break;

buf[index++] = (byte)ch;

//out.println(ch);
}

byte[] buf2 = new byte[index];
System.arraycopy(buf, 0, buf2, 0, index);

String info = new String(buf2, "GBK");
out.println(info);
/**j将得到的字符串写入xml文件
byte[] buf3 = info.trim().getBytes("GBK");
String temp = new String(buf3, "iso8859-1")
File f=new File("xiaogao1.xml");
if(f.exists()){
f=new File("aa.xml");
}
try
{
DataOutputStream output = new DataOutputStream(new FileOutputStream(f));
output.writeBytes(temp);
}
catch (Exception e)
{
// TODO Auto-generated catch block
e.printStackTrace();
}
**/
%>
<h1>
end
</h1>
</body>
</html>

本节介绍了如何撰写接收上行短信XML流的jsp文件(linux/unix)。其中就就jsp只是简单的将此XML流存成文件，企业可以根据自己的需要做更多的事情。

7.3 小结
本章介绍了如何接收上行短信，可以将此理解为移动服务器向企业客户端PUSH(推)的过程。

8 接收状态报告
接收状态报告的过程和接收上行短信处理方法一致。
8.1 状态报告的XML定义
<?xml version="1.0" encoding="UTF-8"?>
<im apicode ="1">
<sms>
<report mobile="13900000002" sm_id="1" code="0" desc=”正确”/>
<report mobile="13900000003" sm_id="2" code="0" desc=”正确”/>
</sms>
</im>

节点说明：
节 点
描 述
apicode
接口编号
mobile
发送短信的手机号码
sm_id
发送短信的短信ID
code
回执编码
desc
回执描述

1)移动服务器端的上行组件将上行短信组织成XML，然后根据API调用程序所在地址主动提交给特定的jsp文件处理。
2)服务端每次最多只返回200个RPT。

9 错误码使用说明
对于错误码的处理，0始终表示成功，其他表示失败，具体错误代码见附录的错误列表。

10 附录
10.1 短信发送方法返回错误码
错误代码
描述
10121
数据库连接失败（用户名密码错）
10122
参数错误（参数为空）
10123
apiId比存在
10124
SMID非法
10125
Wap push url 长度过长
10126
数据库插入错误
10128-10150
保留

10.2 回执编码列表
所有短信回执的回执定义如下列表：
回执编码
回执描述
说明
0
发送成功
手机已收到短信。
1
发送内容为空
没有短信内容。
2
发送内容中存在被禁止词组
短信内容中包含短信过滤模块中所设置的过滤词组。
3
手机号码不正确
不是正确的手机号码。
4
手机号码为运营商所禁止
此手机号码的短信发送不为运营商所支持或被运营商所禁止
5
手机号码存在黑名单中
此手机号码在短信过滤模块中所设置的黑名单范围中。
6
手机号码不存在白名单中
此手机号码不在短信过滤模块中所设置的白名单范围中。
7
企业欠费
企业帐户余额已用完。
101
系统错误[n]
系统内部出错。频繁出现此问题请联系开发商。
102
短信内容无法到达手机[n]
短信中心无法把短信发送到对应手机。可能是手机不存在、手机停机、手机关机、手机接收信号不好、短信中心出问题等原因所造成。

15