移动代理服务器MAS彩信API20DB接口开发手册.pdf

《移动代理服务器MAS彩信API20DB接口开发手册.pdf》由会员上传分享，免费在线阅读，更多相关内容在行业资料-天天文库。

移动代理服务器MAS彩信API2.0DB接口开发手册V1.0深圳市嘉讯软件有限公司二○○九年一月 移动代理服务器MAS彩信API2.0DB接口开发手册目录1引言............................................................................................................................................11.1编写目的............................................................................................................................11.2背景说明............................................................................................................................11.3术语定义............................................................................................................................12概述............................................................................................................................................32.1接口功能............................................................................................................................32.2接口组成............................................................................................................................42.3彩信收发机制....................................................................................................................42.3.1MT彩信与其回执、回复的对应.............................................................................42.3.2MO彩信的分流........................................................................................................53接口介绍....................................................................................................................................63.1接口管理模块....................................................................................................................63.1.1主页面........................................................................................................................63.1.2新建页面....................................................................................................................73.1.3编辑页面....................................................................................................................83.1.4队列管理页面............................................................................................................93.2数据库接口........................................................................................................................93.2.1发送队列表..............................................................................................................103.2.2接收队列表...............................................................................................................113.2.3回执队列表..............................................................................................................123.3DB接口开发说明...........................................................................................................123.3.1数据编码格式..........................................................................................................133.3.2SMIL_ID与SRC_ID的关系.................................................................................134使用指导..................................................................................................................................144.1开发步骤..........................................................................................................................144.2调试方法..........................................................................................................................144.3运行设置与监控..............................................................................................................155附录..........................................................................................................................................165.1附录一：回执编码列表..................................................................................................16ii 移动代理服务器MAS彩信API2.0DB接口开发手册1引言1.1编写目的移动代理服务器MAS提供了强大的彩信接入机制。本手册用于指导客户利用移动代理服务器MAS提供的彩信接口进行其他需要彩信功能的新系统开发或原有系统的彩信功能扩展。本手册的阅读对象为需要采用移动代理服务器MAS的彩信接口完成客户开发的设计人员与编码人员。1.2背景说明本手册适用于产品“移动代理服务器MAS”。1.3术语定义移动代理服务器全称为“移动代理服务器MAS”，属深圳嘉讯公司开发MAS：的一套产品，简称MAS。MT彩信：通过彩信接口发往手机终端的彩信，也指从MAS的某一功能直接发往手机终端的彩信。MO彩信：从手机终端发往MAS的彩信，这些彩信根据特定的规则有的直接转交到MAS的某一具体功能，有的转交到某一彩信接口的接收队列。彩信回执：对于MT彩信，手机终端收到后会返回彩信回执给MAS。通过发送队列发送出去的所有MT彩信随后都会在回执1 移动代理服务器MAS彩信API2.0DB接口开发手册队列中收到对应的回执。回执包含MT彩信是否成功提交到特定手机终端的信息。彩信回复：对于MT彩信，手机终端收到后可以使用彩信回复功能回复一条彩信，对于通过发送队列发送的MT彩信，其回复彩信随后都可以从接收队列中获得接口编码：某套彩信接口的唯一标识，在创建接口时设置，随后不允许修改。彩信子号：每套彩信接口都拥有一个特定数字，这个特定数字由彩信收发机制所使用，其具体作用请参照章节2.3.12 移动代理服务器MAS彩信API2.0DB接口开发手册2概述移动代理服务器MAS不仅为各种类型的集团客户直接提供了丰富的彩信业务应用功能，而且提供强大的彩信接入机制。此机制允许客户再接入任何其他系统以开发此系统的彩信应用功能，从而使拥有移动代理服务器MAS的客户相当于拥有了一个属于自己的“袖珍型彩信行业网关”2.1接口功能移动代理服务器MAS的彩信接入机制所提供的功能是很强大的：¢支持MT彩信的发送、MO彩信的接收。¢所发送的MT彩信文件可以达到100K(视手机和移动网络限制而不同)。¢支持MT彩信的回执确认。¢支持MT彩信的回复会话。¢支持通过分配给接口的彩信子号来接收MO彩信。¢所有接口的收发彩信都有话单记录¢可以出丰富的接口彩信话单报表。¢提供接入的多种语言开发包。¢提供不受任何具体开发语言约束的数据库接入。¢提供开发用的调试环境。3 移动代理服务器MAS彩信API2.0DB接口开发手册¢提供彩信收发的监控功能。2.2接口组成移动代理服务器MAS的彩信接口包括如下部分：组成部分功能说明用于彩信接口的创建、设置、监控；用于开发时的接口管理模块辅助调试。各种语言包用于各种语言的API调用。用于其他系统直接通过访问数据库来进行彩信的收数据库接口发。2.3彩信收发机制2.3.1MT彩信与其回执、回复的对应外部系统利用移动代理服务器MAS的彩信接口进行MT彩信的发送时，可以为每条MT彩信提供指定一个彩信编号，那么随后这条彩信的回执与回复就会带上同样的彩信编号。这样外部系统通过发送MT彩信时所用的彩信编号就可以辨识出随后针对这条彩信的回执、回复。彩信编号可以是1到99999999之间的任何一个整数。如果外部系统需要随后能辨识出每条MT彩信的回执、回复的功能，那么外部系统必须确保在一定的时间段(不低于48小时)内所发送的每条MT彩信都有唯一的彩信编号。4 移动代理服务器MAS彩信API2.0DB接口开发手册2.3.2MO彩信的分流移动代理服务器MAS可以支持几十套彩信接口，那么移动代理服务器MAS怎样确保手机用户主动发起的MO彩信能准确的达到某套彩信接口呢？这有如下两种方法：¢彩信子号分流。在创建1套彩信接口时，MAS会要求用户为此接口分配一个彩信子号，随后MO彩信就可以通过彩信子号的辨识而到达此接口。举例如下：假设发往MAS所用的目的号码为076114044，而某一套彩信接口所分配的彩信子号为5，则手机用户若要发送彩信到此接口，只要发往目的号码07611404405则可。5 移动代理服务器MAS彩信API2.0DB接口开发手册3接口介绍3.1接口管理模块登录MAS后，只要用户权限允许，用户可以在系统管理菜单下访问“接口管理”模块。利用此功能模块，可以对接口进行图形化创建、维护、设置、监控、或进行客户开发的调试辅助。如果用户无法访问“系统管理—〉接口管理－〉彩信接口”，应联系MAS的系统管理员授权。3.1.1主页面彩信接口的主页面如下：主页面主要包括4个按钮与一个列表。所创建的每个接口在列表上有1条记录，通过此列表可以查阅每个接口的基本信息。列表上方各按钮功能如下：¢新建：用于创建一套新的彩信接口，¢编辑：用于编辑已存在彩信接口的某些属性¢删除：删除一套已存在的彩信接口。¢队列管理：可以查阅正在发送队列、接收队列、回执队列中排队的彩信记录，同时用于清除一些非法的彩信记录。配合暂停功能（调试状态），6 移动代理服务器MAS彩信API2.0DB接口开发手册可用于外系统彩信接入开发中的调试。3.1.2新建页面通过主页面的“新建”按钮创建接口时，就会弹出如下新建页面：通过如上页面就可以创建一个接口。如上页面的各输入元素如下：¢接口编码：接口的编码标识符，任意英文字母及数字组成，不能重复。¢接口名称：接口的描述性名称，便于开发用户记忆方便。¢接口类型：包括DB类型、API类型，前者提供DB接口，后者提供开发语言的开发包。DB接口：表示开发用户可以通过任何途径（JDBC,ODBC，其它API等）连接上MAS的数据库，即可进行彩信的收发。¢彩信子码：mo彩信的分流¢登录用户：对应DB接口建立数据库连接的用户名，或API接口init函数的loginName参数。¢登录密码：对应DB接口建立数据库连接的用户密码，或API接口init函数的loginPWD参数。7 移动代理服务器MAS彩信API2.0DB接口开发手册¢接口状态：包括运行状态、调试状态两种类型。当在接口连接开发中时，应设置接口为调试状态，这时候队列管理页面可作为调试时的模拟网关，此时彩信接口是还没有接入真实的彩信网关的。当开发完投入运行时，应设置接口为运行状态，这样彩信接口就接入了真实的彩信网关。3.1.3编辑页面通过主页面的“编辑”按钮编辑某接口时，就会弹出如下编辑页面：通过如上页面就可以修改一个接口。如上页面的各输入元素如下：¢接口名称：修改接口的描述性名称。¢彩信子码：修改彩信子码。¢登录用户：登录名不能修改。¢登录密码：修改登录密码。¢接口状态：切换接口的状态。当在接口连接开发中时，应设置接口为调试状态，这时候队列管理页面可作为调试时的模拟网关，此时彩信接口是还没有接入真实的彩信网关的。当开发完投入运行时，应设置接口为运行状态，这样彩信接口就接入了真实的彩信网关。8 移动代理服务器MAS彩信API2.0DB接口开发手册3.1.4队列管理页面通过主页面的“队列管理”按钮，就可以进入如下队列管理页面：¢发送队列：利用此页面可查看或清除尚在发送队列表的某些记录。¢接收队列：利用此页面可查看或清除尚在接收队列表的某些记录。¢回执队列：利用此页面可查看或清除尚在回执队列表的某些记录。在调试状态时，如上Tab子页都提供了“删除”“添加”按钮，这样利用其添加、删除记录的功能，就可以模拟彩信网关接收上行的MT彩信，并下行MO彩信、MT彩信回执。在运行状态时，如上Tab子页不会出现“删除”“添加”按钮。用户仅能通过队列管理页面查看当前3个队列的排队情况。3.2数据库接口DB接口存在于一个库名为mas的MySQL库内，MySQL数据库的版本为5.0，用户可通过JDBC，ODBC，DAO等任何MySQL可支持的方式访问。建立数据库连接时，所用的IP地址应为MAS的IP地址，登录名、登录密码为接口创建时的接口登录名、接口登录密码。用户在Mas页面上新建彩信接口时，Mas自动生成数据库接口队列表。MO，MT队列表新增了彩信9 移动代理服务器MAS彩信API2.0DB接口开发手册内容字段。DB接口由如下3个表组成，APIMT队列表用于发送彩信，APIMO队列表用于接收彩信，APIRPT队列表用于接收回执。3.2.1发送队列表此表用于发送彩信，表名为api_mms_mt_，其中为接口编码。表结构如下：10 移动代理服务器MAS彩信API2.0DB接口开发手册字段别名字段名数据类型是否空值说明序列号auto_snunsignedintNOTNULL主键，为自增量发送方号码，即目的手机上显示的号码，用于对应NOTNULL彩信SRCIDsrc_idvarchar(21)回复。如果不需要回复，则此值写入空串。唯一ID，1-99999999之间的任何一个数值如果need_rpt的值为1需要回复、回执，此值也必NOTNULL须填入，如果neet_rpt的值0，则此值可以写入0。彩信IDsmil_idtext（不为空）用英文逗号或中文逗号隔开的手机号码集，手机号NOTNULL手机号码集mobilestext码最大不能超过1000个。NOTNULL彩信标题subjectvarchar(100)彩信标题，最大长度为100字节。彩信资源文件名列表,以英文分号分割，Mas系统从NOTNULL彩信内容字段获取文件及文件名，本字段暂未使彩信文件filestext用。是否需要回NOTNULL执need_rpttinyint(1)需要回执填1，否则填0，default0提交发送的时间，字符串的格式为：yyyy-MM-ddNOTNULL提交时间submit_timedatetimeHH:mm:ssmmsContent将彩信资源文件编码成字符串（彩信Demo中提供NOTNULL彩信内容Advlongtext了编码方法，见3.3节）外部系统可对此表进行SELECT、INSERT操作。外部系统通过插入1条记录来进行一次MT彩信发送。3.2.2接收队列表此表用于接收彩信，表名为api_mms_mo_，其中为接口编码。表结构如下：字段别名字段名数据类型是否空值说明序列号auto_snunsignedintNOTNULL主键，为自增量彩信SRCIDsrc_idvarchar(21)NOTNULL用户发送彩信的目的地址。NOTNULL手机号码mobiletext用户提交的手机号码NOTNULL彩信标题subjectvarchar(100)彩信标题，最大长度为100字节。彩信文件filestextNOTNULL文件名称直接从彩信内容字段获取，这里暂未使用收到此MO彩信的的时间，字符串的格式为：NOTNULL接收时间receive_timedatetimeyyyy-MM-ddHH:mm:ss收到的MO彩信资源文件进行编码后的字符串，mmsContentAdNOTNULL客户程序读取MO彩信后利用DecodeMime.java类彩信内容vlongtext的解码方法在客户端程序中解码11 移动代理服务器MAS彩信API2.0DB接口开发手册外部系统可对此表进行SELECT、DELETE操作。外部系统通过SELECT操作来取出所有已收到的MO彩信，取出后的记录通过DELETE操作来删除掉。3.2.3回执队列表此表用于接收回执，表名为api_mms_rpt_，其中为接口编码。表结构如下：字段别名字段名数据类型是否空值说明序列号auto_snunsignedintNOTNULL主键，为自增量唯一ID，1-99999999之间的任何一个数值，NOTNULL当发送彩信need_rpt的值为1需要回复、回执，彩信IDsmil_idtext才有相应的此条记录，对应发送时的smil_idNOTNULL手机号码mobiletext手机号码NOTNULL回执号rpt_resultint回执返回的结果代码NULL回执描述rpt_detailvarchar(100)回执的详细描述回执时间rpt_timedatetimeNOTNULL彩信网关返回回执的时间外部系统可对此表进行SELECT、DELETE操作。外部系统通过SELECT操作来取出所有已返回的彩信回执，取出后的记录通过DELETE操作来删除掉。3.3DB接口开发说明DB接口与原api接口的区别是：不需要依赖MAS机器上的FTP服务来上传和下载彩信文件，MT和MO队列表增加了彩信内容字段，采用编码和解码的方式，在彩信Demo中将彩信文件编码成字符串，利用jdbc将彩信文件插入到彩信MT队列表，服务端自动使用解码方法进行解码后得到原彩信资源文件。在demo工程源码目录下mmsDemosrccomjassonmasmmsutil，MmsUtils.java是彩信工具类提供了编码的方法。发送彩信参考MmsApiDemo.java类，接收MO和回执参考ReceiveMoRpt.java，彩信的12 移动代理服务器MAS彩信API2.0DB接口开发手册MO和回执读取后需要删除，已防止重复读取数据。DecodeMime.java类将MO彩信的编码串解码成彩信文件。目前只提供了java版本的编解码方法。要求客户开发人员具有java编程基础。3.3.1数据编码格式Mysql使用的是ISO8859-1编码格式，外部系统使用DB接口进行开发，往DB接口写入数据时，应先把编码格式转化成ISO8859-1格式；从DB接口读取数据时，应先把编码格式从ISO8859-1转换成外部系统所需要的格式。3.3.2SMIL_ID与SRC_ID的关系SMIL_ID：彩信ID，1-99999999之间的任何一个数值，缺省值0。当SMIL_ID为0时，表示这类彩信不需要辨别其回执、回复。对应回执队列表（RPT表）的SMIL_ID字段。SRC_ID：手机上显示尾号（终端源地址），0到99999999之间的任何一个数值。对应接收队列表（MO表）的SRC_ID字段。13 移动代理服务器MAS彩信API2.0DB接口开发手册4使用指导4.1开发步骤对于使用MAS的用户，利用MAS彩信接口进行其它软件的开发与使用，大体分为如下步骤：接口创建：登录MAS的接口管理模块，进入彩信接口页面，根据需要创建一个合适的彩信接口开发：根据将使用的开发语言选择对应语言的接口语言包进行开发。如果没有对应的语言包，就使用DB接口。如果使用DB接口，则在第1步创建彩信接口时要创建DB类型的接口。调试与测试：编码过程中或编码完成后，利用接口管理模块的队列管理作为一个彩信模拟终端进行调试与测试。运行：在开发完成后，把对应接口设置为运行态，就可以上线运行所开发的软件。4.2调试方法当利用MAS提供的彩信接口进行软件开发时，直接使用手机进行彩信14 移动代理服务器MAS彩信API2.0DB接口开发手册收发的调试当然是可以的。但是如果MAS还没有接入运营商的彩信网络，或者考虑到调试中所产生大量彩信费用的节省，或者为了确保开发中不会造成陌生手机用户的骚扰彩信投诉事件，这时候可以考虑使用接口管理模块的队列管理作为彩信模拟终端进行调试与测试。要使用接口管理模块的队列管理作为彩信模拟终端使用，必须把对应接口的状态设为调试状态。彩信接口是否处于调试状态以及把彩信接口切换到调试状态的方法请参见第3节。当对应接口的状态为调试状态时，先进入接口管理模块的队列管理主页面，然后通过如下方法进行MO彩信、MT彩信、MT彩信的回执进行调试：MO彩信调试：通过在发送队列中新增MO彩信记录来模拟手机的MO彩信发送。随后所开发软件就能接收到此MO彩信。MT彩信调试：所开发软件发送的MT彩信，可以在MT对列中查收。回执调试：通过在回执队列中新增回执记录来模拟来自彩信网关的回执。随后所开发软件就能接收到此彩信回执。在调试状态时，队列管理主页中的发送队列、接收队列、回执队列都提供了删除功能，开发人员可以根据需要进行记录的删除与队列清空。4.3运行设置与监控只要MAS通讯连接设置正确，并已正常运行，在彩信接口置于运行态15 移动代理服务器MAS彩信API2.0DB接口开发手册下，接入彩信接口的外部系统就可正常运行。彩信接口是否处于运行状态以及把彩信接口切换到运行状态的方法请参见第3.1节。彩信接口运行时，可通过接口管理模块进行监控，具体参见第3.1节。彩信接口所收发的所有彩信都有彩信话单，这些话单可以通过Mas的话单管理模块查询，也可以利用统计报表模块进行报表统计。话单管理、统计报表模块的具体操作方法请参见《移动代理服务器MAS用户手册(V1.0).doc》。5附录5.1附录一：回执编码列表所有彩信回执的回执定义如下列表：回执编码回执描述说明0发送成功手机已收到彩信。1彩信标题为空没有彩信标题。2发送内容中存在被彩信内容中包含彩信过滤模块中所设置的过禁止词组滤词组。3手机号码不正确不是正确的手机号码。4手机号码为运营商此手机号码的彩信发送不为运营商所支持或所禁止被运营商所禁止5手机号码存在黑名此手机号码在彩信过滤模块中所设置的黑名单中单范围中。6手机号码不存在白此手机号码不在彩信过滤模块中所设置的白名单中名单范围中。7企业欠费企业帐户余额已用完。101系统错误[n]系统内部出错。频繁出现此问题请联系开发商。102彩信无法到达手机彩信中心无法把彩信发送到对应手机。可能[n]是手机不存在、手机停机、手机关机、手机接收信号不好、彩信中心出问题等原因所造成。16 移动代理服务器MAS彩信API2.0DB接口开发手册地址：深圳市科技园高新南一道创维大厦A区801号电话：0755-26743535传真：0755-26743155邮编：51805717