中国移动代理服务器MAS v20 WebService接口插件开发手册.docx

1、中国移动代理服务器MAS v20 WebService接口插件开发手册中国移动代理服务器MAS V2.0 WebService接口插件开发手册深圳市嘉讯软件有限公司2008年9月前言本手册是采用深圳嘉讯有限公司MAS系统的WebService接口进行插件开发的指导手册。目录1. 引言 31.1. 编写目的 41.2. 背景说明 41.3. 相关术语与缩略语解释 42. 概述 43. 开发环境 44. 运行环境 55. 开发步骤 56. 接口描述 66.1. 插件管理接口 76.1.1. 接口说明 76.1.2. 流程说明 76.1.3. 数据类型 86.1.4. 接口定义 96.2. 应用系统

2、服务通知接口 126.2.1. 接口说明 126.2.2. 流程说明 126.2.3. 接口定义 136.3. 短信接口 146.3.1. 接口说明 146.3.2. 流程说明 146.3.3. 数据类型 166.3.4. 接口定义 176.4. 彩信接口 216.4.1. 接口说明 216.4.2. 流程说明 216.4.3. 数据类型 236.4.4. 接口定义 246.5. Wappush短信接口 276.5.1. 接口说明 286.5.2. 流程说明 286.5.3. 数据类型 286.5.4. 接口定义 291. 引言本手册用于指导嘉讯MAS2.0平台上的DB插件开发，嘉讯公司以及嘉

3、讯MAS2.0平台的使用产商共同使用。1.1. 编写目的本文档描述了MAS2.0基座WebService通信接口的使用方法，文档的使用对象为MAS开发人员、数字化部队、SI工程技术人员、SI开发人员、集团客户技术人员。本文档的读者需要有一定的WebService相关知识。1.2. 背景说明1.3. 相关术语与缩略语解释缩写词英文解析中文解析MASMobile Agent Server移动代理服务器HTTPHypertext Transfer Protocol超文本传输协议HTTPSSecure HTTP加密的HTTP协议SOAPSimple Object Access Protocol简单对象

4、访问协议UCAUnified Communication Agent统一通信代理WSWebServiceWeb服务接口2. 概述WebService方式通信提供了对各种通信能力的统一封装，供集团客户应用系统和MAS服务器应用插件进行调用。同时，提供统一WebService方式封装也降低了si的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对si呈现简单的标准接口。WebService方式通信适配插件接口封装了以下移动通信能力： 短信 彩信 wappush ussd(暂不可用) LBS(暂不可用)此外，还提供基座与应用插件之间的插件管理功能接口。MAS服务器应提供配置工具，指定对于某个

5、集团客户应用系统或应用插件，通过WebService方式通信适配插件或数据库方式通信适配插件接入MAS服务器。3. 开发环境 JDK：java5 数据库：mysql5.0 应用服务器：Tomcat5.5 WebService工具：AXIS1.4这是当应用作为插件的身份来接入MAS时才考滤的开发环境。当应用不作为插件而做为集团客户应用的身份来接入时不需关注，只需通过标准的WebService接口即可。4. 运行环境 MAS2.0基座运行环境 MAS管理平台环境 WebService适配插件开关打开5. 开发步骤 首先确定所开发的应用是集团客户应用还是插件两者的区别是，如果是插件在使用通信能力之前

6、必须向MAS服务器注册，而如果开发的是集团客户应用，就不需预先向MAS服务器注册。 开发插件注册模块(如是集团客户应用忽略此步)注册接口请参考6.1节 开发通信接口具体接口见第6章 运行MAS2服务器，登录到系统管理-“插件管理”中新建一个企业应用或插件在开完了后准备调试前，先运行MAS2.0服务器，然后在插件管理里新建一个应用或插件。图5-1新增插件页面图5-2插件管理页面注意：新建时“通信接口方式”选择“WebService”。 在“插件管理”中把插件运行要新建的插件WebService接口可用，需要点击“开关”列的运行按钮。否则在使用WS接口通信时可能会报POL0906错误。当然要确保W

7、ebService接口能正常使用，还需要管理平台相应的业务能力。 MAS2 WebService服务地址http:/mas_ip:port/services/cmcc_mas_wbs6. 接口描述6.1. 插件管理接口6.1.1. 接口说明插件管理接口实现对应用插件的注册、注销、暂停和恢复，各插件通过此接口报告插件状态。插件管理具体内容包括： 插件的注册、注销、启用、暂停 插件状态报告。WebService方式通信适配插件作为基座插件管理模块的代理，实现插件管理相关操作信息的处理和转发。6.1.2. 流程说明插件管理流程如下：MAS的WS服务定义文件。图6-1 插件管理流程示意图MAS服务器系

8、统中应用插件必须注册通过后方可使用，WebService方式通信适配插件将该请求转发到插件管理模块并获得结果，将结果封装在响应消息中返回给应用插件，注册及响应过程通过APRegistration操作实现。应用插件注册通过后，要周期性地进行状态汇报并获取响应，状态报告及响应过程通过APStatusRep操作完成。在应用插件运行过程中，根据从MAS统一服务平台得到的业务能力信息，插件管理模块可以主动地发出命令，暂停或恢复特定的插件，这些指令经WebService方式通信适配插件通知给应用插件，通过PauseAP和RecoveryAP两个操作实现。在应用插件结束之前，应用插件主动发起注销操作APLo

9、gOut。考虑到一个应用插件可能包含多个进程，因此在上述流程中，注册、状态上报和注销为进程级，而暂停和恢复为插件级。当插件管理模块发现插件进程异常或资源占用超过阀值时，并不停止该进程，而是提示告警给指定人员。插件分为提供Web服务端和不提供Web服务端两种。对于提供Web服务端的情况，要在插件注册操作中指明服务端的URL，对插件的暂停和恢复可以通过PauseAP和RecoveryAP操作，或在状态上报响应中体现；对于不提供Web服务端的情况，对插件的暂停和恢复命令只能在状态上报响应中体现。6.1.3. 数据类型注册结果：APRegResult数据结构：枚举名称描述success注册成功ille

10、galAP插件不被允许，注册失败CMAbilityNotSup不支持所要求的通信能力，注册失败repeatedReg重复注册，注册成功svcAddrMismatch注册请求中的插件Web服务端地址与之前的同一插件其它进程注册请求中的插件Web服务端地址不一致，注册失败。AP运行状态：APStatusType数据结构：枚举名称描述Normal状态正常OutofActiveTime超过有效期NeedRegistration未注册，需要先注册OutofService已经注销Closed插件进程已被mas服务器强行关闭WaitingforConfirm插件的注册请求等待审批中注销结果：APLogout

11、Result数据结构：枚举名称描述success注销成功illegalAPid插件id不合法，注销失败repeatedLogout重复注销请求6.1.4. 接口定义6.1.4.1. 插件注册由应用插件AP发起进行注册：操作：APRegistration业务触发条件：AP插件启动后，需要自动向WebService适配插件进行注册。注册成功后才能进行其他的正常的调用，否则，WebService适配插件会拒绝该插件后续的所有操作。输入：APRegistrationReq参数类型可选性描述Apidxsd: stringMAP插件的标识APPidxsd:intMAP插件的PIDHostIPxsd: st

12、ringM主机所在的ip地址MessageNotificationMessageNotificationTypeMAP插件所需的通信能力及各通信能力对应的Web服务URL，若对应某通信能力，Web URL不填，表示对于该应用能力，应用插件不提供服务端。APWSURIxsd: anyURIO应用插件对应的WEB服务端URL，若为空，则表示该应用插件不提供服务端。输出：APRegistrationRsp参数类型可选性描述RegResultAPRegResultM注册响应结果NextIntervalxsd:intM表示AP的后续状态上报时间间隔（单位为秒）差错：业务异常： SVC0001 - 业务错

13、误策略异常： POL0001 - 策略错误6.1.4.2. 插件状态信息上报由应用插件AP发起，报告插件的状态。操作：APStatusRep业务触发条件：在插件运行过程中，需要周期性地上报自己的运行状态。上报周期可以由MAS服务器进行控制。在状态上报响应消息中，MAS服务器将后续状态上报时间间隔反馈给AP，之后AP按照这个间隔进行上报插件状态。状态上报响应消息中还可携带需要应用插件执行的管理命令，对于不提供服务端的应用插件，状态上报响应是向应用插件发送管理命令的唯一手段。输入：APStatusRepReq参数类型可选性描述APidxsd:stringMAP插件的标识APStatusAPStat

14、usTypeM插件运行状态APPidxsd:intMAP插件的PID输出：APStatusRepRsp参数类型可选性描述NextCommandxsd:stringO需要插件执行的管理命令，pause代表暂停，recovery代表恢复，不填表示无命令。NextIntervalxsd：intO插件的后续上报时间间隔（单位为秒），不填表示同上次时间间隔差错：业务异常： SVC0002 - 不合法的输入值策略异常： POL0001 - 策略错误6.1.4.3. 注销插件由应用插件AP发起进行注销插件进程。操作：APLogOut业务触发条件：应用插件AP的进程在结束之前，调用此接口进行注销。注销后的进程

15、若重新使用，需要重新进行注册。输入：APLogOutReq参数类型可选性描述APidxsd:stringMAP插件的标识APPidxsd:intMAP插件的PID输出：APLogOutRsp参数类型可选性描述LogoutResultAPLogoutResultM注销响应结果差错：业务异常： SVC0001 - 业务错误策略异常： POL0001 - 策略错误6.1.4.4. 插件暂停此接口用于暂停AP的业务功能，由WebService插件发起。只有当应用插件有Web服务端的情况，才能使用该操作。操作：PauseAPWebService方式通信适配插件根据插件管理模块的要求，暂停AP的业务功能。

16、如果插件要重新启用，需要在注销后由插件重新发起注册请求；或者由WebService插件重新启动AP。输入：PauseAPReq参数类型可选性描述APidxsd:stringMAP插件的标识输出：PauseAPRsp参数类型可选性描述ACKxsd:BooleanMtrue表示成功，false表示失败。差错：业务异常： SVC0001 - 业务错误策略异常： POL0001 - 策略错误6.1.4.5. 插件恢复此接口用于恢复AP的业务功能，由WebService方式通信适配插件发起，仅当应用插件有Web服务端时有效。操作：RecoveryAPWebService方式通信适配插件根据业务要求，恢复

17、已暂停的AP的业务功能。输入：RecoveryAPReq参数类型可选性描述APidxsd:stringMAP插件的标识输出：RecoveryAPRsp参数类型可选性描述ACKxsd:BooleanMtrue表示成功，false表示失败。差错：业务异常： SVC0001 - 业务错误策略异常： POL0001 - 策略错6.2. 应用系统服务通知接口6.2.1. 接口说明此接口用于集团客户应用系统完成对短消息、多媒体消息、定位和USSD相关的服务通知。集团客户应用系统通过此接口通知WebService方式通信适配插件各通信能力对应的服务端URL，以及服务端是否开启或关闭。6.2.2. 流程说明图

18、5-3 应用系统服务通知流程示意图对于应用系统支持服务端的情况，需要通过startNotification操作通知WebService方式通信适配插件各个通信能力对应的服务端URL，之后WebService方式通信适配插件可以调用服务端向应用系统发出各种消息通知，直到应用系统通过stopNotification通知服务端不可用为止。应用系统可以多次执行startNotification和stopNotification操作，WebService方式通信适配插件以最后一次的通知为准。WebService方式通信适配插件在向应用侧发出消息通知失败时，采用指数后退方式重试三次。若重试后仍失败，则抑制

19、后续的所有消息通知。6.2.3. 接口定义操作：startNotificationstartNotification调用由应用系统发起，通知WebService方式通信适配插件，应用系统的服务端已经开启。应用系统在MessageNotification参数中注明各通信能力对应的服务端URL。输入：startNotificationRequest参数类型可选性描述ApplicationIdxsd:stringMEC应用标识MessageNotificationMessageNotificationTypeM应用的各通信能力对应的Web服务URL，若对应某通信能力，Web URL不填，表示对于该应

20、用能力，应用插件不提供服务端，或服务端不可用。输出：startNotificationResponse无。差错：业务异常： SVC0001 - 业务错误 SVC0002 - 不合法的输入值 SVC0005 - 重复关联符策略异常： POL0001 - 策略错误操作：stopNotificationstopNotification调用由应用系统发起，通知WebService方式通信适配插件该应用系统不再提供服务端。输入：stopNotificationRequest参数类型可选性描述ApplicationIdxsd: stringMEC应用ID输出：stopNotificationRespons

21、e无。差错业务异常： SVC0001 - 业务错误 SVC0002 - 不合法的输入值策略异常： POL0001 - 策略错误6.3. 短信接口6.3.1. 接口说明集团客户应用系统和应用插件通过此接口收发短消息。WebService方式通信适配插件收到应用插件的发送请求后，通过MAS服务器基座中的SMS通信协议模块发送SMS；当从SMS通信协议模块收到SMS后，通过此接口将短消息发送给集团客户应用系统和应用插件。6.3.2. 流程说明短消息接口包括发送和接收两个流程。图5-4 短消息发送流程示意图发送短信由应用系统或应用插件发起，通过sendSms操作实现。在提交短信发送请求之后，应用侧可以

22、主动获取短信发送状态（getSmsDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧短信发送状态（notifySmsDeliveryStatus操作）。图5-5 短消息接收流程示意图接收短信可以通过两种方式，一种是由应用侧发起（GetReceivedSms操作），WebService方式通信适配插件将所接收到的发往该应用的短信在响应中提交；第二种是由WebService方式通信适配插件通知应用侧有短信到达（notifySmsReception操作），短信内容包含在请求中。6.3.3. 数据类型DeliveryStatus含义：传送状态数据类型：枚举，定义如下

23、：参数描述Delivered短消息已成功递交。DeliveryUncertain递交状态未知：例如，因为短消息被发送到另外一个网络。DeliveryImpossible无法成功发送；短消息在超时前无法被递交。MessageWaiting消息仍在排队等待递交。这是一个临时状态，等待转换为前述的状态之一。DeliveryToTerminal短消息已发给终端。DeliveryNotificationNotSupported不支持短消息提交通知。KeyWordFilterFailed关键字过滤未通过。DeliveryInformation含义：传送消息数据类型：结构。定义如下：参数类型描述Addres

24、sxsd: anyURI目的地址信息。DeliveryStatusDeliveryStatus发送状态。SMSMessage含义：短消息信息数据类型：结构。定义如下：参数类型描述Messagexsd:string短消息中的文本。SmsServiceActivationNumberxsd: anyURI与被调用的消息业务相关的号码，即，终端用来发送消息的目标地址。SenderAddressxsd:anyURI指示短消息发送者的名称，即作为消息发起者显示在用户终端上的名称。MessageFormatMessageFormat编码格式。MessageFormat含义：消息编码类型数据类型：枚举。定义

25、如下：参数描述ASCIIASCII字符。UCS2USC2格式的UniCode字符。GB18030GB18030格式的中文字符。GB2312GB2312格式的中文字符。Binary二进制短信，用十六进制字符串。SendMethodType含义：发送选项数据类型：枚举。定义如下：参数描述Normal普通短信Instant普通短信立即显示Long长短信Structured长度小于160字节，但UDHI需置为16.3.4. 接口定义6.3.4.1. 发送短消息操作：sendSmssendSms调用是由应用系统或插件发起，请求发送一条短消息到一个指定地址（或地址集合），该短消息由Message描述，目的

26、地址由DestinationAddress描述。对于可任意扩展服务代码的应用，应用可以通过ExtendCode填写应用内部的扩展码，MAS服务器需自动在其前面补充为该业务分配的长服务号码。对本接口的调用，MAS服务器应返回RequestIdentifier标识这次发送请求。如果消息的长度大于可支持的最大长度，此条消息将被分成若干条短消息进行发送。应用通过DeliverResultRequest告知是否需要返回状态报告。MAS根据要求用notifySmsDeliveryStatus接口返回状态报告。 输入：sendSmsRequest参数类型可选性描述ApplicationIDxsd:strin

27、gM应用ID或插件的ID。DestinationAddressesxsd:anyURI 0.unboundedM短消息要被发送到的地址。群发短消息的最大数量为254。ExtendCodexsd:stringO指由该应用填写的内部扩展号码。MAS服务器需自动补充为此业务分配的长服务号码。Messagexsd：stringM在短消息中发送的文本。MessageFormatMessageFormatM消息编码类型。SendMethodSendMethodTypeM发送消息选项。0DeliveryResultRequestxsd:booleanO指示是否需要网络侧返回递交状态报告。若无，则不返回。Tr

28、ue表示需要网络侧返回递交状态报告，false表示不需要网络侧返回递交状态报告。输出：sendSmsResponse参数类型可选性描述RequestIdentifierxsd:stringM标识一个特定的短消息发送请求。差错：业务异常： SVC0001 - 业务错误 SVC0002 - 不合法的输入值 SVC0004 - 不合法地址 SVC0006 - 不合法的组 SVC0280 - 消息过长策略异常： POL0001 - 策略错误 POL0003 地址超界 POL0006 - 组不被允许 POL0007 - 嵌套的组不被允许 POL0008 - 不允许支付操作：GetSmsDeliveryStatus用于集团客户应用系统或应用插件查询短消息的发送状态。集团客户应用系统或应用插件通过requestIdentifier指定查询对应的发送请求，状态信息由DeliveryStatus返回。输入：GetSmsDeliveryStatusRequest参数类型可选性描述ApplicationIDxsd:stringM应用ID或插件ID。RequestIdentifierxsd:stringM在发送短信时由WebService方式通信适配插件分配的发送请求标识。输出：GetSmsDeliver