WebService 接口通信文档

最新推荐文章于 2024-08-22 12:21:19 发布

echoHelloWord

最新推荐文章于 2024-08-22 12:21:19 发布

阅读量5.3k

点赞数

分类专栏：开发应用

本文链接：https://blog.csdn.net/echocdzh/article/details/50215451

版权

开发应用专栏收录该内容

170 篇文章 0 订阅

订阅专栏

1.1. WebService方式通信适配插件接口

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

ü 短信

ü 彩信

ü wap

ü ussd

ü LBS

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

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

1.1.1.Web服务公共数据定义

5.2.1.1 命名空间

公共数据类型的命名空间参见：

http://www.csapi.org/schema/common/v2_0

公共异常的命名空间参见：

http://www.csapi.org/wsdl/common_faults/v2_0

5.2.1.2 WEB服务调用方式

WEB服务应支持HTTP上的SOAP调用，使集团客户应用系统以及各插件可通过HTTP方式与服务器进行通信。

5.2.1.3 XML数据类型

XML数据类型参见XML Schema（W3C Recommendation (2 May 2001): "XML Schema Part2: Datatypes"）。

5.2.1.4 XML Schema数据类型定义

5.2.1.4.1. TimeMetricsValues

数据类型为枚举型。

值	描述
Millisecond	毫秒
Second	秒
Minute	分
Hour	小时
Day	日
Week	星期
Month	月
Year	年

5.2.1.4.2. TimeMetric

数据类型为结构。

名称	类型	描述
Metric	TimeMetricValues	计量单位
Units	xsd:int	数值

5.2.1.4.3. ServiceError

数据类型为结构。

名称	类型	描述
MessageId	xsd:string	消息标识
Text	xsd:string	消息说明
Variables	xsd:string [0..unbounded]	变量

5.2.1.4.4. SimpleReference

数据类型为结构。

名称	类型	描述
Endpoint	xsd:anyURI	端口
InterfaceName	xsd:string	接口名称
Correlator	xsd:string	关联标识

5.2.1.4.5. CMAbility

数据类型为枚举。

值	描述
SMSbility	对短信能力的需求
MMSAbility	对彩信能力的需求
WAPAbility	对WAP能力的需求
USSDAbility	对USSD能力的需求
LBSAbility	对LBS能力的需求
GPRSAbility	对GPRS能力的需求

5.2.1.4.6. MessageNotificationType

用于集团客户应用系统和应用插件通知通信能力需求及所提供的web服务端地址。

数据类型为结构：

名称	类型	描述
CMAbility	CMAbility	对应某一个通信能力
WSURI	xsd:anyURI	对应该通信能力，应用系统或插件提供的WEB服务端地址

5.2.1.5 公共异常定义

5.2.1.5.1. 业务异常

业务异常消息使用保留的消息标识符‘SVC’，并使用从0001到0999的号码来定义。其中0001至0199被保留作公共差错定义，0200至0999作为其它Web Service指定用途。从‘1000’至‘9999’为自定义。

名称	类型	描述
MessageId	xsd:string	消息标识符，前缀为SVC
Text	xsd:string	消息文本，可变可替代部分用%来标识
Variables	xsd:string [0..unbounded]	替代文本字串中的可变部分

SVC0001: 业务错误

名称	描述
Message Id	SVC0001
Text	发生了一个业务错误。错误代码是%1
Variables	%1－来自业务的错误码。

SVC0002: 不合法的输入值

名称	描述
Message Id	SVC0002
Text	消息部分%1有不合法的输入值。
Variables	%1－消息部分。

SVC0003:不合法的输入值包含部分合法值

名称	描述
Message Id	SVC0003
Text	消息部分%1有不合法的输入值，%2是合法值。
Variables	%1－消息部分； %2－合法值列表。

SVC0004: 不合法地址

名称	描述
Message Id	SVC0004
Text	消息部分%1未提供合法地址。
Variables	%1－消息部分。

SVC0005:重复关联符

名称	描述
Message Id	SVC0005
Text	消息部分%2中描述的关联符%1是重复的。
Variables	%1－关联符。 %2－消息部分。

SVC0006: 不合法的组

名称	描述
Message Id	SVC0006
Text	消息部分%2中的组%1不是一个合法的组。
Variables	%1－不合法的组的标识符。 %2－消息部分。

SVC0902:因内容过滤，被拒绝

名称	描述
Message Id	SVC0902
Text	因内容过滤，被拒绝
Variables	无。

5.2.1.5.2. 策略异常

策略异常消息使用保留的消息标识符‘POL’，并使用从0001到0999的号码来定义。其中0001至0199被保留作公共差错定义，0200至0999作为其它Web Service 指定用途。从‘1000’至‘9999’为自定义。

名称	类型	描述
MessageId	xsd:string	消息标识符，前缀为POL
Text	xsd:string	消息文本，可变可替代部分用%来标识。
Variables	xsd:string [1..unbounded]	替代文本字串中的可变部分。

POL0001:策略错误

名称	描述
Message Id	POL0001
Text	发生了一个策略错误。错误代码是%1。
Variables	%1—来自业务的错误码。

POL0003:过多的地址

名称	描述
Message Id	POL0003
Text	在消息部分%1中描述了过多的地址。
Variables	%1－消息部分。

POL0004:不支持无限制的通知请求

名称	描述
Message Id	POL0004
Text	不支持无限制的通知请求。
Variables	无。

POL0005:请求了过多的通知

名称	描述
Message Id	POL0005
Text	请求了过多的通知。
Variables	无。

POL0006:组地址不被允许

名称	描述
Message Id	POL0006
Text	在消息部分%1中描述的组不被允许。
Variables	%1－消息部分。

POL0007:嵌套的组不被允许

名称	描述
Message Id	POL0007
Text	在消息部分%1中描述的嵌套的组不被允许。
Variables	%1－消息部分。

POL0009:请求的频率不合法

名称	描述
Message Id	POL0009
Text	请求的频率不合法。
Variables	无。

POL0900: 不支持群发

名称	描述
Message Id	POL0900
Text	不支持群发请求。
Variables	无。

POL0903: 超过状态保留时长

名称	描述
Message Id	POL0903
Text	超过状态保留时长。
Variables	无。

POL0904: 超过流量门限

名称	描述
Message Id	POL0904
Text	超过流量门限。
Variables	无。

POL0905: 不被支持操作或者请求

名称	描述
Message Id	POL0905
Text	系统不支持此API调用。
Variables	无。

POL0906: 不被允许操作或者请求

名称	描述
Message Id	POL0906
Text	不被允许操作或者请求。
Variables	无。

POL0907: 不允许群发请求

名称	描述
Message Id	POL0907
Text	不允许群发请求。
Variables	无。

POL0908: 短信消息超长

名称	描述
Message Id	POL0908
Text	短信消息超长。
Variables	无。

POL0910: 超过消息上限

名称	描述
Message Id	POL0910
Text	超过消息上限。
Variables	无。

5.2.1.6 AnyUri格式说明

关于anyURI中各类型的格式定义如下：

类型	格式	描述
电话号码	tel:电话号码	表示接收者是一个电话号码
群组	tel:组名称;type=grp	表示接收者是一个群组，用于群发，需要与基座中的地址本管理模块配合使用。
部门	tel:部门名称;type=dpt	表示接收者是一个部门，用于群发，需要与基座中的地址本管理模块配合使用。
Web服务地址	http:URL	URL

号码、群组、部门可以组合使用，中间用一个“,”号分开。

其它遵循以下标准

RFC 2396 Uniform Resource Identifiers (URI): GenericSyntax

RFC 3966 The tel URI for Telephone Numbers

http://www.w3.org/2001/XMLSchema.dtd

1.1.2.插件管理接口

5.2.2.1 接口说明

插件管理接口实现对应用插件的注册、注销、暂停和恢复，各插件通过此接口报告插件状态。插件管理具体内容包括：

ü 插件的注册、注销、启用、暂停

ü 插件状态报告

ü 业务鉴权

ü 业务性能通知

WebService方式通信适配插件作为基座插件管理模块的代理，实现插件管理相关操作信息的处理和转发。

5.2.2.2 流程说明

插件管理流程如下：

图5-1 插件管理流程示意图

MAS服务器系统中的应用插件必须注册通过后方可使用，WebService方式通信适配插件将该注册请求转发到插件管理模块并获得结果，将结果封装在响应消息中返回给应用插件，注册及响应过程通过APRegistration操作实现。

应用插件注册通过后，要周期性地进行状态汇报并获取响应，状态报告及响应过程通过APStatusRep操作完成。

插件分为提供Web服务端和不提供Web服务端两种。对于提供Web服务端的情况，需在插件注册操作中指明服务端的URL，插件管理模块对该插件的所有后续管理操作均通过调用该服务端的操作实现；对于不提供Web服务端的插件，插件管理模块对该插件的所有后续管理操作均通过APStatusRep的响应消息带回。

在应用插件运行过程中，根据从MAS统一服务平台得到的业务能力信息，插件管理模块可以主动地发出命令，暂停或恢复特定的插件，这些指令经WebService方式通信适配插件通知给应用插件，通过APStatusRep、PauseAP和RecoveryAP操作实现。

对于提供服务端和不提供服务端的插件，暂停和恢复流程分别如下图所示：

图5-1 插件暂停及恢复流程

MAS服务器在运行过程中，将根据业务管理的需求，与MAS统一服务平台之间进行业务鉴权和业务性能数据上报，而鉴权数据和业务性能数据需要由应用插件提供。因此，MAS服务器需要从应用插件获取原始的鉴权数据和业务性能数据，通过APStatusRep、APSvcCfgRep、APSvcAuthentic、APSvcPerfCmd和APSvcPerfReport操作实现。

对于提供服务端和不提供服务端的插件，业务鉴权和业务性能数据上报流程分别如下图所示：

图5-3 业务鉴权和业务性能数据上报流程

在应用插件结束之前，应用插件主动发起注销操作APLogOut。

考虑到一个应用插件可能包含多个进程，因此在上述流程中，注册、状态上报、注销、业务鉴权和业务性能数据上报为进程级，而暂停和恢复为插件级。

当插件管理模块发现插件进程异常或资源占用超过阀值时，并不停止该进程，而是提示告警给指定人员。

应用插件的状态图如下图所示：

图5-2 应用插件状态示意图

5.2.2.3 数据类型

注册结果：APRegResult

数据结构：枚举

名称	描述
success	注册成功
illegalAP	插件不被允许，注册失败
CMAbilityNotSup	不支持所要求的通信能力，注册失败
repeatedReg	重复注册，注册成功
svcAddrMismatch	注册请求中的插件Web服务端地址与之前的同一插件其它进程注册请求中的插件Web服务端地址不一致，注册失败。

AP运行状态：APStatusType

数据结构：枚举

名称	描述
Normal	状态正常
OutofActiveTime	超过有效期
NeedRegistration	未注册，需要先注册
OutofService	已经注销
Paused	已暂停
Closed	插件进程已被mas服务器强行关闭
WaitingforConfirm	插件的注册请求等待审批中

注销结果：APLogoutResult

数据结构：枚举

名称	描述
success	注销成功
illegalAPid	插件id不合法，注销失败
repeatedLogout	重复注销请求

5.2.2.4 接口定义

5.2.2.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，若对应某通信能力，Web URL不填，表示对于该应用能力，应用插件不提供服务端。
APWSURI	xsd: anyURI	O	应用插件对应的WEB服务端URL，若无，则表示该应用插件不提供服务端。

输出：APRegistrationRsp

参数	类型	可选性	描述
RegResult	APRegResult	M	注册响应结果
NextInterval	xsd:int	M	表示AP的后续状态上报时间间隔（单位为秒）

差错：

业务异常：

ü SVC0001 - 业务错误.

策略异常：

ü POL0001 - 策略错误.

5.2.2.4.2. 插件状态信息上报

由应用插件AP发起，报告插件的状态。

操作：APStatusRep

业务触发条件：在插件运行过程中，需要周期性地上报自己的运行状态。上报周期可以由MAS服务器进行控制。在状态上报响应消息中，MAS服务器将后续状态上报时间间隔反馈给AP，收到响应之后AP按照这个间隔上报插件状态。对于不提供服务端的应用插件，MAS服务器插件管理模块将需要应用插件执行的管理命令包含在状态上报响应消息中，包括暂停、恢复、业务鉴权通知、业务性能上报通知。

输入：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	插件的后续上报时间间隔（单位为秒），不填表示同上次时间间隔
ApSvcAuthType	xsd:string [0..unbounded]	O	仅对于不提供服务端的应用插件有效，表示要求插件立即进行业务鉴权。
ApSvcPerfCmdType	xsd:string [0..unbounded]	O	仅对于不提供服务端的应用插件有效，表示要求插件进行业务性能数据上报。

差错：

业务异常：

ü SVC0002 - 不合法的输入值.

策略异常：

ü POL0001 - 策略错误.

ApSvcAuthType定义：

ApSvcAuthType中包含插件管理模块的业务鉴权要求，格式为“订购编码:订购关系信息类型”。应用插件在收到APStatusRepRsp后，需判断其中的ApSvcAuthType字段信息，若有业务鉴权要求时，应用插件应立即按要求通过APSvcCfgRep发起业务鉴权。

例如，若要求移动办公插件（开通短信和彩信通信能力，无服务端）进行鉴权，上报订购关系变量，则在ApSvcAuthType填写812100010002:2。

ApSvcPerfCmdType定义：

ApSvcPerfCmdType包含插件管理模块的业务性能数据上报请求，格式为：“性能数据编码:业务性能上报统计的起始和结束时间”。其中，统计起始和结束时间字段的格式为“yyyymmddHHmmss, yyyymmddHHmmss”。应用插件在收到APStatusRepRsp后，需判断其中的ApSvcPerfCmdType字段信息，若有业务性能数据上报要求时，应用插件按照指令中的起始和结束时间统计性能数据，并在到达ApSvcPerfCmdType中所要求的性能统计结束时间之后，通过APSvcPerfReport发送性能数据。

5.2.2.4.3. 插件发起业务鉴权

由应用插件AP根据APStatusRep中的指令发起，报告插件的订购关系信息信息。

操作：APSvcCfgRep

业务触发条件：对于无服务端的应用插件，当收到的状态报告响应APStatusRepRsp中的ApSvcAuthType字段要求插件进行业务鉴权时，需立即按要求发起业务鉴权。插件业务鉴权的目的是为MAS服务器提供业务鉴权的原始数据，供MAS服务器与统一服务平台鉴权使用。

输入：APSvcCfgRepReq

参数	类型	可选性	描述
APid	xsd:string	M	AP插件的标识
SvcCfgInfo	xsd:string [0..unbounded]	M	业务订购关系信息，格式及定义参见“订购关系信息”一节

输出：APSvcCfgRepRsp

参数	类型	可选性	描述
ACK	xsd:boolean	M	true表示成功，false表示失败。

差错

业务异常：

· SVC0001 - 业务错误.

策略异常：

· POL0001 - 策略错误.

5.2.2.4.4. 插件管理模块发起业务鉴权

对于具备web服务端的应用插件，插件管理模块通过此接口获取应用插件的业务订购关系信息。

操作：APSvcAuthentic

业务触发条件：对于具备web服务端的应用插件，MAS服务器根据自身的业务鉴权请求需要，通过此接口向应用插件发起请求，请求获取插件的订购关系信息，插件需根据请求中的具体要求返回对应的订购关系信息。

输入：APSvcAuthenticReq

参数	类型	可选性	描述
Apid	xsd: string	M	AP插件的标识
ApSvcAuthType	xsd: string [0..unbounded]	M	要求返回的鉴权数据类型

输出：APSvcAuthenticRsp

参数	类型	可选性	描述
APid	xsd:string	M	AP插件的标识
ApSvcAuthResult	xsd:string [0..unbounded]	M	业务订购关系信息，格式及定义参见“订购关系信息”一节

ApSvcAuthType定义：

ApSvcAuthType中包含插件管理模块的业务鉴权要求，格式为“订购编码:订购关系信息类型”。应用插件在收到APSvcAuthenticReq后，需判断其中的ApSvcAuthType字段信息，并按要求通过APSvcAuthenticRsp返回对应的订购关系信息。

例如，若要求移动办公插件（开通短信和彩信通信能力，无服务端）返回该业务的订购关系变量，则在ApSvcAuthType填写812100010002:2。

5.2.2.4.5. 业务性能上报通知

对于有WEB服务端的应用插件，插件管理模块通过此接口通知应用插件需进行业务性能上报。

操作：APSvcPerfCmd

业务触发条件：MAS服务器根据自身的业务性能上报需要，通过此接口向应用插件发起请求，请求获取该应用插件的业务性能信息，应用插件需根据要求统计对应的业务性能信息，并通过APSvcPerfReport操作上报业务性能信息。

输入：APSvcPerfCmdReq

参数	类型	可选性	描述
Apid	xsd: string	M	AP插件的标识
ApSvcPerfCmdType	xsd: string [0..unbounded]	M	业务性能数据统计要求

输出：APSvcPerfCmdRsp

无。

ApSvcPerfCmdType定义：

ApSvcPerfCmdType为插件管理模块的业务性能数据统计请求，格式为：“性能数据编码:业务性能上报统计的起始和结束时间”。其中，统计起始和结束时间字段的格式为“yyyymmddHHmmss, yyyymmddHHmmss”。应用插件在收到APSvcPerfCmdReq后，需判断其中的ApSvcPerfCmdType字段信息，并按照指令中的起始和结束时间统计性能数据，并在到达ApSvcPerfCmdType中所要求的性能统计结束时间之后，通过APSvcPerfReport发起性能数据上报。

5.2.2.4.6. 业务性能数据上报

操作：APSvcPerfReport

业务触发条件：此业务有两个触发条件，1）对于有Web服务端的应用插件，在收到通过APSvcPerfCmd操作发出的业务性能上报通知后；2）对于无Web服务端的应用插件，在收到APStatusRepRsp中的ApSvcPerfCmdType后。应用插件在上述两个触发条件下，应统计对应的业务性能信息。对于有Web服务端的应用插件，在到达APSvcPerfCmd中所要求的性能统计结束时间之后，通过APSvcPerfReport发送性能数据；对于无Web服务端的应用插件，在到达APStatusRepRsp中ApSvcPerfCmdType字段所要求的性能统计结束时间之后，通过APSvcPerfReport发送性能数据。

输入：APSvcPerfReportReq

参数	类型	可选性	描述
Apid	xsd: string	M	AP插件的标识
ApSvcPerfData	xsd: string [0..unbounded]	M	业务性能数据

输出：APSvcPerfReportRsp

无。

ApSvcPerfData定义：

该项格式为：性能数据编码;性能数据;统计的起始结束时间

第一部分格式及定义参见“性能数据编码”一节的说明；

第二部分为多项’业务性能数据’的组合，各项业务性能数据之间用空格区分，如:12k 20 30对应着第一部分中的“性能编码”的000100030002，表示：GPRS流量为12k, 开户用户数为30人，活跃用户数为20人。

第三部分为统计的起始结束时间，具体格式为：yyyymmddHHmmss,yyyymmddHHmmss。

5.2.2.4.7. 注销插件

由应用插件AP发起进行注销插件进程。

操作：APLogOut

业务触发条件：应用插件AP的进程在结束之前，调用此接口进行注销。注销后的进程若重新使用，需要重新进行注册。

输入：APLogOutReq

参数	类型	可选性	描述
APid	xsd:string	M	AP插件的标识
APPid	xsd:int	M	AP插件的PID

输出：APLogOutRsp

参数	类型	可选性	描述
LogoutResult	APLogoutResult	M	注销响应结果

差错：

业务异常：

ü SVC0001 - 业务错误.

策略异常：

ü POL0001 - 策略错误.

5.2.2.4.8. 插件暂停

此接口用于暂停AP的业务功能，由WebService插件发起。只有当应用插件有Web服务端的情况，才能使用该操作。

操作：PauseAP

WebService方式通信适配插件根据插件管理模块的要求，暂停AP的业务功能。如果插件要重新启用，需要在注销后由插件重新发起注册请求；或者由WebService插件重新启动AP。

输入：PauseAPReq

参数	类型	可选性	描述
APid	xsd:string	M	AP插件的标识

输出：PauseAPRsp

参数	类型	可选性	描述
ACK	xsd:Boolean	M	true表示成功，false表示失败。

差错：

业务异常：

ü SVC0001 - 业务错误.

策略异常：

ü POL0001 - 策略错误.

5.2.2.4.9. 插件恢复

此接口用于恢复AP的业务功能，由WebService方式通信适配插件发起，仅当应用插件有Web服务端时有效。

操作：RecoveryAP

WebService方式通信适配插件根据业务要求，恢复已暂停的AP的业务功能。

输入：RecoveryAPReq

参数	类型	可选性	描述
APid	xsd:string	M	AP插件的标识

输出：RecoveryAPRsp

参数	类型	可选性	描述
ACK	xsd:Boolean	M	true表示成功，false表示失败。

差错：

业务异常：

ü SVC0001 - 业务错误.

策略异常：

ü POL0001 - 策略错误.

1.1.3.应用系统服务通知接口

5.2.3.1 接口说明

此接口用于集团客户应用系统完成对短消息、多媒体消息、定位和USSD相关的服务通知。集团客户应用系统通过此接口通知WebService方式通信适配插件各通信能力对应的服务端URL，以及服务端是否开启或关闭。

5.2.3.2 流程说明

图5-3 应用系统服务通知流程示意图

对于应用系统支持服务端的情况，需要通过startNotification操作通知WebService方式通信适配插件各个通信能力对应的服务端URL，之后WebService方式通信适配插件可以调用服务端向应用系统发出各种消息通知，直到应用系统通过stopNotification通知服务端不可用为止。

应用系统可以多次执行startNotification和stopNotification操作，WebService方式通信适配插件以最后一次的通知为准。

WebService方式通信适配插件在向应用侧发出消息通知失败时，采用指数后退方式重试三次。若重试后仍失败，则抑制后续的所有消息通知。

5.2.3.3 接口定义

操作：startNotification

startNotification调用由应用系统发起，通知WebService方式通信适配插件，应用系统的服务端已经开启。应用系统在MessageNotification参数中注明各通信能力对应的服务端URL。

输入：startNotificationRequest

参数	类型	可选性	描述
ApplicationId	xsd:string	M	EC应用标识
MessageNotification	MessageNotificationType[]	M	应用的各通信能力对应的Web服务URL，若对应某通信能力，Web URL不填，表示对于该应用能力，应用插件不提供服务端，或服务端不可用。

输出：startNotificationResponse

无。

差错：

业务异常：

ü SVC0001 - 业务错误.

ü SVC0002 - 不合法的输入值.

ü SVC0005 - 重复关联符.

策略异常：

ü POL0001 - 策略错误.

操作：stopNotification

stopNotification调用由应用系统发起，通知WebService方式通信适配插件该应用系统不再提供服务端。

输入：stopNotificationRequest

参数	类型	可选性	描述
ApplicationId	xsd: string	M	EC应用ID

输出：stopNotificationResponse

无。

差错

业务异常：

ü SVC0001 - 业务错误.

ü SVC0002 - 不合法的输入值.

策略异常：

ü POL0001 - 策略错误.

1.1.4.短消息接口

5.2.4.1 接口说明

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

5.2.4.2 流程说明

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

图5-4 短消息发送流程示意图

发送短信由应用系统或应用插件发起，通过sendSms操作实现。在提交短信发送请求之后，应用侧可以主动获取短信发送状态（getSmsDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧短信发送状态（notifySmsDeliveryStatus操作）。

图5-5 短消息接收流程示意图

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

5.2.4.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

5.2.4.4 接口定义

5.2.4.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	发送消息选项。
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方式通信适配插件分配的发送请求标识。

输出：GetSmsDeliveryStatusResponse

参数	类型	可选性	描述
DeliveryStatus	DeliveryInformation[0..unbounded]	M	列出短消息发送状态。

差错：

业务异常：

ü SVC0001 - 业务错误.

ü SVC0002 - 不合法的输入值.

策略异常：

ü POL0001 - 策略错误

5.2.4.4.2. 短消息通知

操作：notifySmsReception

通信适配插件收到发送到特定地址的短消息时，调用本接口，通知集团客户应用系统和应用插件有短消息到达，前提是应用系统或插件具备Web服务端。

输入：notifySmsReceptionRequest

参数	类型	可选性	描述
Message	SmsMessage	M	在短消息中发送的文本。

输出：notifySmsReceptionResponse

无。

差错：

无。

操作：notifySmsDeliveryStatus

应用系统或应用插件通过通信适配插件发送了短消息之后，通信适配插件对该短消息的发送分配了一个标识符RequestIdentifier。当通信适配插件获得状态报告后，调用本接口将短消息的发送状态报告给应用侧，前提是应用系统或插件具备Web服务端。状态信息在DeliveryInfomation中具体描述。

输入：notifySmsDeliveryStatusRequest

参数	类型	可选性	描述
RequestIdentifier	xsd:string	M	标识一个短消息发送请求。
DeliveryInformation	deliveryInformation[0..unbounded]	M	短消息递交状态参数。