MAS20API接口插件开发手册.docx
《MAS20API接口插件开发手册.docx》由会员分享，可在线阅读，更多相关《MAS20API接口插件开发手册.docx（32页珍藏版）》请在冰豆网上搜索。
MAS20API接口插件开发手册
中国移动代理服务器MASV2.0
API接口插件
开发手册
深圳市嘉讯软件有限公司
2008年9月
1.
引言
1.1.编写目的
本手册详细描述了中国移动代理服务器（MAS）短信、彩信API的开发步骤以及注意事项。
其阅读对象为需要MAS开发、工程支持人员、集成开发人员、SI厂商开发人员、企业客户IT开发人员。
1.2.背景说明
近年来移动业务高速发展，MAS业务也开展的如火如荼，但同时许多集团客户有许多自己的IT系统，他们如何把自己的IT系统也“移动”化起来呢？
MAS做为移动代理服务器，提供了许多手段来供企业IT系统接入（如WS接口、DB接口、WAP适配），但此次API又为这许多手段之外再增加了一种方式，并且这种方式更为高效、更稳定、扩展性更强。
本手册适用于产品“中国移动代理服务器MAS”V2.0版本。
只描述了以JAVA语言客户端来接入MAS的内容，其它语言开发客户端可以参考本手册。
1.3.相关术语与缩略语解释
缩写词
英文解析
中文解析
MAS
MobileAgentServer
移动代理服务器
HTTP
HypertextTransferProtocol
超文本传输协议
HTTPS
SecureHTTP
加密的HTTP协议
SOAP
SimpleObjectAccessProtocol
简单对象访问协议
UCA
UnifiedCommunicationAgent
统一通信代理
WS
WebService
Web服务接口
2.API结构说明
企业应用通过APIClient来与MAS通信，底层采用Socket，这样可以保证高性能与稳定性。
API方式通信适配插件接口封装了以下移动通信能力：
●短信
●彩信
此外，还提供基座与应用插件之间的插件管理功能接口。
MAS服务器应提供配置工具，指定对于某个集团客户应用系统或应用插件，通过API方式通信适配插件或数据库方式通信适配插件接入MAS服务器。
这是当应用作为插件的身份来接入MAS时才考滤的开发环境。
当应用不作为插件而做为集团客户应用的身份来接入时不需关注，只需通过标准的API接口即可。
3.运行环境
●MAS2.0基座运行环境
●MAS管理平台环境
4.接口描述
4.1.短信接口
4.1.1.接口说明
图5-1-1短信API主要类结构图
集团客户应用系统和应用插件通过此接口收发短消息。
API方式通信适配插件收到应用插件的发送请求后，通过MAS服务器基座中的SMS通信协议模块发送SMS；当从SMS通信协议模块收到SMS后，通过此接口将短消息发送给集团客户应用系统和应用插件。
4.1.2.流程说明
短消息接口主要包括短信发送、接收、和取消三个流程。
短信发送：
图5-1-2短消息发送流程示意图
步骤说明：
●企业应用通过smsSend来向MAS的API适配模块提交要发送的短信，smsSend方法返回一个messageID
●MAS服务器收到消息后进行检查
●检查通过后将短信提交到UCA模块
●并把提交结果返回给API客户端
●UCA模块将短信提交到网关
●网关在向手机发送后把下发结果（状态报告或叫回执）通知给UCA模块
●UCA将状态报告传给服务器的API适配模块
●API适配模块将状态报告传给API客户端的回调对象（注，在发送时是否需要状态报告字段要填true）
短信接收：
图5-1-3短消息接收流程示意图
步骤说明：
●行业网关收到手机上行的短信
●将MO短信通知到MAS服务器的UCA模块
●UCA将MO短信交到API适配模块
●API适配模块将MO交到SmsApiClient
●SmsApiClient将MO短信回调通知到SmsApiClientHandler的notifySmsReception接口
短信取消：
图5-1-4取消短信
步骤说明：
●企业应用通过SmsApiClient发起取消请求，并到一个请求是否提交成功的结果
●服务器API适配模块向UCA模块发送取消请求，并得到已取消成功能的手机号码列表
●API适配模块将得到的取消号码列表通知给客户端
●SmsApiClient将取消成功的手机号码回调给SmsApiClientHandler的notifyCanelSmsList接口。
4.1.3.主要类说明
类名
描述
备注
ApiClientFactory
工厂方法类，主要用于创建SmsApiClient与MmsApiClient
SmsApiClient
短信客户端接口，一个Client代表与MAS服务端的一个连接
可以创建多个Client对象来发送短信，但多个Client发送的响应不一定由该Client关的Handler收到，有可能由同一API标识的其它Handler收到。
SmsApiClientImpl
短信客户端的实现类
SmsApiClientHandler
短信API回调处理接口
由企业应用来实现，一个Client对象至少关联一个Handler实例
SmsSendRequest
短信发送请求参数类
SmsSendResponse
短信发送响应类
Sms
MO短信表示对象
Report
发送回执表示对象
4.2.彩信接口
4.2.1.接口说明
图5-2-1彩信API主要类结构图
应用系统或应用插件调用发送接口给目的用户发送一条彩信。
通信适配插件采用非同步的通知机制将彩信提交状态通知给应用系统或应用插件。
对于彩信接收，可以由通信适配插件主动通知应用系统或应用插件有彩信到达，应用系统或应用插件也可通过接口从通信适配插件接收彩信。
4.2.2.流程说明
彩信发送流程：
彩信发送流程请参考API的短信发送流程图。
步骤说明：
●企业应用通过mmsSend来向MAS的API适配模块提交要发送的彩信，mmsSend方法返回一个热requestID
●MAS服务器收到消息后进行检查
●检查通过后将彩信提交到UCA模块
●并把提交结果返回给API客户端
●UCA模块将彩信提交到网关
●网关在向手机发送后把下发结果（状态报告或叫回执）通知给UCA模块
●UCA将状态报告传给服务器的API适配模块
●API适配模块将状态报告传给API客户端的回调对象（注，在发送时是否需要状态报告字段要填true）
彩信MO流程：
MO彩信通知流程请参考API的短信MO短信通知流程图。
步骤说明：
●行业网关收到手机上行的彩信
●将MO彩信通知到MAS服务器的UCA模块
●UCA将MO彩信交到API适配模块
●API适配模块将MO交到MmsApiClient
●MmsApiClient将MO彩信回调通知到MmsApiClientHandler的notifyMmsReception接口。
取消彩信发送流程：
取消彩信发送流程请参考API的取消短信流程图。
步骤说明：
●企业应用通过MmsApiClient发起取消请求，并到一个请求是否提交成功的结果
●服务器API适配模块向UCA模块发送取消请求，并得到已取消成功能的手机号码列表
●API适配模块将得到的取消号码列表通知给客户端
●MmsApiClient将取消成功的手机号码回调给MmsApiClientHandler的notifyCanelMmsMobile接口。
4.2.3.主要类说明
类名
描述
备注
ApiClientFactory
工厂方法类，主要用于创建SmsApiClient与MmsApiClient
MmsApiClient
彩信客户端接口，一个Client代表与MAS服务端的一个连接
可以创建多个Client对象来发送彩信，但多个Client发送的响应不一定由该Client关的Handler收到，有可能由同一API标识的其它Handler收到。
MmsApiClientImpl
彩信客户端的实现类
MmsApiClientHandler
彩信API回调处理接口
由企业应用来实现，一个Client对象至少关联一个Handler实例
MmsSendRequest
彩信发送请求参数类
MmsSendResponse
彩信发送响应类
MmsMessageReference
MO彩信表示对象
Report
发送回执表示对象
5.开发步骤
5.1.在Mas服务器新建一个企业应用
●首先确定所开发的应用是集团客户应用还是插件
两者的区别是，如果是插件在使用通信能力之前必须向MAS服务器注册，而如果开发的是集团客户应用，就不需预先向MAS服务器注册。
●运行MAS2服务器，登录到系统管理->“插件管理”中新建一个企业应用或插件
在开发完成后准备调试前，先运行MAS2.0服务器，然后在插件管理里新建一个应用或插件。
图5-1新增插件页面
注意：
新建时“通信接口方式”选择“API”。
5.2.启动企业应用
图5-2插件管理页面
要新建的插件API接口可用，需要点击“开关”列的运行按钮。
否则在使用WS接口通信时可能会报POL0906错误。
当然要确保API接口能正常使用，还需要管理平台相应的业务能力。
5.3.接口开发及使用举例
5.3.1.ApiClientFactory类
描述：
APIClient工厂类，用来创建短信APIClient与彩信APIClient。
5.3.1.1.createSmsApiClient方法
功能：
创建短信API客户端，一个SmsApiClient绑定了一个Socket连接。
参数
描述
备注
smsHandler
短信服务回调接口，如状态报告通知、MO短信接收、发送响应等
masIP
MAS服务器IP地址
masApiPort
MAS服务器API适配监听端口
MAS默认一般是61616，具体可在MAS上修改
apiID
API的标识，新建API时指定的
见图5-1
password
API登录的密码，新建API时指定
见图5-1
5.3.2.短信接口
5.3.2.1.SmsApiClient类
短信API客户端主要操作接口，通过ApiClientFactory类来创建期实例，一个SmsApiClient对象代表了与服务器连接，在正常与服务器通信时需要先调其start方法来初始化。
5.3.2.1.1.setTimingConnect方法
功能：
设置是否自动重连到服务器。
5.3.2.1.2.setConnectTime方法
功能：
设置自动重连服务器相隔时间（单位：
秒），默认为30秒
5.3.2.1.3.setConnectTimeout方法
功能：
设置与服务连接超时时长，单位：
millisecond，需要在调用start方法前设置方可生效。
5.3.2.1.4.setSendTimeout方法
功能：
设置发送超时时长，单位：
millisecond，需要在调用start方法前设置方可生效。
5.3.2.1.5.start方法
功能：
启动API，该方法会自动连接到MAS服务器并进行登录。
所有的发送、接收等操作都需要在start成功后方可使用。
5.3.2.1.6.getConnStatusIAGW方法
功能：
获得网关连接状态。
5.3.2.1.7.canelSms方法
功能：
取消短信发送。
5.3.2.1.8.getStat方法
功能：
获得短信队列中未发送的条数。
5.3.2.1.9.getXCodeLength方法
功能：
获得扩展服务代码（插件短信扩展号码+流水号）长度。
5.3.2.1.10.getSmsCount方法
功能：
计算短信条数和字数。
5.3.2.1.11.getSmsContentPreview方法
功能：
获得预览的短信内容。
5.3.2.1.12.loginOut方法
功能：
短信API退出。
5.3.2.1.13.getDestAddrsLimit方法
功能：
获得MAS当前短信提交的限制数量。
5.3.2.1.14.sendSms方法
功能：
发送短信。
字段
类型
描述
备注
destAddrs
List
目的地址，即手机号码集合
一次发送的最大长度，具体可通过getDestAddrsLimit方法获得
xCode
String
短信子码+流水号
message
String
短信内容
msgFormat
MsgFmt
短信内容编码格式
ASCII：
ASCII字符。
UCS2G：
USC2格式的UniCode字符。
B18030：
GB18030格式的中文字符。
GB2312：
GB2312格式的中文字符。
Binary：
二进制短信，用十六进制字符串。
type
SmsType
短信类型
Normal:
普通短信
Instant：
免提短信
Long：
长短信
Structured：
二进制短信
WapPush：
WapPush短信
priority
int
短信优先级。
大于0的正整数，数字越小优先级越高。
targetURL
String
推送URL
发送Wappush短信时有效，其它类型短信时忽略
isNeedReport
boolean
是否需要状态报告
validTime
int
短信存活期，单位秒
开始时间以MAS收到API提交时间为准
返回值
String
本次发送操作的标识
5.3.2.2.SmsApiClientHandler类
描述：
由企业应用来实现，该接口类主要是对短信服务的一些回调对象进行处理，如接收状态报告、MO短信、接收发送响应等。
5.3.2.2.1.notifySmsSendResponse方法
功能：
发送响应通知。
其smsSendResponse说明如下：
字段
类型
描述
备注
requestID
String
发送请求标识
sendSms方法返回的值
submitID
String
提交到UCA的标识
可以对应后续收到的状态报告
errCode
ErrCode
错误代码，为null表示发送成功
5.3.2.2.2.notifySmsDeliveryStatus方法
功能：
状态报告通知。
如果在发送时指定不要状态报告将不会调用到此方法
字段
类型
描述
备注
submitID
String
提交到UCA标识
sendSms方法返回的值
5.3.2.2.3.notifySmsReception方法
功能：
MO短信通知。
其sms参数说明如下
字段
类型
描述
备注
dest_Id
String
MO流水号
一般跟发送时的xCode对应
src_terminal_Id
String
上行的手机号码
content
ErrCode
短信内容
msg_fmt
MsgFmt
短信内容编码
ASCII：
ASCII字符。
UCS2G：
USC2格式的UniCode字符。
B18030：
GB18030格式的中文字符。
GB2312：
GB2312格式的中文字符。
Binary：
二进制短信，用十六进制字符串。
5.3.2.2.4.notifyCanelSmsList方法
功能：
通知取消成功的手机号码，其参数说明如下
字段
类型
描述
备注
submitID
String
提交到UCA标识
canelMobileList
List
取消成功的手机号码集合
5.3.2.3.短信开发客户端代码举例
由图5-1所示，新建了API插件，API插件标识为“API插件”，API插件密码“123123”，
下面代码演示API客户端发送短信及相关方法。
短信开发客户端相关方法调用代码example
SmsApiClientsmsApiClient=null;
longmobile=13800000000l;
StringappID="API插件";//API插件标识ID
StringappPwd="123123";//API插件密码
Stringcontent=”发送API短信”;//短信内容
Stringxcode=”222”;//短信扩展码
//SmsApiClientHandlerImpl是由自己实现的
SmsApiClientHandlersmsHandler=newSmsApiClientHandlerImpl（）;
try
{
smsApiClient=ApiClientFactory.createSmsApiClient（smsHandler,"192.168.0.238","61616",appID,appPwd）;
//设置是否自动重连到服务器（可以不需要设置，如果要设置要在start（）方法设置才有效）
smsApiClient.setTimingConnect（true）;
//设置自动重连服务器相隔时间（单位：
秒）,默认为30秒（可以不需要设置，如果要设置要在start（）方法设置才有效）
smsApiClient.setConnectTime（60）;
//设置与服务连接超时时长，单位：
millisecond（可以不需要设置，如果要设置需要在调用start方法前设置方可生效）
smsApiClient.setConnectTimeout（100000）;
//设置发送超时时长，单位：
millisecond（可以不需要设置，如果要设置需要在调用start方法前设置方可生效）
smsApiClient.setSendTimeout（1000000）;
smsApiClient.start（）;//连接服务器及登陆验证
//获得短信群发提交的数量限制
intret=smsApiClient.getDestAddrsLimit（）;
//获取网关连接状态（Connect：
连接正常,Disconnect：
断连,NotConnect：
没有连接,Other：
其他）
ConnectStatusconnectStatus=smsApiClient.getConnStatusIAGW（）;
if（!
ConnectStatus.Connect.equals（connectStatus））
{
System.out.println（"网关未连接"）;
return;
}
//计算短信条数和字数
SmsCountsmsCount=smsApiClient.getSmsCount（content,MsgFmt.GB2312,SmsType.Normal）;
//获得扩展服务代码（插件短信扩展号码+流水号）长度
intxcodeLength=smsApiClient.getXCodeLength（）
//发送短信
//＝＝＝＝＝＝构造发送短信对象开始，下面代码演示发送短信对象几个比较主要的属性值，其它的属性可以不设置，如果要设置可以参考sendSms方法中SmsSendRequest参数＝＝＝
SmsSendRequestsmsSendRequest=newSmsSendRequest（）;
Listlist=newArrayList（）;
//每次群发数量不能超过最大限制数
for（inti=0;i{
longaddress=mobile+i;
list.add（String.valueOf（address））;
}
smsSendRequest.setDestAddrs（list）;
smsSendRequest.setValidTime（10000）;//短信存活期，单位秒
smsSendRequest.setXCode（xcode）;//短信扩展码
smsSendRequest.setMessage（"短信内容"）;//短信内容
smsSendRequest.setMsgFormat（MsgFmt.GB2312）;//短信编码类型
smsSendRequest.setNeedReport（true）;//短信是否需要状态报告
smsSendRequest.setPriority（MessagePriority.Default）;//短信网关优先级
smsSendRequest.setType（SmsType.Normal）;
//＝＝＝＝＝＝构造发送短信对象结束＝＝＝＝＝＝＝
StringrequestID=smsApiClient.sendSms（smsSendRequest）;
System.out.println（"提交成功，requestID:
"+requestID）;
}
catch（Exceptione）
{
System.out.println（"API短信客户端调用失败:
"+e.getMessage（））;
return;
}
如提交成功会收到messageID,如有网络连接、密码错误等问题，则会抛相应的异常，相关异常信息请参考5.3.4 API异常错误对应常量。
5.3.3.彩信接口
5.3.3.1.MmsApiClient类
彩信API客户端主要操作接口，通过ApiClientFactory类来创建期实例，一个MmsApiClient对象代表了与服务器连接，在正常与服务器通信时需要先调其start方法来初始化。
5.3.3.1.1.setTimingConnect方法
功能：
设置是否自动重连到服务器。
5.3.3.1.2.setConnectTime方法
功能：
设置自动重连服务器相隔时间（单位：
秒），默认为30秒。
5.3.3.1.3.setConnectTimeout方法
功能：
设置与服务连接超时时长，单位：
millisecond，需要在调用start方法前设置方可生效。
5.3.3.1.4.setSendTimeout方法
功能：
设置发送超时时长，单位：
millisecond，需要在调用start方法前设置方可生效。
5.3.3.1.5.start方法
功能：
启动API，该方法会自动连接到MAS服务器并进行登录。
所有的发送、接收等操作都需要在start成功后方可使用。
5.3.3.1.6.loginOut方法
功能：
彩信API退出。
5.3.3.1.7.getConnStatusIAGW方法
功能：
获得网关连接状态。
5.3.3.1.8.getDestAddrsLimit方法
功能：
获得MAS当前彩信提交的限制数量。
5.3.3.1.9.sendMms方法
功能：
发送彩信。
其参数request说明如下
字段
类型
描述
备注
destAddrs
String
目的地址，即手机
升级会员 