中国移动代理服务器MAS V2.0 WebService 接口插件
开发手册
北京无限立通通讯技术有限责任公司
2010年10月
目录
1．引言 (1)
1.1编写目的 (1)
1.2相关术语与缩略语解释 (1)
2．概述 (1)
3．开发环境 (2)
4．开发步骤 (2)
4.1MAS服务器应用插件WebService插件参数建立 (2)
4.2插件管理接口 (3)
4.2.1接口说明 (3)
4.2.2流程说明 (3)
4.2.3数据类型 (4)
通讯能力CMAbility (4)
4.2.4接口定义 (6)
4.3应用系统服务通知接口 (9)
4.3.1接口说明 (9)
4.3.2流程说明 (9)
4.3.3接口定义 (10)
4.3.4短信接口 (11)
4.3.5彩信接口 (17)
4.3.5WAP PUSH短信接口 (23)
1．引言
本手册用于指导立通MAS2.0平台上的WebService插件开发。
1.1编写目的
本文档描述了MAS2.0基座WebService通信接口的使用方法，文档的使用对象为MAS开发人员、数字化部队、SI工程技术人员、SI开发人员、集团客户技术人员。
注：本文档的读者需要有一定的WebService相关知识。
1.2相关术语与缩略语解释
2．概述
WebService 方式通信提供了对各种通信能力的统一封装，供集团客户应用系统和MAS服务器应用插件进行调用。同时，提供统一WebService 方式封装也降低了si 的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对si呈现简单的标准接口。WebService方式通信适配插件接口封装了以下移动通信能力：
●短信
●彩信
●Wappush
此外，还提供基座与应用插件之间的插件管理功能接口。
MAS 服务器应提供配置工具，指定对于某个集团客户应用系统或应用插件，通过WebService方式通信适配插件或数据库方式通信适配插件接入MAS服务器。
3．开发环境
●JDK：java6
●应用服务器：Tomcat5.5
●数据库版本：MySQL 5.0.21
●WebService工具：AXIS1.4
4．开发步骤
插件在使用MAS服务器通信能力之前必须向MAS服务器注册，所以必须先在MAS服务器上建立应用插件的参数信息。
4.1MAS服务器应用插件WebService插件参数建立
1：运行MAS2.0服务器，登录到“系统管理”->“MAS配置管理”->“通讯适配插件管理”中进行WebService通讯能力设置。
注：通讯能力依赖MAS服务器所拥有的能力而定，只要MAS服务器通过到MAS管理平台鉴权回来拥有短信、彩信、WapPush等能力，这里就可以进行设置。
2：创建应用插件参数，进入“配置中心”->“应用插件管理”进行参数配置，如下图红色框部分，“通讯接口方式”必须选择“WebService”，可以根据插件功能需要选择开启某个应用能力。
WebServicedi地址：http://ip:80/services/cmcc_mas_wbs
4.2插件管理接口
4.2.1接口说明
插件管理接口实现对应用插件的注册、注销、暂停和恢复，各插件通过此接口报告插件
状态。插件管理具体内容包括：
插件的注册、注销、启用、暂停
插件状态报告。
WebService方式通信适配插件作为基座插件管理模块的代理，实现插件管理相关操作信息的处理和转发。
4.2.2流程说明
插件注册流程说明：
MAS服务器系统中应用插件必须注册通过后方可使用，WebService方式通信适配插件将该请求转发到插件管理模块并获得结果，将结果封装在响应消息中返回给应用插件，注册及响应过程通过APRegistration操作实现。应用插件注册通过后，要周期性地进行状态汇报并获取响应，状态报告及响应过程通APStatusRep操作完成。
在应用插件运行过程中，根据从MAS统一服务平台得到的业务能力信息，插件管理模块可以主动地发出命令，暂停或恢复特定的插件，这些指令经WebService方式通信适配插件通知给应用插件，通过PauseAP和RecoveryAP两个操作实现。
在应用插件结束之前，应用插件主动发起注销操作APLogOut。
考虑到一个应用插件可能包含多个进程，因此在上述流程中，注册、状态上报和注销为进程级，而暂停和恢复为插件级。
当插件管理模块发现插件进程异常或资源占用超过阀值时，并不停止该进程，而是提示告警给指定人员。
插件分为提供Web服务端和不提供Web服务端两种。对于提供Web服务端的情况，要在插件注册操作中指明服务端的URL，对插件的暂停和恢复可以通过PauseAP和RecoveryAP操作，或在状态上报响应中体现；对于不提供Web服务端的情况，对插件的暂停和恢复命令只能在状态上报响应中体现。
4.2.3数据类型
通讯能力CMAbility
用于集团客户应用系统和应用插件通知通信能力需求及所提供的web服务端地址。
注册结果：APRegResult
AP运行状态：APStatusType
注销结果：APLogoutResult
AnyUri格式说明：
其它遵循以下标准
RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax
RFC 3966 The tel URI for Telephone Numbers
https://www.doczj.com/doc/fe17164526.html,/2001/XMLSchema.dtd
4.2.4接口定义
4.2.4.1插件注册
由应用插件AP发起进行注册：
操作：APRegistration
业务触发条件：AP插件启动后，需要自动向WebService适配插件进行注册。注册成功
后才能进行其他的正常的调用，否则，WebService适配插件会拒绝该插件后续的所有操作
业务异常：
SVC0001 - 业务错误.
策略异常：
?POL0001 - 策略错误.
4.2.4.2插件状态信息上传
由应用插件AP发起，报告插件的状态。
操作：APStatusRep
业务触发条件：在插件运行过程中，需要周期性地上报自己的运行状态。上报周期可以由MAS服务器进行控制。在状态上报响应消息中，MAS服务器将后续状态上报时间间隔反馈给AP，之后AP按照这个间隔进行上报插件状态。状态上报响应消息中还可携带需要应用插件执行的管理命令，对于不提供服务端的应用插件，状态上报响应是向应用插件发送管理命令的唯一手段。
业务异常：
?SVC0002 - 不合法的输入值.
策略异常：
?POL0001 - 策略错误.
4.2.4.3注销插件
由应用插件AP发起进行注销插件进程。
操作：APLogOut
业务触发条件：应用插件AP的进程在结束之前，调用此接口进行注销。注销后的进程若重新使用，需要重新进行注册。
业务异常：
?SVC0001 - 业务错误.
策略异常：
?POL0001 - 策略错误.
4.2.4.3插件暂停
此接口用于暂停AP的业务功能，由WebService插件发起。只有当应用插件有Web服务端的情况，才能使用该操作。
操作：PauseAP
WebService方式通信适配插件根据插件管理模块的要求，暂停AP的业务功能。如果插件要重新启用，需要在注销后由插件重新发起注册请求；或者由WebService插件重新启动AP。
业务异常：
?SVC0001 - 业务错误.
策略异常：
?POL0001 - 策略错误.
4.2.4.5插件恢复
此接口用于恢复AP的业务功能，由WebService方式通信适配插件发起，仅当应用插件有Web服务端时有效。
操作：RecoveryAP
WebService方式通信适配插件根据业务要求，恢复已暂停的AP的业务功能。
差错
业务异常：
?SVC0001 - 业务错误.
策略异常：
?POL0001 - 策略错误.
4.3应用系统服务通知接口
4.3.1接口说明
此接口用于集团客户应用系统完成对短消息、多媒体消息、定位和USSD相关的服务通知。集团客户应用系统通过此接口通知WebService方式通信适配插件各通信能力对应的服务端URL，以及服务端是否开启或关闭。
4.3.2流程说明
对于应用系统支持服务端的情况，需要通过startNotification操作通知WebService 方式通信适配插件各个通信能力对应的服务端URL，之后WebService方式通信适配插件可以调用服务端向应用系统发出各种消息通知，直到应用系统通过stopNotification通知服务端不可用为止。
应用系统可以多次执行startNotification和stopNotification操作，WebService方式通信适配插件以最后一次的通知为准。
WebService方式通信适配插件在向应用侧发出消息通知失败时，采用指数后退方式重试三次。若重试后仍失败，则抑制后续的所有消息通知。
操作：startNotification
startNotification调用由应用系统发起，通知WebService方式通信适配插件，应用系统的服务端已经开启。应用系统在MessageNotification参数中注明各通信能力对应的服务端URL。
无。
差错：
业务异常：
?SVC0001 - 业务错误.
?SVC0002 - 不合法的输入值.
?SVC0005 - 重复关联符.
策略异常：
?POL0001 - 策略错误.
操作：stopNotification
stopNotification调用由应用系统发起，通知WebService方式通信适配插件该应用系统不再提供服务端。
无。
差错
业务异常：
?SVC0001 - 业务错误.
?SVC0002 - 不合法的输入值.
策略异常：
POL0001 - 策略错误.
4.3.4.1接口说明
集团客户应用系统和应用插件通过此接口收发短消息。WebService方式通信适配插件收到应用插件的发送请求后，通过MAS服务器基座中的SMS通信协议模块发送SMS；当从SMS通信协议模块收到SMS后，通过此接口将短消息发送给集团客户应用系统和应用插件。
4.3.4.2流程说明
短消息接口包括发送和接收两个流程。
发送短信由应用系统或应用插件发起，通过sendSms操作实现。在提交短信发送请求之后，应用侧可以主动获取短信发送状态（getSmsDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧短信发送状态（notifySmsDeliveryStatus操作）。
接收短信可以通过两种方式，一种是由应用侧发起（GetReceivedSms 操作），WebService 方式通信适配插件将所接收到的发往该应用的短信在响应中提交；第二种是由WebService 方式通信适配插件通知应用侧有短信到达（notifySmsReception 操作），短信内容包含在请求中。 4.3.4.3数据类型 DeliveryStatus
含义：传送状态
数据类型：枚举，定义如下：
含义：传送消息
数据类型：结构。定义如下： 含义：短消息信息
数据类型：结构。定义如下：
含义：消息编码类型
数据类型：枚举。定义如下：
含义：发送选项
4.3.4.4接口定义
4.3.4.4.1发送短信
操作：sendSms
sendSms调用是由应用系统或插件发起，请求发送一条短消息到一个指定地址（或地址集合），该短消息由Message描述，目的地址由DestinationAddress描述。对于可任意扩展服务代码的应用，应用可以通过ExtendCode填写应用内部的扩展码，MAS服务器需自动在其前面补充为该业务分配的长服务号码。对本接口的调用，MAS服务器应返回RequestIdentifier标识这次发送请求。如果消息的长度大于可支持的最大长度，此条消息将被分成若干条短消息进行发送。应用通过DeliverResultRequest告知是否需要返回状态报告。MAS根据要求用notifySmsDeliveryStatus接口返回状态报告。
业务异常：
?SVC0001 - 业务错误.
?SVC0002 - 不合法的输入值.
?SVC0004 - 不合法地址.
?SVC0006 - 不合法的组.
?SVC0280 - 消息过长.
策略异常：
?POL0001 - 策略错误.
?POL0003 –地址超界.
?POL0006 - 组不被允许.
?POL0007 - 嵌套的组不被允许.
?POL0008 - 不允许支付.
操作：GetSmsDeliveryStatus
用于集团客户应用系统或应用插件查询短消息的发送状态。集团客户应用系统或应用插件通过requestIdentifier指定查询对应的发送请求，状态信息由DeliveryStatus返回。
业务异常:
?SVC0001 - 业务错误.
?SVC0002 - 不合法的输入值.
策略异常：
?POL0001 - 策略错误
4.3.4.4.2短消息通知
操作：notifySmsReception
通信适配插件收到发送到特定地址的短消息时，调用本接口，通知集团客户应用系统和应用插件有短消息到达，前提是应用系统或插件具备Web服务端。
输入：notifySmsReceptionRequest
输出：notifySmsReceptionResponse
无。
差错
无。
操作：notifySmsDeliveryStatus
应用系统或应用插件通过通信适配插件发送了短消息之后，通信适配插件对该短消息的发送分配了一个标识符RequestIdentifier。当通信适配插件获得状态报告后，调用本接口将短消息的发送状态报告给应用侧，前提是应用系统或插件具备Web服务端。状态信息在DeliveryInfomation中具体描述。
输入：notifySmsDeliveryStatusRequest
输出：notifySmsDeliveryStatusResponse
无。
差错：
无。
4.3.4.4.3短消息接收
操作：GetReceivedSms
用于集团客户应用系统和应用插件从通信适配插件获取接收到的短消息。
通信适配插件返回receivedSms，包含短消息的发送者和内容。
输入：GetReceivedSmsRequest
输出：GetReceivedSmsResponse
差错：
业务异常:
?SVC0001 - 业务错误.
?SVC0002 - 不合法的输入值.
策略异常：
?POL0001 - 策略错误
4.3.4.4.4差错定义
业务异常
4.3.4.4.5服务策略
4.3.5彩信接口
4.3.
5.1接口说明
应用系统或应用插件调用发送接口给目的用户发送一条彩信。通信适配插件采用非同步的通知机制将彩信提交状态通知给应用系统或应用插件。对于彩信接收，可以由通信适配插件主动通知应用系统或应用插件有彩信到达，应用系统或应用插件也可通过接口从通信适配插件接收彩信。 4.3.5.2流程说明
发送彩信由应用系统或应用插件发起，通过sendMessage操作实现。在彩信发送之后，应用侧可以主动获取彩信发送状态（getMessageDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧彩信发送状态（notifyMessageDeliveryReceipt操作）。
接收短信可以通过两种方式，一种是由应用侧发起（GetReceivedMessages操作），WebService方式通信适配插件将发往该应用的彩信的标识在响应中提交，应用侧获取标识之后，可以选择获取某一条彩信（getMessage操作）；第二种是由WebService方式通信适配插件通知应用侧有彩信到达（notifyMessageReception 操作），在请求中包括彩信内容。
4.3.
5.3数据类型
DeliveryStatus
MessagePriority