中国移动代理服务器MAS v20 WebService接口插件开发手册.docx
《中国移动代理服务器MAS v20 WebService接口插件开发手册.docx》由会员分享，可在线阅读，更多相关《中国移动代理服务器MAS v20 WebService接口插件开发手册.docx（38页珍藏版）》请在冰豆网上搜索。
中国移动代理服务器MASv20WebService接口插件开发手册
中国移动代理服务器MASV2.0
WebService接口插件
开发手册
深圳市嘉讯软件有限公司
2008年9月
前言
本手册是采用深圳嘉讯有限公司MAS系统的WebService接口进行插件开发的指导手册。
目录
1.引言3
1.1.编写目的4
1.2.背景说明4
1.3.相关术语与缩略语解释4
2.概述4
3.开发环境4
4.运行环境5
5.开发步骤5
6.接口描述6
6.1.插件管理接口7
6.1.1.接口说明7
6.1.2.流程说明7
6.1.3.数据类型8
6.1.4.接口定义9
6.2.应用系统服务通知接口12
6.2.1.接口说明12
6.2.2.流程说明12
6.2.3.接口定义13
6.3.短信接口14
6.3.1.接口说明14
6.3.2.流程说明14
6.3.3.数据类型16
6.3.4.接口定义17
6.4.彩信接口21
6.4.1.接口说明21
6.4.2.流程说明21
6.4.3.数据类型23
6.4.4.接口定义24
6.5.Wappush短信接口27
6.5.1.接口说明28
6.5.2.流程说明28
6.5.3.数据类型28
6.5.4.接口定义29
1.引言
本手册用于指导嘉讯MAS2.0平台上的DB插件开发，嘉讯公司以及嘉讯MAS2.0平台的使用产商共同使用。
1.1.编写目的
本文档描述了MAS2.0基座WebService通信接口的使用方法，文档的使用对象为MAS开发人员、数字化部队、SI工程技术人员、SI开发人员、集团客户技术人员。
本文档的读者需要有一定的WebService相关知识。
1.2.背景说明
1.3.相关术语与缩略语解释
缩写词
英文解析
中文解析
MAS
MobileAgentServer
移动代理服务器
HTTP
HypertextTransferProtocol
超文本传输协议
HTTPS
SecureHTTP
加密的HTTP协议
SOAP
SimpleObjectAccessProtocol
简单对象访问协议
UCA
UnifiedCommunicationAgent
统一通信代理
WS
WebService
Web服务接口
2.概述
WebService方式通信提供了对各种通信能力的统一封装，供集团客户应用系统和MAS服务器应用插件进行调用。
同时，提供统一WebService方式封装也降低了si的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对si呈现简单的标准接口。
WebService方式通信适配插件接口封装了以下移动通信能力：
●短信
●彩信
●wappush
●ussd（暂不可用）
●LBS（暂不可用）
此外，还提供基座与应用插件之间的插件管理功能接口。
MAS服务器应提供配置工具，指定对于某个集团客户应用系统或应用插件，通过WebService方式通信适配插件或数据库方式通信适配插件接入MAS服务器。
3.开发环境
●JDK：
java5
●数据库：
mysql5.0
●应用服务器：
Tomcat5.5
●WebService工具：
AXIS1.4
这是当应用作为插件的身份来接入MAS时才考滤的开发环境。
当应用不作为插件而做为集团客户应用的身份来接入时不需关注，只需通过标准的WebService接口即可。
4.运行环境
●MAS2.0基座运行环境
●MAS管理平台环境
●WebService适配插件开关打开
5.开发步骤
●首先确定所开发的应用是集团客户应用还是插件
两者的区别是，如果是插件在使用通信能力之前必须向MAS服务器注册，而如果开发的是集团客户应用，就不需预先向MAS服务器注册。
●开发插件注册模块（如是集团客户应用忽略此步）
注册接口请参考6.1节
●开发通信接口
具体接口见第6章
●运行MAS2服务器，登录到系统管理->“插件管理”中新建一个企业应用或插件
在开完了后准备调试前，先运行MAS2.0服务器，然后在插件管理里新建一个应用或插件。
图5-1新增插件页面
图5-2插件管理页面
注意：
新建时“通信接口方式”选择“WebService”。
●在“插件管理”中把插件运行
要新建的插件WebService接口可用，需要点击“开关”列的运行按钮。
否则在使用WS接口通信时可能会报POL0906错误。
当然要确保WebService接口能正常使用，还需要管理平台相应的业务能力。
●MAS2WebService服务地址
http:
//mas_ip:
port/services/cmcc_mas_wbs
6.接口描述
6.1.插件管理接口
6.1.1.接口说明
插件管理接口实现对应用插件的注册、注销、暂停和恢复，各插件通过此接口报告插件状态。
插件管理具体内容包括：
●插件的注册、注销、启用、暂停
●插件状态报告。
WebService方式通信适配插件作为基座插件管理模块的代理，实现插件管理相关操作信息的处理和转发。
6.1.2.流程说明
插件管理流程如下：
MAS的WS服务定义文件。
图6-1插件管理流程示意图
MAS服务器系统中应用插件必须注册通过后方可使用，WebService方式通信适配插件将该请求转发到插件管理模块并获得结果，将结果封装在响应消息中返回给应用插件，注册及响应过程通过APRegistration操作实现。
应用插件注册通过后，要周期性地进行状态汇报并获取响应，状态报告及响应过程通过APStatusRep操作完成。
在应用插件运行过程中，根据从MAS统一服务平台得到的业务能力信息，插件管理模块可以主动地发出命令，暂停或恢复特定的插件，这些指令经WebService方式通信适配插件通知给应用插件，通过PauseAP和RecoveryAP两个操作实现。
在应用插件结束之前，应用插件主动发起注销操作APLogOut。
考虑到一个应用插件可能包含多个进程，因此在上述流程中，注册、状态上报和注销为进程级，而暂停和恢复为插件级。
当插件管理模块发现插件进程异常或资源占用超过阀值时，并不停止该进程，而是提示告警给指定人员。
插件分为提供Web服务端和不提供Web服务端两种。
对于提供Web服务端的情况，要在插件注册操作中指明服务端的URL，对插件的暂停和恢复可以通过PauseAP和RecoveryAP操作，或在状态上报响应中体现；对于不提供Web服务端的情况，对插件的暂停和恢复命令只能在状态上报响应中体现。
6.1.3.数据类型
注册结果：
APRegResult
数据结构：
枚举
名称
描述
success
注册成功
illegalAP
插件不被允许，注册失败
CMAbilityNotSup
不支持所要求的通信能力，注册失败
repeatedReg
重复注册，注册成功
svcAddrMismatch
注册请求中的插件Web服务端地址与之前的同一插件其它进程注册请求中的插件Web服务端地址不一致，注册失败。
AP运行状态：
APStatusType
数据结构：
枚举
名称
描述
Normal
状态正常
OutofActiveTime
超过有效期
NeedRegistration
未注册，需要先注册
OutofService
已经注销
Closed
插件进程已被mas服务器强行关闭
WaitingforConfirm
插件的注册请求等待审批中
注销结果：
APLogoutResult
数据结构：
枚举
名称
描述
success
注销成功
illegalAPid
插件id不合法，注销失败
repeatedLogout
重复注销请求
6.1.4.接口定义
6.1.4.1.插件注册
由应用插件AP发起进行注册：
操作：
APRegistration
业务触发条件：
AP插件启动后，需要自动向WebService适配插件进行注册。
注册成功后才能进行其他的正常的调用，否则，WebService适配插件会拒绝该插件后续的所有操作。
输入：
APRegistrationReq
参数
类型
可选性
描述
Apid
xsd:
string
M
AP插件的标识
APPid
xsd:
int
M
AP插件的PID
HostIP
xsd:
string
M
主机所在的ip地址
MessageNotification
MessageNotificationType[]
M
AP插件所需的通信能力及各通信能力对应的Web服务URL，若对应某通信能力，WebURL不填，表示对于该应用能力，应用插件不提供服务端。
APWSURI
xsd:
anyURI
O
应用插件对应的WEB服务端URL，若为空，则表示该应用插件不提供服务端。
输出：
APRegistrationRsp
参数
类型
可选性
描述
RegResult
APRegResult
M
注册响应结果
NextInterval
xsd:
int
M
表示AP的后续状态上报时间间隔（单位为秒）
差错：
业务异常：
●SVC0001-业务错误
策略异常：
●POL0001-策略错误
6.1.4.2.插件状态信息上报
由应用插件AP发起，报告插件的状态。
操作：
APStatusRep
业务触发条件：
在插件运行过程中，需要周期性地上报自己的运行状态。
上报周期可以由MAS服务器进行控制。
在状态上报响应消息中，MAS服务器将后续状态上报时间间隔反馈给AP，之后AP按照这个间隔进行上报插件状态。
状态上报响应消息中还可携带需要应用插件执行的管理命令，对于不提供服务端的应用插件，状态上报响应是向应用插件发送管理命令的唯一手段。
输入：
APStatusRepReq
参数
类型
可选性
描述
APid
xsd:
string
M
AP插件的标识
APStatus
APStatusType
M
插件运行状态
APPid
xsd:
int
M
AP插件的PID
输出：
APStatusRepRsp
参数
类型
可选性
描述
NextCommand
xsd:
string
O
需要插件执行的管理命令，pause代表暂停，recovery代表恢复，不填表示无命令。
NextInterval
xsd：
int
O
插件的后续上报时间间隔（单位为秒），不填表示同上次时间间隔
差错：
业务异常：
●SVC0002-不合法的输入值
策略异常：
●POL0001-策略错误
6.1.4.3.注销插件
由应用插件AP发起进行注销插件进程。
操作：
APLogOut
业务触发条件：
应用插件AP的进程在结束之前，调用此接口进行注销。
注销后的进程若重新使用，需要重新进行注册。
输入：
APLogOutReq
参数
类型
可选性
描述
APid
xsd:
string
M
AP插件的标识
APPid
xsd:
int
M
AP插件的PID
输出：
APLogOutRsp
参数
类型
可选性
描述
LogoutResult
APLogoutResult
M
注销响应结果
差错：
业务异常：
●SVC0001-业务错误
策略异常：
●POL0001-策略错误
6.1.4.4.插件暂停
此接口用于暂停AP的业务功能，由WebService插件发起。
只有当应用插件有Web服务端的情况，才能使用该操作。
操作：
PauseAP
WebService方式通信适配插件根据插件管理模块的要求，暂停AP的业务功能。
如果插件要重新启用，需要在注销后由插件重新发起注册请求；或者由WebService插件重新启动AP。
输入：
PauseAPReq
参数
类型
可选性
描述
APid
xsd:
string
M
AP插件的标识
输出：
PauseAPRsp
参数
类型
可选性
描述
ACK
xsd:
Boolean
M
true表示成功，false表示失败。
差错：
业务异常：
●SVC0001-业务错误
策略异常：
●POL0001-策略错误
6.1.4.5.插件恢复
此接口用于恢复AP的业务功能，由WebService方式通信适配插件发起，仅当应用插件有Web服务端时有效。
操作：
RecoveryAP
WebService方式通信适配插件根据业务要求，恢复已暂停的AP的业务功能。
输入：
RecoveryAPReq
参数
类型
可选性
描述
APid
xsd:
string
M
AP插件的标识
输出：
RecoveryAPRsp
参数
类型
可选性
描述
ACK
xsd:
Boolean
M
true表示成功，false表示失败。
差错：
业务异常：
●SVC0001-业务错误
策略异常：
●POL0001-策略错
6.2.应用系统服务通知接口
6.2.1.接口说明
此接口用于集团客户应用系统完成对短消息、多媒体消息、定位和USSD相关的服务通知。
集团客户应用系统通过此接口通知WebService方式通信适配插件各通信能力对应的服务端URL，以及服务端是否开启或关闭。
6.2.2.流程说明
图5-3应用系统服务通知流程示意图
对于应用系统支持服务端的情况，需要通过startNotification操作通知WebService方式通信适配插件各个通信能力对应的服务端URL，之后WebService方式通信适配插件可以调用服务端向应用系统发出各种消息通知，直到应用系统通过stopNotification通知服务端不可用为止。
应用系统可以多次执行startNotification和stopNotification操作，WebService方式通信适配插件以最后一次的通知为准。
WebService方式通信适配插件在向应用侧发出消息通知失败时，采用指数后退方式重试三次。
若重试后仍失败，则抑制后续的所有消息通知。
6.2.3.接口定义
操作：
startNotification
startNotification调用由应用系统发起，通知WebService方式通信适配插件，应用系统的服务端已经开启。
应用系统在MessageNotification参数中注明各通信能力对应的服务端URL。
输入：
startNotificationRequest
参数
类型
可选性
描述
ApplicationId
xsd:
string
M
EC应用标识
MessageNotification
MessageNotificationType[]
M
应用的各通信能力对应的Web服务URL，若对应某通信能力，WebURL不填，表示对于该应用能力，应用插件不提供服务端，或服务端不可用。
输出：
startNotificationResponse
无。
差错：
业务异常：
●SVC0001-业务错误
●SVC0002-不合法的输入值
●SVC0005-重复关联符
策略异常：
●POL0001-策略错误
操作：
stopNotification
stopNotification调用由应用系统发起，通知WebService方式通信适配插件该应用系统不再提供服务端。
输入：
stopNotificationRequest
参数
类型
可选性
描述
ApplicationId
xsd:
string
M
EC应用ID
输出：
stopNotificationResponse
无。
差错
业务异常：
●SVC0001-业务错误
●SVC0002-不合法的输入值
策略异常：
●POL0001-策略错误
6.3.短信接口
6.3.1.接口说明
集团客户应用系统和应用插件通过此接口收发短消息。
WebService方式通信适配插件收到应用插件的发送请求后，通过MAS服务器基座中的SMS通信协议模块发送SMS；当从SMS通信协议模块收到SMS后，通过此接口将短消息发送给集团客户应用系统和应用插件。
6.3.2.流程说明
短消息接口包括发送和接收两个流程。
图5-4短消息发送流程示意图
发送短信由应用系统或应用插件发起，通过sendSms操作实现。
在提交短信发送请求之后，应用侧可以主动获取短信发送状态（getSmsDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧短信发送状态（notifySmsDeliveryStatus操作）。
图5-5短消息接收流程示意图
接收短信可以通过两种方式，一种是由应用侧发起（GetReceivedSms操作），WebService方式通信适配插件将所接收到的发往该应用的短信在响应中提交；第二种是由WebService方式通信适配插件通知应用侧有短信到达（notifySmsReception操作），短信内容包含在请求中。
6.3.3.数据类型
DeliveryStatus
含义：
传送状态
数据类型：
枚举，定义如下：
参数
描述
Delivered
短消息已成功递交。
DeliveryUncertain
递交状态未知：
例如，因为短消息被发送到另外一个网络。
DeliveryImpossible
无法成功发送；短消息在超时前无法被递交。
MessageWaiting
消息仍在排队等待递交。
这是一个临时状态，等待转换为前述的状态之一。
DeliveryToTerminal
短消息已发给终端。
DeliveryNotificationNotSupported
不支持短消息提交通知。
KeyWordFilterFailed
关键字过滤未通过。
DeliveryInformation
含义：
传送消息
数据类型：
结构。
定义如下：
参数
类型
描述
Address
xsd:
anyURI
目的地址信息。
DeliveryStatus
DeliveryStatus
发送状态。
SMSMessage
含义：
短消息信息
数据类型：
结构。
定义如下：
参数
类型
描述
Message
xsd:
string
短消息中的文本。
SmsServiceActivationNumber
xsd:
anyURI
与被调用的消息业务相关的号码，即，终端用来发送消息的目标地址。
SenderAddress
xsd:
anyURI
指示短消息发送者的名称，即作为消息发起者显示在用户终端上的名称。
MessageFormat
MessageFormat
编码格式。
MessageFormat
含义：
消息编码类型
数据类型：
枚举。
定义如下：
参数
描述
ASCII
ASCII字符。
UCS2
USC2格式的UniCode字符。
GB18030
GB18030格式的中文字符。
GB2312
GB2312格式的中文字符。
Binary
二进制短信，用十六进制字符串。
SendMethodType
含义：
发送选项
数据类型：
枚举。
定义如下：
参数
描述
Normal
普通短信
Instant
普通短信立即显示
Long
长短信
Structured
长度小于160字节，但UDHI需置为1
6.3.4.接口定义
6.3.4.1.发送短消息
操作：
sendSms
sendSms调用是由应用系统或插件发起，请求发送一条短消息到一个指定地址（或地址集合），该短消息由Message描述，目的地址由DestinationAddress描述。
对于可任意扩展服务代码的应用，应用可以通过ExtendCode填写应用内部的扩展码，MAS服务器需自动在其前面补充为该业务分配的长服务号码。
对本接口的调用，MAS服务器应返回RequestIdentifier标识这次发送请求。
如果消息的长度大于可支持的最大长度，此条消息将被分成若干条短消息进行发送。
应用通过DeliverResultRequest告知是否需要返回状态报告。
MAS根据要求用notifySmsDeliveryStatus接口返回状态报告。
输入：
sendSmsRequest
参数
类型
可选性
描述
ApplicationID
xsd:
string
M
应用ID或插件的ID。
DestinationAddresses
xsd:
anyURI[0..unbounded]
M
短消息要被发送到的地址。
群发短消息的最大数量为254。
ExtendCode
xsd:
string
O
指由该应用填写的内部扩展号码。
MAS服务器需自动补充为此业务分配的长服务号码。
Message
xsd：
string
M
在短消息中发送的文本。
MessageFormat
MessageFormat
M
消息编码类型。
SendMethod
SendMethodType
M
发送消息选项。
0
DeliveryResultRequest
xsd:
boolean
O
指示是否需要网络侧返回递交状态报告。
若无，则不返回。
True表示需要网络侧返回递交状态报告，false表示不需要网络侧返回递交状态报告。
输出：
sendSmsResponse
参数
类型
可选性
描述
RequestIdentifier
xsd:
string
M
标识一个特定的短消息发送请求。
差错：
业务异常：
●SVC0001-业务错误
●SVC0002-不合法的输入值
●SVC0004-不合法地址
●SVC0006-不合法的组
●SVC0280-消息过长
策略异常：
●POL0001-策略错误
●POL0003–地址超界
●POL0006-组不被允许
●POL0007-嵌套的组不被允许
●POL0008-不允许支付
操作：
GetSmsDeliveryStatus
用于集团客户应用系统或应用插件查询短消息的发送状态。
集团客户应用系统或应用插件通过requestIdentifier指定查询对应的发送请求，状态信息由DeliveryStatus返回。
输入：
GetSmsDeliveryStatusRequest
参数
类型
可选性
描述
ApplicationID
xsd:
string
M
应用ID或插件ID。
RequestIdentifier
xsd:
string
M
在发送短信时由WebService方式通信适配插件分配的发送请求标识。
输出：
GetSmsDeliver
升级会员 