MAS2.0 WebService接口插件开发手册

中国移动代理服务器MAS V2.0

WebService接口插件

开发手册

深圳市嘉讯软件有限公司

2008年9月

中国移动代理服务器MAS V2.0 WebService接口开发手册

目录

1.

引言 ................................................................................................................................... 4 1.1. 编写目的 ................................................................................................................... 4 1.2. 背景说明 ................................................................................................................... 4 1.3. 相关术语与缩略语解释 ........................................................................................... 4 概述........................................................................................................................................... 4 运行环境 ................................................................................................................................... 5 接口描述 ................................................................................................................................... 5 4.1. 短信接口 ................................................................................................................... 5

4.1.1. 接口说明 ........................................................................................................... 5 4.1.2. 流程说明 ........................................................................................................... 5 4.1.3. 数据类型 ........................................................................................................... 6 4.2. 彩信接口 ................................................................................................................... 8

4.2.1. 接口说明 ........................................................................................................... 8 4.2.2. 流程说明 ........................................................................................................... 8 4.2.3. 数据类型 ........................................................................................................... 9 4.3. Wappush短信接口 ................................................................................................. 10

4.3.1. 接口说明 ......................................................................................................... 10 4.3.2. 流程说明 ......................................................................................................... 10 4.3.3. 数据类型 ......................................................................................................... 11 开发步骤 ................................................................................................................................. 12 5.1. 在Mas服务器新建一个企业应用 ........................................................................ 12 5.2. 启动企业应用 ......................................................................................................... 13 5.3. 访问并获取WebService方式通信适配插件服务地址 ....................................... 13 5.4. 客户端及服务端代码生成 ..................................................................................... 13 5.5. 接口开发及使用举例 ............................................................................................. 13

5.5.1. 短信接口 ......................................................................................................... 13

5.5.1.1. sendSms操作 .......................................................................................... 14 5.5.1.2. getSmsDeliveryStatus操作 .................................................................... 15 5.5.1.3. notifySmsDeliveryStatus操作 ................................................................ 16 5.5.1.4. getReceivedSms操作 ............................................................................. 16 5.5.1.5. notifySmsReception操作 ....................................................................... 17 5.5.2. 彩信接口 ......................................................................................................... 17

5.5.2.1. sendMessage操作................................................................................... 17 5.5.2.2. getMessageDeliveryStatus操作 ............................................................. 18 5.5.2.3. notifyMessageDeliveryReceipt操作 ...................................................... 19 5.5.2.4. getReceivedMessages操作 ..................................................................... 20 5.5.2.5. getMessage操作 ..................................................................................... 20 5.5.2.6. notifyMessageReception操作 ................................................................ 21 5.5.3. Wappush短信接口 ......................................................................................... 22

5.5.3.1. sendPush操作 ......................................................................................... 22

2.

3. 4.

5.

2

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

5.5.3.2. getPushDeliveryStatus操作.................................................................... 23 5.5.3.3. notifyPushDeliveryReceipt操作 ............................................................ 24

5.6. 常见错误及处理方式 ............................................................................................. 24 6. 参考文档 ................................................................................................................................. 25

3

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

1. 引言

1.1. 编写目的

本文档描述了MAS2.0基座WebService通信接口的使用方法，文档的使用对象为MAS开发人员、数字化部队、SI工程技术人员、SI开发人员、集团客户技术人员。

本文档的读者需要有一定的WebService相关知识。

1.2. 背景说明

1.3. 相关术语与缩略语解释

缩写词 MAS HTTP HTTPS SOAP UCA WS 英文解析 Mobile Agent Server Hypertext Transfer Protocol Secure HTTP Simple Object Access Protocol Unified Communication Agent WebService 中文解析 移动代理服务器 超文本传输协议 加密的HTTP协议 简单对象访问协议 统一通信代理 Web服务接口 2. 概述

开发环境WebService方式通信提供了对各种通信能力的统一封装，供集团客户应用系统和MAS服务器应用插件进行调用。同时，提供统一WebService方式封装也降低了si的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对si呈现简单的标准接口。WebService方式通信适配插件接口封装了以下移动通信能力： ? 短信 ? 彩信 ? wappush ? ussd(暂不可用) ? LBS(暂不可用)

此外，还提供基座与应用插件之间的插件管理功能接口。

MAS服务器应提供配置工具，指定对于某个集团客户应用系统或应用插件，通过WebService方式通信适配插件或数据库方式通信适配插件接入MAS服务器。

4

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

3. 运行环境

? MAS2.0基座运行环境 ? MAS管理平台环境

? WebService适配插件开关打开

4. 接口描述

4.1. 短信接口

4.1.1.

接口说明

集团客户应用系统和应用插件通过此接口收发短消息。WebService方式通信适配插件收到应用插件的发送请求后，通过MAS服务器基座中的SMS通信协议模块发送SMS；当从SMS通信协议模块收到SMS后，通过此接口将短消息发送给集团客户应用系统和应用插件。

4.1.2. 流程说明

短消息接口包括发送和接收两个流程。

应用系统或应用插件WebService方式通信适配插件应用发送短信sendSmsRequestsendSmsResponse应用主动获取短信发送状态getSmsDeliveryStatusRequestgetSmsDeliveryStatusResponse通知应用短信发送状态notifySmsDeliveryStatusRequestnotifySmsDeliveryStatusResponse 图5-2 短消息发送流程示意图

发送短信由应用系统或应用插件发起，通过sendSms操作实现。在提交短信发送请求

5

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

之后，应用侧可以主动获取短信发送状态（getSmsDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧短信发送状态（notifySmsDeliveryStatus操作）。

应用系统或应用插件WebService方式通信适配插件应用主动发起接收短信GetReceivedSmsRequestGetReceivedSmsResponse通知应用短信到达notifySmsReceptionRequestnotifySmsReceptionResponse 图5-3 短消息接收流程示意图

接收短信可以通过两种方式，一种是由应用侧发起（GetReceivedSms操作），WebService方式通信适配插件将所接收到的发往该应用的短信在响应中提交；第二种是由WebService方式通信适配插件通知应用侧有短信到达（notifySmsReception操作），短信内容包含在请求中。

4.1.3. 数据类型

DeliveryStatus 含义：传送状态

数据类型：枚举，定义如下： 参数 Delivered DeliveryUncertain 描述 短消息已成功递交。 递交状态未知：例如，因为短消息被发送到另外一个网络。 DeliveryImpossible MessageWaiting 无法成功发送；短消息在超时前无法被递交。 消息仍在排队等待递交。这是一个临时状态，等待转换为前述的状态之一。 DeliveryToTerminal DeliveryNotificationNotSupp短消息已发给终端。 不支持短消息提交通知。 6

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

orted KeyWordFilterFailed DeliveryInformation 含义：传送消息

数据类型：结构。定义如下： 参数 Address DeliveryStatus SMSMessage 含义：短消息信息

数据类型：结构。定义如下： 参数 Message SmsServiceActivationNumber 类型 xsd:string xsd: anyURI 描述 短消息中的文本。 与被调用的消息业务相关的号码，即，终端用来发送消息的目标地址。 SenderAddress xsd:anyURI 指示短消息发送者的名称，即作为消息发起者显示在用户终端上的名称。 MessageFormat MessageFormat 含义：消息编码类型 数据类型：枚举。定义如下： 参数 ASCII UCS2 GB18030 GB2312 Binary 描述 ASCII字符。 USC2格式的UniCode字符。 GB18030格式的中文字符。 GB2312格式的中文字符。 二进制短信，用十六进制字符串。 MessageFormat 编码格式。 类型 xsd: anyURI DeliveryStatus 描述 目的地址信息。 发送状态。 关键字过滤未通过。 7

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

SendMethodType 含义：发送选项

数据类型：枚举。定义如下： 参数 Normal Instant Long Structured 描述 普通短信 普通短信立即显示 长短信 长度小于160字节，但UDHI需置为1 4.2. 彩信接口

4.2.1.

接口说明

应用系统或应用插件调用发送接口给目的用户发送一条彩信。通信适配插件采用非同步的通知机制将彩信提交状态通知给应用系统或应用插件。对于彩信接收，可以由通信适配插件主动通知应用系统或应用插件有彩信到达，应用系统或应用插件也可通过接口从通信适配插件接收彩信。

4.2.2. 流程说明

应用系统或应用插件WebService方式通信适配插件应用发送彩信sendMessageRequestsendMessageResponse应用主动获取彩信发送状态getMessageDeliveryStatusRequestgetMessageDeliveryStatusResponse通知应用彩信发送状态notifyMessageDeliveryReceiptRequestnotifyMessageDeliveryReceiptResponse 图5-4 发送彩信流程示意图

8

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

发送彩信由应用系统或应用插件发起，通过sendMessage操作实现。在彩信发送之后，应用侧可以主动获取彩信发送状态（getMessageDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧彩信发送状态（notifyMessageDeliveryReceipt操作）。

应用系统或应用插件WebService方式通信适配插件应用主动发起接收彩信GetReceivedMessagesRequestGetReceivedMessagesResponse获取某一条彩信getMessageRequestgetMessageResponse通知应用彩信到达notifyMessageReceptionRequestnotifyMessageReceptionResponse 图5-5 接收彩信流程示意图

接收短信可以通过两种方式，一种是由应用侧发起（GetReceivedMessages操作），WebService方式通信适配插件将发往该应用的彩信的标识在响应中提交，应用侧获取标识之后，可以选择获取某一条彩信（getMessage操作）；第二种是由WebService方式通信适配插件通知应用侧有彩信到达（notifyMessageReception操作），在请求中包括彩信内容。

4.2.3. 数据类型

DeliveryStatus 数据类型：枚举 名称 DeliveredToNetwork DeliveryUncertain DeliveryImpossible MessageWaiting DeliveredToTerminal DeliveryNotificationNotSupported 描述 消息成功发送至网络 消息下发状态不确定 消息无法发送。 消息在队列中，尚未发送。 消息成功发送至终端。 不支持消息下发收到通知 9

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

MessagePriority 数据类型：枚举 名称 Default Low Normal High DeliveryInformation 数据类型：结构 参数 address deliveryStatus MessageReference 数据类型：结构 参数 messageIdentifier 类型 xsd:string 可选性 O M M O O 描述 指向某条彩信。如接收彩信为纯文本则此参数无效。 目的地址。 发送方地址。 彩信的标题。 优先级，缺省值为Normal。 若接收彩信为纯文本，则此参数为消息体内容，当此参数存在时，messageIdentifier 参数无效。 消息接收时间 类型 xsd:anyURI DeliveryStatus 描述 消息接收地址 发送状态 描述 缺省消息优先级 低的消息优先级 正常的消息优先级 高的消息优先级 messageServiceActivationNumber xsd:string senderAddress Subject Priority Message xsd:anyURI xsd:string xsd:string MessagePriority M dateTime MmsMessage 数据类型：结构 参数 bodyText Content xsd:dateTime O 类型 xsd: string xsd: string 可选性 M O 描述 彩信消息体的文本部分 与消息一起接收到的数据。MIME组包。 4.3. Wappush短信接口

4.3.1.

接口说明

应用系统或应用插件通过此接口发送WAP PUSH并获取PUSH发送状态。

4.3.2. 流程说明

10

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

到的数据。

5.5.2.5.2. 开发代码举例

输入：getMessageRequest 参数 ApplicationID messageRefIdentifier 参数 mmsMessage 类型 xsd:string xsd:string 类型 xsd: MmsMessage 可选性 M M 可选性 No 描述 应用ID或插件ID 消息标识 描述 彩信消息 输出：getMessageResponse 代码实现如下： Cmcc_mas_wbs_ServiceLocator cmcc_mas_wbs_ServiceLocator = new Cmcc_mas_wbs_ServiceLocator();

// 设置WebService方式通信适配插件服务地址

cmcc_mas_wbs_ServiceLocator.setcmcc_mas_wbsEndpointAddress(\方式通信适配插件服务地址\

// 生成客户端访问接口

Cmcc_mas_wbs_PortType cmcc_mas_wbs_PortType = cmcc_mas_wbs_ServiceLocator.getcmcc_mas_wbs();

// 接收彩信的请求

GetMessageRequest getMessageRequest = new GetMessageRequest(); // 设置应用ID或插件ID

getMessageRequest.setApplicationID(applicationID);

// 设置要接收的彩信的优先级，要求返回高于或等于该优先级的彩信。若未指定，则返回所有彩信

getMessageRequest.setMessageRefIdentifier(messageRefIdentifier); // 接收彩信（返回接收到的彩信信息） GetMessageResponse getMessageResponse =

cmcc_mas_wbs_PortType.getMessage(getMessageRequest);

5.5.2.6. notifyMessageReception操作 5.5.2.6.1. 操作说明

用于通知应用系统或应用插件接收到的彩信。在请求中包含彩信的所有信息及数据。

5.5.2.6.2. 开发代码举例

输入：notifyMessageReceptionRequest 参数 ApplicationID Message Content 类型 xsd:string MessageReference xsd: string 可选性 M M O 描述 应用ID或插件ID 与接收消息相关的所有信息 与消息一起接收到的数据。 输出：notifyMessageReceptionResponse

21

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

5.5.3. Wappush短信接口

5.5.3.1. sendPush操作 5.5.3.1.1. 操作说明

本操作请求把一个消息的URL推送到一组目标地址，并且返回一个标识requestIdentifier以唯一标识这个消息发送请求。应用系统或应用插件可以用requestIdentifier查询消息发送状态。

5.5.3.1.2. 开发代码举例

输入：sendPushRequest 参数 ApplicationID addresses targetURL ExtendCode 类型 xsd:string xsd:anyURI [1..unbounded] xsd:anyURI xsd:string 可选性 M M O O 描述 应用ID或插件ID。 推送的目标终端设备的地址集 推送的URL连接 指由该应用系统或应用插件填写的扩展号码。MAS服务器需自动补充为此业务分配的服务代码。 主题（可选） 指示是否需要网络侧返回递交状态报告。true表示需要返回状态报告，false表示不需要。若无，则不返回。 subject receiptRequest xsd:string xsd:boolean O O 输出：sendPushResponse 参数 requestIdentifier 类型 xsd:string 可选性 M 说明 用来标识一次消息发送。 代码实现如下： Cmcc_mas_wbs_ServiceLocator cmcc_mas_wbs_ServiceLocator = new Cmcc_mas_wbs_ServiceLocator(); // 设置WebService方式通信适配插件服务地址 cmcc_mas_wbs_ServiceLocator.setcmcc_mas_wbsEndpointAddress(\方式通信适配插件服务地址\// 生成客户端访问接口 Cmcc_mas_wbs_PortType cmcc_mas_wbs_PortType = cmcc_mas_wbs_ServiceLocator.getcmcc_mas_wbs(); // 推送请求 SendPushRequest sendPushRequest = new SendPushRequest(); // 设置推送的目标终端设备的地址集 sendPushRequest.setAddresses(addresses); // 设置应用ID或插件ID sendPushRequest.setApplicationID(applicationID); 22

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

// 设置由该应用系统或应用插件填写的扩展号码。MAS服务器需自动补充为此业务分配的服务代码 sendPushRequest.setExtendCode(extendCode); // 设置是否需要网络侧返回递交状态报告。true表示需要返回状态报告，false表示不需要。若无，则不返回 sendPushRequest.setReceiptRequest(receiptRequest); // 设置主题（可选） sendPushRequest.setSubject(subject); // 设置推送的URL连接 sendPushRequest.setTargetURL(targetURL); // 发送PUSH消息（返回发送状态） SendPushResponse sendPushResponse = cmcc_mas_wbs_PortType.sendPush(sendPushRequest); 5.5.3.2. getPushDeliveryStatus操作 5.5.3.2.1. 操作说明

应用系统或应用插件通过本操作查询先前提交的WAP PUSH请求的发送状态。

5.5.3.2.2. 开发代码举例

输入：getPushDeliveryStatusRequest 参数 ApplicationID requestIdentifier 参数 result 类型 xsd:string xsd:string 类型 可选性 M M 可选性 说明 应用ID或插件ID。 标识一次消息推送请求。 说明 推送状态 输出：getPushDeliveryStatusResponse DeliveryInformation M [1 .. unbounded] 代码实现如下： Cmcc_mas_wbs_ServiceLocator cmcc_mas_wbs_ServiceLocator = new Cmcc_mas_wbs_ServiceLocator(); // 设置WebService方式通信适配插件服务地址 cmcc_mas_wbs_ServiceLocator.setcmcc_mas_wbsEndpointAddress(\方式通信适配插件服务地址\// 生成客户端访问接口 Cmcc_mas_wbs_PortType cmcc_mas_wbs_PortType = cmcc_mas_wbs_ServiceLocator.getcmcc_mas_wbs(); // 获取发送状态的请求 GetPushDeliveryStatusRequest getPushDeliveryStatusRequest = new GetPushDeliveryStatusRequest(); // 设置应用ID或插件ID getPushDeliveryStatusRequest.setApplicationID(applicationID); // 设置请求标识 getPushDeliveryStatusRequest.setRequestIdentifier(requestIdentifier); 23

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

// 获取PUSH发送状态（返回发送状态集合） org.csapi.www.schema.wap.DeliveryInformation[] deliveryInformation = cmcc_mas_wbs_PortType.getPushDeliveryStatus(getPushDeliveryStatusRequest); 5.5.3.3. notifyPushDeliveryReceipt操作 5.5.3.3.1. 操作说明

本操作由适配插件向应用侧通知推送结果。

5.5.3.3.2. 开发代码举例

输入：notifyPushDeliveryReceiptRequest 参数名称 requestIdentifier deliveryStatus 类型 xsd:string 可选性 M 说明 标识一次消息推送请求。 推送状态 DeliveryInformation M [1 .. unbounded] 输出：notifyPushDeliveryReceiptResponse

5.6. 常见错误及处理方式

业务异常：

? SVC0001 - 业务错误

? SVC0002 - 不合法的输入值（如接收地址为空） ? SVC0004 - 不合法地址 ? SVC0006 - 不合法的组 ? SVC0280 - 消息过长 ? SVC0281 - 未知的数据格式 ? SVC0283 - 不支持下发到达通知 策略异常：

? POL0001 - 策略错误 ? POL0003 - 地址超界 ? POL0006 - 组不被允许 ? POL0007 - 嵌套的组不被允许 ? POL0008 - 不允许支付 ? POL0900 - 不支持群发

? POL0906 - 不被允许操作或者请求（如不支持OA业务能力短信发送、应用ID

或插件ID不存在等） ? POL0907 - 不允许群发

24

深圳市嘉讯软件有限公司

中国移动代理服务器MAS V2.0 WebService接口开发手册

? POL0908 - 短信消息超长

? POL0910 - 通信未建立（如短信网关连接不正常、彩信网关连接不正常） ? POL9001 - 超过群发提交的数量限制 ? POL9002 - 禁止时间段不允许提交短信

6. 参考文档

<<中国移动移动代理服务器（MAS）系统接口规范2.0.doc>> << MAS2.0安装手册.doc>>

<< MAS2.0二次开发手册(总则).doc>>

25

深圳市嘉讯软件有限公司

本文来源：https://www.bwwdw.com/article/hc5g.html