玄武网关接口文档.doc

41 广州市玄武无线科技有限公司玄武集团短信平台WebService2.1开发手册2013-5-14目录1.前言31.1.编写目的31.2.内容概述31.3.读者对象31.4.适用产品31.5.相关术语与缩略语解释32.接口描述52.1.短信接口52.1.1.接口说明52.1.2.接口流程62.2.彩信接口72.2.1.接口说明72.2.2.接口流程82.3.其他接口92.3.1.接口说明92.3.2.接口流程92.4.上下行匹配92.4.1.内容匹配92.4.2.扩展码匹配102.5.状态报告匹配112.5.1.批次ID+手机号码进行匹配112.5.2.短信customMsgID进行匹配113.开发步骤114.1.在玄武MOS/UMP服务器新建一个企业应用114.2.访问并获取WebService服务地址124.3.客户端代码生成124.4.接口开发及使用举例134.4.1.Post操作134.4.2.PostSingle操作184.4.3.PostMass操作184.4.4.PostGroup操作194.4.5.GetResponse操作204.4.6.GetReport操作234.4.7.FindResponse操作264.4.8.FindReport操作294.4.9.GetMOMessage操作324.4.10.GetAccountInfo操作344.4.11.GetBusinessType操作364.4.12.ModifyPassword操作384.5.状态码定义394.5.1.MT提交状态码394.5.2.Response转义状态码404.5.3.Report转义状态码404.与我们联系401. 前言1.1. 编写目的在本手册里，将向您介绍玄武集团短信产品WebService2.1通信接口的使用方法。1.2. 内容概述Web Service也叫XML Web Service WebService是一种可以接收从Internet或者Intranet上的其它系统中传递过来的请求，轻量级的独立的通讯技术。Web Service完全基于XML（可扩展标记语言）、XSD（XML Schema）等独立于平台、独立于软件供应商的标准，是创建可互操作的、分布式应用程序的新平台。Web Service的主要目标是跨平台的可互操作性。玄武科技集团短信产品WebService通信接口提供了对各种通信能力的统一封装，供对接玄武科技集团短信产品的业务系统进行调用。通过提供统一WebService方式封装也降低了业务系统的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对业务系统呈现简单的标准接口。1.3. 读者对象本手册适用于对接玄武集团短信产品的业务系统开发人员。本文档的读者需要有一定的WebService相关知识。1.4. 适用产品本接口适用于玄武MOS2.1和UMP2.0产品。1.5. 相关术语与缩略语解释缩写词英文解析中文解析备注MOSMessage Operating System集团短信运营平台由玄武科技自主研发的一整套面向多企业级的运营平台UMPUniversal Message Platform集团短信通用平台由玄武科技自主研发的一整套面向单企业级的通用平台XMLExtensible Markup Language扩展型可标记语言面向短期的临时数据处理、面向万维网络，是Soap的基础。SOAPSimple Object Access Protocol简单对象访问协议是XML Web Service的通信协议。WSDLWeb Services Description LanguageWSDL文件一个XML文档，用于说明一组SOAP消息以及如何交换这些消息。SMSShort Messaging Service短消息业务普及率最高的一种短消息业务MMSMultimedia Messaging Service多媒体消息业务中国移动公司把它定名为“彩信”RESResponse提交响应提交运营商网关的响应报告，用于判断是否成功提交到运营商行业网关RPTReport状态报告提交手机的响应报告，用于，用于判断是否成功下发到用户手机MT下行下发到用户手机MO上行用户上行回复业务类型玄武集团短信产品对复杂的业务一种封装类型，包括了下发时间，下发通道，下发的时间范围，下发黑名单等统一封装的对象，用户下发时候用系统默认的业务类型，也可进行特定的配置，详情见平台操作手册批次单次提交的发送单元单发单个发送内容，单个手机号码群发同一个发送内容，不同的手机号码组发一个发送内容，对应一个手机号码batchid批次ID玄武短信产品定义的区分不同批次的唯一标识，主要用户匹配状态报告2. 接口描述. 短信接口.2.1.1. 接口说明业务系统通过此接口收发短消息。业务系统通过标准的WebService方式，提交收发请求，玄武短信平台收发请求之后，进行标准解析和逻辑处理，并将最终处理结果返回给业务系统。2.1.2. 接口流程业务系统通过调用短信下发接口，下发短消息，玄武MOS/UMP返回接收响应；业务系统可以通过查询和推送接口，查询响应的运营商提交相应和手机状态报告。业务系统通过调用短信上行接口，获取用户上行的数据。2.2. 彩信接口2.2.1. 接口说明彩信的下发，获取提交响应和状态报告跟短信类同，通过下发对象赋值不同来区分。另外，彩信没有上行接口。2.2.2. 接口流程业务系统通过调用彩信下发接口，下发彩信，玄武MOS/UMP返回接收响应；业务系统可以通过查询和推送接口，查询响应的运营商提交相应和手机状态报告。对应关系：MT与Response，通过batchid与phone字段进行对应，同一个下发批次，如果出现重复手机号码，则无法进行绝对匹配；Response与Report，通过msgid字段进行对应。2.3. 其他接口2.3.1. 接口说明玄武MOS/UMP提供了一些业务数据获取接口，获取一些基本的业务数据。2.3.2. 接口流程业务系统通过也可调用获取帐号信息，获取业务类型，修改密码接口，得到相应的信息。2.4. 上下行匹配2.4.1. 内容匹配根据规定的上行内容，匹配对应的下行。例如：下发了一批下行，规定回复XXX开头，则匹配到该下行。2.4.2. 扩展码匹配通过对下发的端口号进行扩展，下发短信，手机回复的上行，会带上配置的扩展码，上行和下行再通过该扩展码进行匹配。例如：原始的通道号：10690550，下行设置的扩展码：001，那么，手机回复的上行，除了收到上行内容之后，还可以收到目标地址：10690550001，通过收到的目标地址，则可找到对应的下行。设置方法：方法一：一个批次，一个扩展码MTPack pack = new MTPack();pack.setBatchID(UUID.randomUUID();pack.setBatchName(短信测试批次);pack.setMsgType(MTPack.MsgType.SMS);pack.setBizType(0);pack.setDistinctFlag(false);ArrayList msgs = new ArrayList();/* 群发，多号码一内容 */pack.setSendType(MTPack.SendType.MASS);msgs.add(new MessageData 内容1);msgs.add(new MessageData 内容2);pack.setMsgs(msgs);/设置扩展码pack.setCustomNum(001);GsmsResponse resp = pm.post(ac, pack);方法二：每条短信，一个扩展码MTPack pack = new MTPack();pack.setBatchID(UUID.randomUUID();pack.setBatchName(短信测试批次);pack.setMsgType(MTPack.MsgType.SMS);pack.setBizType(0);pack.setDistinctFlag(false);ArrayList msgs = new ArrayList();/* 群发，多号码一内容 */pack.setSendType(MTPack.SendType.MASS);String content = 短信;MessageData md1 = new MessageData content);md1.setCustomNum(003);MessageData md2 = new MessageData content);md2.setCustomNum(004);msgs.add(md1);msgs.add(md2);pack.setMsgs(msgs);GsmsResponse resp = pm.post(ac, pack);2.5. 状态报告匹配2.5.1. 批次ID+手机号码进行匹配MT与Response，通过batchid与phone字段进行对应，Response与Report，通过msgid字段进行对应。优点：下发简单，无需每条信息都设置msgid字段，节约传输空间，提高传输效率。缺点：状态报告匹配相对复杂，需要通过batchid和phone才能匹配，且如果同一批次有重复手机号码，则无法进行绝对匹配。2.5.2. 短信customMsgID进行匹配每条短信设置customMsgID，Response与Report都会返回customMsgID，通过customMsgID进行对应。优点：状态报告匹配简单，每条短信，状态报告都有唯一对应的customMsgID。缺点：每条短信都需要设置唯一的customMsgID，传输效率相对较低。3. 开发步骤. 在玄武MOS/UMP服务器新建一个企业应用玄武科技销售经理协调处理，并最终提供一个可用的发送帐号。4.2. 访问并获取WebService服务地址在IE浏览器中输入如http:/IP :PORT/Service/WebService.asmx地址，其中IP为MOS/UMP服务器的IP地址，PORT为服务的端口，80可省略, /Service/WebService.asmx为服务地址名，若访问服务地址成功，在IE中将显示如图所示信息。UMP：IP为部署服务器Receiver模块的IP。MOS：IP为2/MOS网关 wsdl地址：2/Service/WebService.asmx?wsdl /400网关 wsdl地址：2:8500/Service/WebService.asmx?wsdl 正确显示服务信息后，记住此服务地址：http:/IP :PORT/Service/WebService.asmx，此地址即为WebService服务地址。4.3. 客户端代码生成根据服务地址生产客户端代码，不同的开发语言，开发工具的生成方法不同，下面以java eclipse为例。首先，获取WSDL地址，后添加?wsdl，然后在IE中输入此地址，如 http:/IP :PORT/Service/WebService.asmx?wsdl，访问可显示WSDL信息。接着，在ecplise导入wsdl地址，生成相应的客户端代码。将生成的客户端及服务端代码部署到开发工程中，然后进行后续的开发步骤。4.4. 接口开发及使用举例4.4.1. Post操作. 操作说明Post调用是业务系统发起，请求发送短消息到指定手机。该操作为统一的发送接口，支持单发，组发，群发操作，推荐使用。. 开发代码举例原型：GsmsResponse Post(string account, string password, MTPack mtpack);输入参数：序字段名称数据类型是否必须说明1accountString是用户名2passwordString是密码，MD5加密，设置时自动加密3mtpackMTPacks是下行批次包，最大下发手机号码数为100万。Mtpack：序字段名称数据类型是否必须说明1.batchIDUUID否信息批次唯一序号 2.batchNameString否批次名称3.sendTypeint32是发送类型：群发(0默认)组发(1)单发是以上两者的特例4.msgTypeint32是消息类型：短信(1默认)彩信(2),WAPPUSH(3);5.mediasMediaItem否公共彩信资源列表6.msgsMessageData是数条短信7.bizTypeint32否信息业务类型,对应于BusinessType(业务类型)的ID8.distinctFlagbool是是否过滤重复号码（默认：false）9.scheduleTimeint64否计划发送时间10.remarkString否备注11.customNumString否用户扩展码12.deadlinelong否下发截至时间输出参数：序字段名称数据类型是否必须说明1GsmsResponseGsmsResponse是玄武MOS/UMP响应报告，详细返回代码见：MT提交状态码输出xml：0代码片段：/ / 短信发送/ public void PostMSG() var wb = new WebServiceSoapClient(); MessageData messagedatas = new MessageData3; /号码数量 #region 群发 / /for (int i = 0; i messagedatas.Length; i+) / / messagedatasi = new MessageData(); / messagedatasi.Content = 中华人民共和国测试; / messagedatasi.Phone = 135 + i.ToString(D8); / messagedatasi.vipFlag = true; / messagedatasi.customMsgID = 121; / #endregion #region /messagedatas0 = new MessageData(); /messagedatas0.Content = 中华人民共和国测试1; /messagedatas0.Phone = /messagedatas0.vipFlag = true; /messagedatas0.customMsgID = 121; /messagedatas1 = new MessageData(); /messagedatas1.Content = 中华人民共和国测试2; /messagedatas1.Phone = ; /messagedatas1.vipFlag = true; /messagedatas1.customMsgID = 121; /messagedatas2 = new MessageData(); /messagedatas2.Content = 中华人民共和国测试3; /messagedatas2.Phone = /messagedatas2.vipFlag = true; /messagedatas2.customMsgID = 121; #endregion #region 组发 / for (int i = 0; i messagedatas.Length; i+) messagedatasi = new MessageData(); messagedatasi.Content = 内容 + i; messagedatasi.Phone = 135 + i.ToString(D8); messagedatasi.vipFlag = true; messagedatasi.customMsgID = 3241; #endregion MTPacks mtpack = new MTPacks(); /mtpack.batchID = Guid.NewGuid(); mtpack.batchName = qqqqq;/ +DateTime.Now.Millisecond; / 分批名称 mtpack.msgs = messagedatas; mtpack.msgType = 1; / 消息类型，短信1、彩信2 /Type = 1; / 业务类型ID mtpack.customNum = 13801; / 扩展号 /mtpack.scheduleTime = 0; / 时间使用int64类型，是指从1970-1-1 00:00:00开始到当前的毫秒数 mtpack.sendType = 1; / 发送类型，群发0、组发1 mtpack.distinctFlag = true; / 是否过滤重复号码 /mtpack.deadline = 0; / 时间使用int64类型，是指从1970-1-1 00:00:00开始到当前的毫秒数 mtpack.remark = ; / 备注 DateTime dt1 = DateTime.Now; GsmsResponse gr = wb.Post(account, password, mtpack); TimeSpan t = DateTime.Now.Subtract(dt1); Console.WriteLine(Thread.CurrentThread.Name + 短信返回结果： + gr.result + + gr.message);/ / 彩信发送/ public void PostMMS() var wb = new WebServiceSoapClient(); MessageData messagedatas = new MessageData2; /手机号码数量 MTPacks mtpack = new MTPacks(); mtpack.batchID = Guid.NewGuid(); mtpack.batchName = ttttttttttt;/ +DateTime.Now.Millisecond; / 分批名称 mtpack.msgType = 2; / 消息类型，短信1、彩信2 Type = 1; / 业务类型ID mtpack.customNum = 1380; / 扩展号 mtpack.scheduleTime = 0; / 时间使用int64类型，是指从1970-1-1 00:00:00开始到当前的毫秒数 mtpack.sendType = 0; / 发送类型，群发0、组发1 mtpack.distinctFlag = true; / 是否过滤重复号码 mtpack.deadline = 0; / 时间使用int64类型，是指从1970-1-1 00:00:00开始到当前的毫秒数 mtpack.remark = ; / 备注 mtpack.medias = SetMedias(D:玄武项目WebserviceWebServiceClientResourcespublic); /设置公共彩信资源 #region 群发 for (int i = 0; i messagedatas.Length; i+) messagedatasi = new MessageData(); messagedatasi.Content = ; messagedatasi.Phone = 135 + i.ToString(D8); messagedatasi.vipFlag = true; messagedatasi.customMsgID = 121; #endregion #region 组发 /messagedatas0 = new MessageData(); /messagedatas0.Content = ; /messagedatas0.Phone = /messagedatas0.vipFlag = true; /messagedatas0.customMsgID = 3241; /messagedatas0.medias = SetMedias(D:Resourcesimg1); /设置私有彩信资源 /messagedatas1 = new MessageData(); /messagedatas1.Content = ; /messagedatas1.Phone = /messagedatas1.vipFlag = true; /messagedatas1.customMsgID = 3241; /messagedatas1.medias = SetMedias(D:Resourcesimg2); /设置私有彩信资源 #endregion mtpack.msgs = messagedatas; DateTime dt1 = DateTime.Now; GsmsResponse gr = wb.Post(account, password, mtpack); TimeSpan t = DateTime.Now.Subtract(dt1); Console.WriteLine(Thread.CurrentThread.Name + 彩信返回结果： + gr.result + + gr.message);4.4.2. PostSingle操作. 操作说明PostSingle调用是业务系统发起，请求单发短消息到一个手机。建议使用Post操作。. 开发代码举例原型：int PostSingle(string account, string password, string mobile, string content, string subid);输入参数：序字段名称数据类型是否必须说明1accountString是用户名2passwordString是密码，MD5加密，设置时自动加密3mobileString是短信发送的目的手机号码4contentString是短信发送的内容5subidString否扩展ID（最好与post的说明一样）,并说明最大不能超过多少位输出参数：序字段名称数据类型是否必须说明1intInt是返回值：见MT提交状态码输出xml：0代码片段4.4.3. PostMass操作. 操作说明PostMass调用是业务系统发起，请求群发短消息到一个指定地址（或地址集合）。建议使用Post操作。. 开发代码举例原型：int PostMass(string account, string password, string mobiles, string content, string subid);输入参数：序字段名称数据类型是否必须说明1accountString是用户名2passwordString是密码，MD5加密，设置时自动加密3mobilesString是短信发送的目的手机号码数组，最大下发手机号码数为100万。4contentString是短信发送的内容5subidString否扩展ID输出参数：序字段名称数据类型是否必须说明1intInt是返回值：见MT提交状态码输出xml：0代码片段4.4.4. PostGroup操作. 操作说明PostGroup调用是业务系统发起，请求组发短消息到一个指定地址（或地址集合）。建议使用Post操作。. 开发代码举例原型：int PostGroup(string account, string password, MessageData mssages, string subid);输入参数：序字段名称数据类型是否必须说明1accountString是用户名2passwordString是密码，MD5加密，设置时自动加密3mssagesMessageData 是短信发送的多个目的的数组，最大下发手机号码数为100万。4subidString否扩展IDMessageData序字段名称数据类型是否必须说明1phoneString是手机号码2contentString是短信内容3mediasMediaItem否私有彩信资源列表4customMsgIDString否用户自定义消息ID5customNumString否用户扩展码5vipFlagbool是是否VIP号码(默认：false)输出参数：序字段名称数据类型是否必须说明1intInt是返回值：见MT提交状态码输出xml：0代码片段4.4.5. GetResponse操作. 操作说明GetResponse调用是业务系统发起，请求推送运营商提交相应。已经推送过的提交相应，下次无法继续推送。. 开发代码举例原型：MTResponse GetResponse(string account, string password, int pagesize);输入参数：序字段名称数据类型是否必须说明1accountString是用户名2passwordString是密码，MD5加密，设置时自动加密3pagesizeInt是获取数量，当超过500时，系统默认为500输出参数：序字段名称数据类型是否必须说明1MTResponseMTResponse是获取的提交相应实体对象MTResponse序字段名称数据类型是否必须说明1batchIDUUID是批次号2msgIDString是消息ID3customMsgIDString否用户自定义消息ID4stateint32是玄武网关根据originResult转义的状态，见Response转义状态码5phoneString是手机号码6totalint32否分段总数（用于长短信）7numberint32否当前段数（用于长短信）8submitRespTimeint64是提交运营商响应时间9originResultString否运营商返回原始提交响应结果10reserveString否保留字段输出xml：162b77b4-bbaa-4045-92df-a3bb58e861c357156525320211343393864612013-05-07T01:56:520108130ecc65a-3d1b-0548-8baf-73b381c2310b5726522411343393864612013-05-07T02:06:0801391代码片段/ / 获取提交报告/ / 获取条数public void GetResponse(int count) if (count = 0) Console.WriteLine(获取条数必须大于0); return; var webService = new WebServiceSoapClient(); MTResponse info = webService.GetResponse(account, password, count); if (info != null) for (int i = 0; i info.Length; i+) Console.WriteLine(批次号： + infoi.batchID); Console.WriteLine(消息ID： + infoi.msgID); Console.WriteLine(手机号码： + infoi.phone); Console.WriteLine(提交运营商响应时间： + infoi.submitRespTime); Console.WriteLine(用户自定义ID： + infoi.customMsgID); Console.WriteLine(分段总数： + infoi.total); Console.WriteLine(当前段数： + infoi.number); Console.WriteLine(保留字： + infoi.reserve); Console.WriteLine(运营商返回的原始提交响应结果： + infoi.originResult + n); else Console.WriteLine(null); 4.4.6. GetReport操作. 操作说明GetReport调用是业务系统发起，请求推送运营商状态报告。已经推送过的状态报告，下次无法继续推送。. 开发代码举例原型：MTReport GetReport(string account, string password, int days, int pagesize);输入参数：序字段名称数据类型是否必须说明1accountString是用户名2passwordString是密码，MD5加密，设置时自动加密3pagesizeInt是获取数量，当超过500时，系统默认为500输出参数：序字段名称数据类型是否必须说明1MTReportMTReport是获取返回的状态报告实体MTReport序字段名称数据类型是否必须说明1Idlong是系统id2batchIDString是批次号3phoneString是手机号码4msgIDString是消息ID5customMsgIDString否用户自定义消息ID6stateint32是玄武网关根据originResult转义的状态，见Report转义状态码7totalint32否分段总数（用于长短信）8numberint32否当前段数（用于长短信）9submitTimeint64是提交时间10doneTimeint64是完成时间11originResultString否运营商返回的原始状态报告。具体状态码含义根据所走的通道所属的运营商网关的协议确定12reserveString否保留字段输出xml：13852162b77b4-bbaa-4045-92df-a3bb58e861c31343393864657156525320202013-05-07T01:56:002013-05-07T01:57:00DELIVRD1403630ecc65a-3d1b-0548-8baf-73b381c2310b13433938646572652