infoXMAS API接口说明SOAP.docx
《infoXMAS API接口说明SOAP.docx》由会员分享，可在线阅读，更多相关《infoXMAS API接口说明SOAP.docx（69页珍藏版）》请在冰点文库上搜索。
infoXMASAPI接口说明SOAP
目录
1WebService方式通信适配插件接口概述及总体说明1-1
1.1Web服务公共数据定义1-1
1.1.1WEB服务调用方式1-1
1.1.2XML数据类型1-1
1.1.3公共异常定义1-3
1.1.4AnyUri格式说明1-9
1.1.5插件管理接口1-10
1.1.6接口定义1-13
1.1.7插件状态信息上报1-14
1.1.8注销插件1-15
1.1.9插件暂停1-16
1.1.10应用系统服务通知接口1-17
1.1.11接口定义1-18
1.1.12短消息接口1-19
1.1.13数据类型1-21
1.1.14接口定义1-23
1.1.15服务策略1-27
1.1.16多媒体消息接口1-28
1.1.17接口定义1-31
1.1.18定位接口1-35
1.1.19接口定义1-40
1.1.20接口定义1-48
1WebService方式通信适配插件接口概述及总体说明
WebService方式通信适配插件提供了对各种通信能力的统一封装，供集团客户应用系统和MAS服务器应用插件进行调用。
同时，提供统一WebService方式封装也降低了si的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对si呈现简单的标准接口。
WebService方式通信适配插件接口封装了以下移动通信能力：
●短信
●彩信
●wap
●ussd
●LBS
此外，还提供基座与应用插件之间的插件管理功能接口。
MAS服务器应提供配置工具，指定对于某个集团客户应用系统或应用插件，通过WebService方式通信适配插件或数据库方式通信适配插件接入MAS服务器。
1.1Web服务公共数据定义
1.1.1WEB服务调用方式
WEB服务应支持HTTP上的SOAP调用，使集团客户应用系统以及各插件可通过HTTP方式与服务器进行通信。
1.1.2XML数据类型
XMLSchema数据类型定义
TimeMetricsValues
数据类型为枚举型。
值
描述
Millisecond
毫秒
Second
秒
Minute
分
Hour
小时
Day
日
Week
星期
Month
月
Year
年
TimeMetric
数据类型为结构。
名称
类型
描述
Metric
TimeMetricValues
计量单位
Units
xsd:
int
数值
ServiceError
数据类型为结构。
名称
类型
描述
MessageId
xsd:
string
消息标识
Text
xsd:
string
消息说明
Variables
xsd:
string[0..unbounded]
变量
SimpleReference
数据类型为结构。
名称
类型
描述
Endpoint
xsd:
anyURI
端口
InterfaceName
xsd:
string
接口名称
Correlator
xsd:
string
关联标识
CMAbility
数据类型为枚举。
值
描述
SMSbility
对短信能力的需求
MMSAbility
对彩信能力的需求
WAPAbility
对WAP能力的需求
USSDAbility
对USSD能力的需求
LBSAbility
对LBS能力的需求
GPRSAbility
对GPRS能力的需求
MessageNotificationType
用于集团客户应用系统和应用插件通知通信能力需求及所提供的web服务端地址。
数据类型为结构：
名称
类型
描述
CMAbility
CMAbility
对应某一个通信能力
WSURI
xsd:
anyURI
对应该通信能力，应用系统或插件提供的WEB服务端地址
1.1.3公共异常定义
业务异常
业务异常消息使用保留的消息标识符‘SVC’，并使用从0001到0999的号码来定义。
其中0001至0199被保留作公共差错定义，0200至0999作为其它WebService指定用途。
从‘1000’至‘9999’为自定义。
名称
类型
描述
MessageId
xsd:
string
消息标识符，前缀为SVC
Text
xsd:
string
消息文本，可变可替代部分用%来标识
Variables
xsd:
string[0..unbounded]
替代文本字串中的可变部分
SVC0001:
业务错误
名称
描述
MessageId
SVC0001
Text
发生了一个业务错误。
错误代码是%1
Variables
%1－来自业务的错误码。
SVC0002:
不合法的输入值
名称
描述
MessageId
SVC0002
Text
消息部分%1有不合法的输入值。
Variables
%1－消息部分。
SVC0003:
不合法的输入值包含部分合法值
名称
描述
MessageId
SVC0003
Text
消息部分%1有不合法的输入值，%2是合法值。
Variables
%1－消息部分；
%2－合法值列表。
SVC0004:
不合法地址
名称
描述
MessageId
SVC0004
Text
消息部分%1未提供合法地址。
Variables
%1－消息部分。
SVC0005:
重复关联符
名称
描述
MessageId
SVC0005
Text
消息部分%2中描述的关联符%1是重复的。
Variables
%1－关联符。
%2－消息部分。
SVC0006:
不合法的组
名称
描述
MessageId
SVC0006
Text
消息部分%2中的组%1不是一个合法的组。
Variables
%1－不合法的组的标识符。
%2－消息部分。
SVC0902:
因内容过滤，被拒绝
名称
描述
MessageId
SVC0902
Text
因内容过滤，被拒绝
Variables
无。
策略异常
策略异常消息使用保留的消息标识符‘POL’，并使用从0001到0999的号码来定义。
其中0001至0199被保留作公共差错定义，0200至0999作为其它WebService指定用途。
从‘1000’至‘9999’为自定义。
名称
类型
描述
MessageId
xsd:
string
消息标识符，前缀为POL
Text
xsd:
string
消息文本，可变可替代部分用%来标识。
Variables
xsd:
string[1..unbounded]
替代文本字串中的可变部分。
POL0001:
策略错误
名称
描述
MessageId
POL0001
Text
发生了一个策略错误。
错误代码是%1。
Variables
%1—来自业务的错误码。
POL0003:
过多的地址
名称
描述
MessageId
POL0003
Text
在消息部分%1中描述了过多的地址。
Variables
%1－消息部分。
POL0004:
不支持无限制的通知请求
名称
描述
MessageId
POL0004
Text
不支持无限制的通知请求。
Variables
无。
POL0005:
请求了过多的通知
名称
描述
MessageId
POL0005
Text
请求了过多的通知。
Variables
无。
POL0006:
组地址不被允许
名称
描述
MessageId
POL0006
Text
在消息部分%1中描述的组不被允许。
Variables
%1－消息部分。
POL0007:
嵌套的组不被允许
名称
描述
MessageId
POL0007
Text
在消息部分%1中描述的嵌套的组不被允许。
Variables
%1－消息部分。
POL0009:
请求的频率不合法
名称
描述
MessageId
POL0009
Text
请求的频率不合法。
Variables
无。
POL0900:
不支持群发
名称
描述
MessageId
POL0900
Text
不支持群发请求。
Variables
无。
POL0903:
超过状态保留时长
名称
描述
MessageId
POL0903
Text
超过状态保留时长。
Variables
无。
POL0904:
超过流量门限
名称
描述
MessageId
POL0904
Text
超过流量门限。
Variables
无。
POL0905:
不被支持操作或者请求
名称
描述
MessageId
POL0905
Text
系统不支持此API调用。
Variables
无。
POL0906:
不被允许操作或者请求
名称
描述
MessageId
POL0906
Text
不被允许操作或者请求。
Variables
无。
POL0907:
不允许群发请求
名称
描述
MessageId
POL0907
Text
不允许群发请求。
Variables
无。
POL0908:
短信消息超长
名称
描述
MessageId
POL0908
Text
短信消息超长。
Variables
无。
POL0910:
超过消息上限
名称
描述
MessageId
POL0910
Text
超过消息上限。
Variables
无。
1.1.4AnyUri格式说明
关于anyURI中各类型的格式定义如下：
类型
格式
描述
电话号码
tel:
电话号码
表示接收者是一个电话号码
群组
tel:
组名称;type=grp
表示接收者是一个群组，用于群发，需要与基座中的地址本管理模块配合使用。
部门
tel:
部门名称;type=dpt
表示接收者是一个部门，用于群发，需要与基座中的地址本管理模块配合使用。
Web服务地址
http:
URL
URL
号码、群组、部门可以组合使用，中间用一个“,”号分开。
其它遵循以下标准
RFC2396UniformResourceIdentifiers（URI）:
GenericSyntax
RFC3966ThetelURIforTelephoneNumbers
http:
//www.w3.org/2001/XMLSchema.dtd
1.1.5插件管理接口
接口说明
插件管理接口实现对应用插件的注册、注销、暂停和恢复，各插件通过此接口报告插件状态。
插件管理具体内容包括：
●插件的注册、注销、启用、暂停
●插件状态报告。
WebService方式通信适配插件作为基座插件管理模块的代理，实现插件管理相关操作信息的处理和转发。
流程说明
插件管理流程如下：
MAS服务器系统中应用插件必须注册通过后方可使用，WebService方式通信适配插件将该请求转发到插件管理模块并获得结果，将结果封装在响应消息中返回给应用插件，注册及响应过程通过APRegistration操作实现。
应用插件注册通过后，要周期性地进行状态汇报并获取响应，状态报告及响应过程通过APStatusRep操作完成。
在应用插件运行过程中，根据从MAS统一服务平台得到的业务能力信息，插件管理模块可以主动地发出命令，暂停或恢复特定的插件，这些指令经WebService方式通信适配插件通知给应用插件，通过PauseAP和RecoveryAP两个操作实现。
在应用插件结束之前，应用插件主动发起注销操作APLogOut。
考虑到一个应用插件可能包含多个进程，因此在上述流程中，注册、状态上报和注销为进程级，而暂停和恢复为插件级。
当插件管理模块发现插件进程异常或资源占用超过阀值时，并不停止该进程，而是提示告警给指定人员。
插件分为提供Web服务端和不提供Web服务端两种。
对于提供Web服务端的情况，要在插件注册操作中指明服务端的URL，对插件的暂停和恢复可以通过PauseAP和RecoveryAP操作，或在状态上报响应中体现；对于不提供Web服务端的情况，对插件的暂停和恢复命令只能在状态上报响应中体现。
应用插件的状态图如下图所示：
●数据类型
●注册结果：
APRegResult
●数据结构：
枚举
名称
描述
success
注册成功
illegalAP
插件不被允许，注册失败
CMAbilityNotSup
不支持所要求的通信能力，注册失败
repeatedReg
重复注册，注册成功
svcAddrMismatch
注册请求中的插件Web服务端地址与之前的同一插件其它进程注册请求中的插件Web服务端地址不一致，注册失败。
AP运行状态：
APStatusType
数据结构：
枚举
名称
描述
Normal
状态正常
OutofActiveTime
超过有效期
NeedRegistration
未注册，需要先注册
OutofService
已经注销
Closed
插件进程已被mas服务器强行关闭
WaitingforConfirm
插件的注册请求等待审批中
注销结果：
APLogoutResult
数据结构：
枚举
名称
描述
success
注销成功
illegalAPid
插件id不合法，注销失败
repeatedLogout
重复注销请求
1.1.6接口定义
插件注册
由应用插件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-策略错误.
1.1.7插件状态信息上报
由应用插件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-策略错误.
1.1.8注销插件
由应用插件AP发起进行注销插件进程。
操作：
APLogOut
业务触发条件：
应用插件AP的进程在结束之前，调用此接口进行注销。
注销后的进程若重新使用，需要重新进行注册。
输入：
APLogOutReq
参数
类型
可选性
描述
APid
xsd:
string
M
AP插件的标识
APPid
xsd:
int
M
AP插件的PID
输出：
APLogOutRsp
参数
类型
可选性
描述
LogoutResult
APLogoutResult
M
注销响应结果
差错
业务异常：
●SVC0001-业务错误.
策略异常：
●POL0001-策略错误.
1.1.9插件暂停
此接口用于暂停AP的业务功能，由WebService插件发起。
只有当应用插件有Web服务端的情况，才能使用该操作。
操作：
PauseAP
WebService方式通信适配插件根据插件管理模块的要求，暂停AP的业务功能。
如果插件要重新启用，需要在注销后由插件重新发起注册请求；或者由WebService插件重新启动AP。
输入：
PauseAPReq
参数
类型
可选性
描述
APid
xsd:
string
M
AP插件的标识
输出：
PauseAPRsp
参数
类型
可选性
描述
ACK
xsd:
Boolean
M
true表示成功，false表示失败。
差错
业务异常：
●SVC0001-业务错误.
策略异常：
●POL0001-策略错误.
插件恢复
此接口用于恢复AP的业务功能，由WebService方式通信适配插件发起，仅当应用插件有Web服务端时有效。
操作：
RecoveryAP
WebService方式通信适配插件根据业务要求，恢复已暂停的AP的业务功能。
输入：
RecoveryAPReq
参数
类型
可选性
描述
APid
xsd:
string
M
AP插件的标识
输出：
RecoveryAPRsp
参数
类型
可选性
描述
ACK
xsd:
Boolean
M
true表示成功，false表示失败。
差错
业务异常：
●SVC0001-业务错误.
策略异常：
●POL0001-策略错误.
1.1.10应用系统服务通知接口
接口说明
此接口用于集团客户应用系统完成对短消息、多媒体消息、定位和USSD相关的服务通知。
集团客户应用系统通过此接口通知WebService方式通信适配插件各通信能力对应的服务端URL，以及服务端是否开启或关闭。
流程说明
对于应用系统支持服务端的情况，需要通过startNotification操作通知WebService方式通信适配插件各个通信能力对应的服务端URL，之后WebService方式通信适配插件可以调用服务端向应用系统发出各种消息通知，直到应用系统通过stopNotification通知服务端不可用为止。
应用系统可以多次执行startNotification和stopNotification操作，WebService方式通信适配插件以最后一次的通知为准。
WebService方式通信适配插件在向应用侧发出消息通知失败时，采用指数后退方式重试三次。
若重试后仍失败，则抑制后续的所有消息通知。
1.1.11接口定义
操作：
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-策略错误.
1.1.12短消息接口
接口说明
集团客户应用系统和应用插件通过此接口收发短消息。
WebService方式通信适配插件收到应用插件的发送请求后，通过MAS服务器基座中的SMS通信协议模块发送SMS；当从SMS通信协议模块收到SMS后，通过此接口将短消息发送给集团客户应用系统和应用插件。
流程说明
短消息接口包括发送和接收两个流程。
发送短信由应用系统或应用插件发起，通过sendSms操作实现。
在提交短信发送请求之后，应用侧可以主动获取短信发送状态（getSmsDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧短信发送状态（notifySmsDeliveryStatus操作）。
接收短信可以通过两种方式，一种是由应用侧发起（GetReceivedSms操作），WebService方式通信适配插件将所接收到的发往该应用的短信在响应中提交；第二种是由WebService方式通信适配插件通知应用侧有短信到达（notifySmsReception操作），短信内容包含在请求中。
1.1
升级会员 