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

1、6.5.3. 数据类型 286.5.4. 接口定义 291. 引言本手册用于指导嘉讯MAS2.0平台上的DB插件开发，嘉讯公司以及嘉讯MAS2.0平台的使用产商共同使用。1.1. 编写目的本文档描述了MAS2.0基座WebService通信接口的使用方法，文档的使用对象为MAS开发人员、数字化部队、SI工程技术人员、SI开发人员、集团客户技术人员。本文档的读者需要有一定的WebService相关知识。1.2. 背景说明1.3. 相关术语与缩略语解释缩写词英文解析中文解析MASMobile Agent Server移动代理服务器HTTPHypertext Transfer Protocol超文本

2、传输协议HTTPSSecure HTTP加密的HTTP协议SOAPSimple Object Access Protocol简单对象访问协议UCAUnified Communication Agent统一通信代理WSWebServiceWeb服务接口2. 概述WebService方式通信提供了对各种通信能力的统一封装，供集团客户应用系统和MAS服务器应用插件进行调用。同时，提供统一WebService方式封装也降低了si的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对si呈现简单的标准接口。WebService方式通信适配插件接口封装了以下移动通信能力： 短信 彩信 wappush

3、 ussd（暂不可用） LBS（暂不可用）此外，还提供基座与应用插件之间的插件管理功能接口。MAS服务器应提供配置工具，指定对于某个集团客户应用系统或应用插件，通过WebService方式通信适配插件或数据库方式通信适配插件接入MAS服务器。3. 开发环境 JDK：java5 数据库：mysql5.0 应用服务器：Tomcat5.5 WebService工具：AXIS1.4这是当应用作为插件的身份来接入MAS时才考滤的开发环境。当应用不作为插件而做为集团客户应用的身份来接入时不需关注，只需通过标准的WebService接口即可。4. 运行环境 MAS2.0基座运行环境 MAS管理平台环境 We

4、bService适配插件开关打开5. 开发步骤 首先确定所开发的应用是集团客户应用还是插件两者的区别是，如果是插件在使用通信能力之前必须向MAS服务器注册，而如果开发的是集团客户应用，就不需预先向MAS服务器注册。 开发插件注册模块（如是集团客户应用忽略此步）注册接口请参考6.1节 开发通信接口具体接口见第6章 运行MAS2服务器，登录到系统管理-“插件管理”中新建一个企业应用或插件在开完了后准备调试前，先运行MAS2.0服务器，然后在插件管理里新建一个应用或插件。图5-1新增插件页面图5-2插件管理页面注意：新建时“通信接口方式”选择“WebService”。 在“插件管理”中把插件运行要新

5、建的插件WebService接口可用，需要点击“开关”列的运行按钮。否则在使用WS接口通信时可能会报POL0906错误。当然要确保WebService接口能正常使用，还需要管理平台相应的业务能力。 MAS2 WebService服务地址http:/mas_ip:port/services/cmcc_mas_wbs6. 接口描述6.1. 插件管理接口6.1.1. 接口说明插件管理接口实现对应用插件的注册、注销、暂停和恢复，各插件通过此接口报告插件状态。插件管理具体内容包括： 插件的注册、注销、启用、暂停 插件状态报告。WebService方式通信适配插件作为基座插件管理模块的代理，实现插件管理相

6、关操作信息的处理和转发。6.1.2. 流程说明插件管理流程如下：MAS的WS服务定义文件。图6-1 插件管理流程示意图MAS服务器系统中应用插件必须注册通过后方可使用，WebService方式通信适配插件将该请求转发到插件管理模块并获得结果，将结果封装在响应消息中返回给应用插件，注册及响应过程通过APRegistration操作实现。应用插件注册通过后，要周期性地进行状态汇报并获取响应，状态报告及响应过程通过APStatusRep操作完成。在应用插件运行过程中，根据从MAS统一服务平台得到的业务能力信息，插件管理模块可以主动地发出命令，暂停或恢复特定的插件，这些指令经WebService方式通

7、信适配插件通知给应用插件，通过PauseAP和RecoveryAP两个操作实现。在应用插件结束之前，应用插件主动发起注销操作APLogOut。考虑到一个应用插件可能包含多个进程，因此在上述流程中，注册、状态上报和注销为进程级，而暂停和恢复为插件级。当插件管理模块发现插件进程异常或资源占用超过阀值时，并不停止该进程，而是提示告警给指定人员。插件分为提供Web服务端和不提供Web服务端两种。对于提供Web服务端的情况，要在插件注册操作中指明服务端的URL，对插件的暂停和恢复可以通过PauseAP和RecoveryAP操作，或在状态上报响应中体现；对于不提供Web服务端的情况，对插件的暂停和恢复命令

8、只能在状态上报响应中体现。6.1.3. 数据类型注册结果：APRegResult数据结构：枚举名称描述success注册成功illegalAP插件不被允许，注册失败CMAbilityNotSup不支持所要求的通信能力，注册失败repeatedReg重复注册，注册成功svcAddrMismatch注册请求中的插件Web服务端地址与之前的同一插件其它进程注册请求中的插件Web服务端地址不一致，注册失败。AP运行状态：APStatusTypeNormal状态正常OutofActiveTime超过有效期NeedRegistration未注册，需要先注册OutofService已经注销Closed插件进

9、程已被mas服务器强行关闭WaitingforConfirm插件的注册请求等待审批中注销结果：APLogoutResult注销成功illegalAPid插件id不合法，注销失败repeatedLogout重复注销请求6.1.4. 接口定义6.1.4.1. 插件注册由应用插件AP发起进行注册：操作：APRegistration业务触发条件：AP插件启动后，需要自动向WebService适配插件进行注册。注册成功后才能进行其他的正常的调用，否则，WebService适配插件会拒绝该插件后续的所有操作。输入：APRegistrationReq参数类型可选性Apidxsd: stringMAP插件的标

10、识APPidintAP插件的PIDHostIP主机所在的ip地址MessageNotificationMessageNotificationTypeAP插件所需的通信能力及各通信能力对应的Web服务URL，若对应某通信能力，Web URL不填，表示对于该应用能力，应用插件不提供服务端。APWSURI anyURIO应用插件对应的WEB服务端URL，若为空，则表示该应用插件不提供服务端。输出：APRegistrationRspRegResult注册响应结果NextInterval表示AP的后续状态上报时间间隔（单位为秒）差错：业务异常： SVC0001 - 业务错误策略异常： POL0001 -

11、 策略错误6.1.4.2. 插件状态信息上报由应用插件AP发起，报告插件的状态。APStatusRep在插件运行过程中，需要周期性地上报自己的运行状态。上报周期可以由MAS服务器进行控制。在状态上报响应消息中，MAS服务器将后续状态上报时间间隔反馈给AP，之后AP按照这个间隔进行上报插件状态。状态上报响应消息中还可携带需要应用插件执行的管理命令，对于不提供服务端的应用插件，状态上报响应是向应用插件发送管理命令的唯一手段。APStatusRepReqAPidstringAPStatus插件运行状态APStatusRepRspNextCommand需要插件执行的管理命令，pause代表暂停，rec

12、overy代表恢复，不填表示无命令。xsd：插件的后续上报时间间隔（单位为秒），不填表示同上次时间间隔 SVC0002 - 不合法的输入值6.1.4.3. 注销插件由应用插件AP发起进行注销插件进程。APLogOut应用插件AP的进程在结束之前，调用此接口进行注销。注销后的进程若重新使用，需要重新进行注册。APLogOutReqAPLogOutRspLogoutResult注销响应结果6.1.4.4. 插件暂停此接口用于暂停AP的业务功能，由WebService插件发起。只有当应用插件有Web服务端的情况，才能使用该操作。PauseAPWebService方式通信适配插件根据插件管理模块的要求

13、，暂停AP的业务功能。如果插件要重新启用，需要在注销后由插件重新发起注册请求；或者由WebService插件重新启动AP。PauseAPReqPauseAPRspACKBooleantrue表示成功，false表示失败。6.1.4.5. 插件恢复此接口用于恢复AP的业务功能，由WebService方式通信适配插件发起，仅当应用插件有Web服务端时有效。RecoveryAPWebService方式通信适配插件根据业务要求，恢复已暂停的AP的业务功能。RecoveryAPReqRecoveryAPRsp POL0001 - 策略错6.2. 应用系统服务通知接口6.2.1. 接口说明此接口用于集团客

14、户应用系统完成对短消息、多媒体消息、定位和USSD相关的服务通知。集团客户应用系统通过此接口通知WebService方式通信适配插件各通信能力对应的服务端URL，以及服务端是否开启或关闭。6.2.2. 流程说明图5-3 应用系统服务通知流程示意图对于应用系统支持服务端的情况，需要通过startNotification操作通知WebService方式通信适配插件各个通信能力对应的服务端URL，之后WebService方式通信适配插件可以调用服务端向应用系统发出各种消息通知，直到应用系统通过stopNotification通知服务端不可用为止。应用系统可以多次执行startNotification

15、和stopNotification操作，WebService方式通信适配插件以最后一次的通知为准。WebService方式通信适配插件在向应用侧发出消息通知失败时，采用指数后退方式重试三次。若重试后仍失败，则抑制后续的所有消息通知。6.2.3. 接口定义startNotificationstartNotification调用由应用系统发起，通知WebService方式通信适配插件，应用系统的服务端已经开启。应用系统在MessageNotification参数中注明各通信能力对应的服务端URL。startNotificationRequestApplicationIdEC应用标识应用的各通信能力

16、对应的Web服务URL，若对应某通信能力，Web URL不填，表示对于该应用能力，应用插件不提供服务端，或服务端不可用。startNotificationResponse无。 SVC0005 - 重复关联符stopNotificationstopNotification调用由应用系统发起，通知WebService方式通信适配插件该应用系统不再提供服务端。stopNotificationRequestEC应用IDstopNotificationResponse差错6.3. 短信接口6.3.1. 接口说明集团客户应用系统和应用插件通过此接口收发短消息。WebService方式通信适配插件收到应用插

17、件的发送请求后，通过MAS服务器基座中的SMS通信协议模块发送SMS；当从SMS通信协议模块收到SMS后，通过此接口将短消息发送给集团客户应用系统和应用插件。6.3.2. 流程说明短消息接口包括发送和接收两个流程。图5-4 短消息发送流程示意图发送短信由应用系统或应用插件发起，通过sendSms操作实现。在提交短信发送请求之后，应用侧可以主动获取短信发送状态（getSmsDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧短信发送状态（notifySmsDeliveryStatus操作）。图5-5 短消息接收流程示意图接收短信可以通过两种方式，一种是由应用侧发

18、起（GetReceivedSms操作），WebService方式通信适配插件将所接收到的发往该应用的短信在响应中提交；第二种是由WebService方式通信适配插件通知应用侧有短信到达（notifySmsReception操作），短信内容包含在请求中。6.3.3. 数据类型DeliveryStatus含义：传送状态数据类型：枚举，定义如下：Delivered短消息已成功递交。DeliveryUncertain递交状态未知：例如，因为短消息被发送到另外一个网络。DeliveryImpossible无法成功发送；短消息在超时前无法被递交。MessageWaiting消息仍在排队等待递交。这是一个临

19、时状态，等待转换为前述的状态之一。DeliveryToTerminal短消息已发给终端。DeliveryNotificationNotSupported不支持短消息提交通知。KeyWordFilterFailed关键字过滤未通过。DeliveryInformation传送消息结构。定义如下：Address目的地址信息。发送状态。SMSMessage短消息信息Message短消息中的文本。SmsServiceActivationNumber与被调用的消息业务相关的号码，即，终端用来发送消息的目标地址。SenderAddressanyURI指示短消息发送者的名称，即作为消息发起者显示在用户终端上的

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

21、tinationAddress描述。对于可任意扩展服务代码的应用，应用可以通过ExtendCode填写应用内部的扩展码，MAS服务器需自动在其前面补充为该业务分配的长服务号码。对本接口的调用，MAS服务器应返回RequestIdentifier标识这次发送请求。如果消息的长度大于可支持的最大长度，此条消息将被分成若干条短消息进行发送。应用通过DeliverResultRequest告知是否需要返回状态报告。MAS根据要求用notifySmsDeliveryStatus接口返回状态报告。 sendSmsRequestApplicationID应用ID或插件的ID。DestinationAddre

22、ssesanyURI 0.unbounded短消息要被发送到的地址。群发短消息的最大数量为254。ExtendCode指由该应用填写的内部扩展号码。MAS服务器需自动补充为此业务分配的长服务号码。在短消息中发送的文本。消息编码类型。SendMethod发送消息选项。DeliveryResultRequestboolean指示是否需要网络侧返回递交状态报告。若无，则不返回。True表示需要网络侧返回递交状态报告，false表示不需要网络侧返回递交状态报告。sendSmsResponseRequestIdentifier标识一个特定的短消息发送请求。 SVC0004 - 不合法地址 SVC0006 - 不合法的组 SVC0280 - 消息过长 POL0003 地址超界 POL0006 - 组不被允许 POL0007 - 嵌套的组不被允许 POL0008 - 不允许支付GetSmsDeliveryStatus用于集团客户应用系统或应用插件查询短消息的发送状态。集团客户应用系统或应用插件通过requestIdentifier指定查询对应的发送请求，状态信息由DeliveryStatus返回。GetSmsDeliveryStatusRequest应用ID或插件ID。在发送短信时由WebService方式通信适配插件分配的发送请求标识。GetSmsDeliver