浙江联通行业应用短信平台二次开发接口使用手册.doc

浙江联通行业应用短信平台二次开发接口使用手册文件版本：v1.0.070201发布时间：2007.02.01浙江联通行业应用短信平台二次开发接口使用手册（v1.0）中国联通浙江分公司增值业务部2007.02 注意事项：1、 本手册介绍浙江联通行业应用短信平台的二次开发接口的安装调试方法。如果需要对帐号进行日常管理（如子帐号管理、费用查询、客户端下载发送短信等），请登录到网站上进行操作。这方面的操作指南请参考网页界面的使用手册。2、 如果您需要快速定位问题，请直接查阅第5节的“常见问题解答（faq）”。1简介1.1系统的结构和特点浙江联通行业应用短信平台具备二次开发接口（后面简称接口或接口软件），接口软件在整个方案中的位置如下图中蓝色部分所示，在安装了接口软件以后，企业内部所有的短信应用系统只要对接口数据库进行数据存储，就能完成收发短信的工作，并且可以查询到所发送短信当前的状态，避免了企业内部软件开发人员在cmpp、smpp等短信通讯协议上浪费大量的人力和物力。和使用api接口在cmpp或smpp协议层次上开发短信应用程序相比，企业直接使用本系统提供的数据库接口开发短信应用程序，可以至少节省一个开发小组几个月的工作量，在时间就是金钱的现代社会，本系统为企业带来的时间效益是惊人的。用户手机企业内部网络应用系统1短信接口数据库浙江联通内部网络短信中心应用系统2短信网关应用系统n杭州联通行业应用短信平台服务器短信接口软件互联网专线图例：绿色箭头采用sgip或smpp协议传输短信的链路红色箭头采用加密数据包传输短信的链路本系统采用了各种方法保证企业短信收发的安全性和稳定性：l 信息加密：和浙江联通行业短信平台接口服务器之间的通讯不采用cmpp、smpp等非加密的协议，而是在短消息传送的过程中进行加密传输，保证了信息的安全性。l 断线重连：软件具备断线自动重连的功能，当因为网络异常等各种原因造成链路中断时，软件能够自动重复尝试连接，以保证短信收发的及时性和可靠性。l 免维护：接口服务软件采用系统服务的方式在后台运行，无须用户干预，即使遇到服务器断电等异常情况，只要按动电源按钮重新将计算机开机，软件即可自动运行。接口软件和企业内部的短信应用系统之间采用容易编程的数据库接口，使开发人员能够以最简便的方式实现最强大的功能：l 发送简单方便：软件自动对接口数据库进行扫描，企业内部的短信应用系统只要将短信发送号码和内容保存到接口数据库里面，就可以将短信发送到用户的手机上。l 状态可查询：软件自动接收短信网关返回的短信状态报告，并将状态保存到接口数据库中，企业内部的短信应用程序只要查询数据库，就可以得知短信的当前状态。l 信息双向交流：当用户向企业发送短信时，软件自动从服务器端接收短信并保存到接口数据库中，其他应用程序只要查询接口数据库，就可以获取该短信。l 号码扩展：企业可以对短信号码进行多达8位的扩展，便于多个内部应用系统同时通过该接口收发短信，真正实现一点接入，多点使用。l 支持广泛：现在最新版本的短信接口服务软件已经支持最常用的oracle、sqlserver和sybase数据库。1.2运行环境接口软件的运行环境为：l 硬件要求：cpu piii 700以上，内存128ml 软件要求：windows 2000/xp，如果接口数据库使用oracle，则需安装oracle客户端软件。和软件配套使用的接口数据库可以使用oracle、sql server或sybase三种类型，接口数据库和接口服务软件既可以安装在不同的计算机上，也可以安装在同一台计算机上，如果两者安装在同一台服务器上，那么服务器的硬件配置应该相应提高。建议采用下列配置的专用服务器： 双p4 1600 cpu，1g内存，36.4g x 2热插拔硬盘（raid1）2数据库的安装和配置在安装接口服务软件之前，需要首先安装数据库并初始化接口表，下面的内容将分oracle、sqlserver和sybase数据库三种类型分别说明如何创建接口表。2.1使用oracle数据库在使用oracle数据库的情况下，最好为短信接口表单独设置一个表空间，并为其单独分配一个用户，以便和其他短信应用系统使用的数据表隔离。2.1.1数据字典下面是短信接口表的初始化脚本，各字段的取值和含义已经包含在字段的注释中：- - 系统范围内唯一的id，容量：10位整数- drop sequence sms_seq;create sequence sms_seq increment by 1 start with 1 maxvalue 9999999999 nocache;- - 数据库版本表- ! 请不要增加、删除或者修改本表的记录 !- drop table sms_ver cascade constraints;create table sms_ver ( vernumber(2)- 数据库结构版本号);insert into sms_ver values(1);commit;- - 短信接收表- drop table sms_receive cascade constraints;create table sms_receive(idnumber(10) primary key,- 唯一id，取自sms_seq序列resultchar(1) default 0,- 供用户程序使用，表示记录是否被处理，缺省为0mobilevarchar2(21) not null,- 发送方的手机号码recv_timevarchar2(20),- 短信接收时间sms_numbervarchar2(10),- 扩展短号（用户发送的号码去除公司短号后的扩展部分）contentvarchar2(160)- 接收的短信内容);create index idx_sms_receive_result on sms_receive(result);create index idx_sms_receive_mobile on sms_receive(mobile);create index idx_sms_receive_sms_number on sms_receive(sms_number);- - 短信发送表- drop table sms_send cascade constraints;create table sms_send(mobilevarchar2(21) not null,- 要发送的手机号码contentvarchar2(160),- 要发送的短信内容sms_numbervarchar2(10),- 要发送的扩展短号（自动添加在公司短信号码后面）idnumber(10) primary key,- 唯一id，取自sms_seq序列prioritynumber(1) default 9,- 发送优先级，0 最高plan_timevarchar2(19),- 短信定时发送时间，格式为 yyyy-mm-dd hh24:mi:ss- 如果不填写，表示马上发送- *- 上面的字段由发送者填写- 下面的字段由接口回填- *resultchar(1) default 0,- 状态- 0 等待提交，表示短信尚未提交到短信群发平台的服务器- 1 已提交，表示短信已经提交到短信群发服务器，但是尚未发送到网关- 2 已发送，表示短信已经发送到网关，等待用户接收- 3 已接收，表示用户的手机已经收到短信- a 提交错误，短信被短信群发服务器拒绝- b 发送错误，短信被网关拒绝- c 接收错误，因为用户关机等原因，短信最终未被用户收到- ! 注意 ! ：- 接口服务程序扫描result=0的记录并发送，然后根据结果更新result字段- 如果在sms_send表上面建触发器，请严格测试，保证result从0更新到其他- 状态的语句不会执行失败，否则该条记录会被接口服务程序重复扫描到并- 一直重复发送 !seq_idvarchar2(10),- 短信编号submit_timevarchar2(20),- 提交时间send_timevarchar2(20),- 网关发送时间recv_timevarchar2(20),- 用户接收时间send_typechar(1)- 保留);create index idx_sms_send_priority on sms_send(priority);create index idx_sms_send_time on sms_send(plan_time);create index idx_sms_send_result on sms_send(result);create index idx_sms_send_seq_id on sms_send(seq_id);create index idx_sms_send_mobile on sms_send(mobile);2.1.2示范sql语句下面是短信应用程序收发短信以及查询短信状态的sql语句示范： 发送短信：假设浙江联通分配给用户的企业短信号码是7016571xxx，那么用户可以在此号码的基础上以7016571xxxyyyyy号码为主叫号码向手机发送短信，其中yyyyy为0位到8位的扩展号码。下面的第1条sql语句以7016571xxx号码送短信“您好！”；第2条sql语句以7016571xxx1234号码送短信“hello!”；第3条sql语句以7016571xxx6789号码送短信“您好”，发送时间定在2004年2月2日18点0分。l insert into sms_send(id,mobile,content) values (sms_seq.nextval您好！)l insert into sms_send(id,sms_number,mobile,content) values (sms_seq.nextval, 1234, 您好！)l insert into sms_send (id, sms_number, mobile, content, plan_time) values (sms_seq. nextval, 6789, 您好！,2004-02-02 18:00:00)注意：定时发送以数据库接口服务器的时间作为基准，请务必将数据库服务器的系统时间调整为正确的时间！ 查询已发送的短信状态：当短信被发送以后，接口服务程序将根据短信的当前状态实时更新sms_send表中相应记录的result字段，所以只要对该表进行查询，即可得知短信当前的状态。submit_time、send_time、recv_time三个字段配合result字段使用，表示短信到达各步骤的时间：l result字段的初始状态为0，当短信被递交到浙江联通行业短信平台接口服务器，并且递交成功的时候，该字段将被设置为1，这时submit_time字段被更新为短信递交到服务器的时间。l 如果短信被接口服务器拒绝（一般原因为发送的号码不合法、或者公司帐号欠费），那么result字段将被设置为a。l 当短信从浙江联通行业短信平台接口服务器递交到短信网关，并且已经递交成功的时候，那么result字段将被设置为2，这时send_time字段被更新为短信递交到网关的时间。l 如果短信被网关拒绝（一般原因为发送号码不合法，或者扣费号码中已经没有余额等），那么result字段将被设置为b。l 当用户手机收到短信后，result字段将被更新为3，这时recv_time字段将被更新为用户手机收到短信的时间。l 如果由于用户手机关机或者不在服务区，短信中心经过多次重试仍无法找到用户，那么result字段将被更新为c。 查询接收到的短信：系统从用户手机接收的短信将被保存在sms_receive表中，假码向7016571xxx12345号码发送了一条短信，那么sms_receive表中将增加一条记录，其中的mobile字段的内容为，sms_number字段的内容为扩展号码“12345”，content字段的内容为短信内容。2.2使用sqlserver数据库在使用sqlserver数据库的情况下，最好为短信接口表单独创建一个数据库，并为其单独分配一个用户，以便和其他短信应用系统使用的数据表隔离。2.2.1数据字典下面是短信接口表的初始化脚本，各字段的取值和含义已经包含在字段的注释中：- - 数据库版本表- ! 请不要增加、删除或者修改本表的记录 !- - drop table sms_ver- gocreate table sms_ver ( verint)goinsert into sms_ver values(1)go- - 短信接收表- create table sms_receive ( idnumeric(18,0) identity (1,1)not for replication not null,- 唯一id resultchar(1) not null default (0),- - 供用户程序使用，表示记录是否被处理，缺省为0 mobilevarchar(21) not null,- - 发送方的手机号码 recv_timevarchar(20),- - 短信接收时间 sms_numbervarchar(10),- - 扩展短号（用户发送的号码去除公司短号后的扩展部分） contentvarchar(160)- - 接收的短信内容)goalter table sms_receive add constraint pk_sms_receive primary key clustered (id)gocreate index ix_sms_receive_result on sms_receive(result)gocreate index ix_sms_receive_mobile on sms_receive(mobile)gocreate index ix_sms_receive_sms_number on sms_receive(sms_number)go- - 短信发送表- create table sms_send( mobilevarchar(21) not null,- 要发送的手机号码 contentvarchar(160) not null,- 要发送的短信内容 sms_numbervarchar(10),- 要发送的扩展短号（自动添加在公司短信号码后面） idnumeric(18,0) identity (1,1)not for replication not null,- 唯一id（自动递增） priorityint default 9,- 发送优先级，0 最高 plan_timevarchar(19),- 短信定时发送时间，格式为 yyyy-mm-dd hh:mm:ss- 如果不填写，表示马上发送- *- 上面的字段由发送者填写- 下面的字段由接口回填- * resultchar(1) default (0),- 状态- 0 等待提交，表示短信尚未提交到短信群发平台的服务器- 1 已提交，表示短信已经提交到短信群发服务器，但是尚未发送到网关- 2 已发送，表示短信已经发送到网关，等待用户接收- 3 已接收，表示用户的手机已经收到短信- a 提交错误，短信被短信群发服务器拒绝- b 发送错误，短信被网关拒绝- c 接收错误，因为用户关机等原因，短信最终未被用户收到- ! 注意 ! ：- 接口服务程序扫描result=0的记录并发送，然后根据结果更新result字段- 如果在sms_send表上面建触发器，请严格测试，保证result从0更新到其他- 状态的语句不会执行失败，否则该条记录会被接口服务程序重复扫描到并- 一直重复发送 ! seq_idvarchar(10),- 短信编号 submit_timevarchar(20),- 提交时间 send_timevarchar(20),- 网关发送时间 recv_timevarchar(20),- 用户接收时间 send_typechar(1) default (0)- 保留)goalter table sms_send add constraint pk_sms_send primary key clustered (id)gocreate index ix_sms_send_priority on sms_send(priority)gocreate index ix_sms_send_time on sms_send(plan_time)gocreate index ix_sms_send_result on sms_send(result)gocreate index ix_sms_send_mobile on sms_send(mobile)gocreate index ix_sms_send_seq_id on sms_send(seq_id)go2.2.2示范sql语句下面是短信应用程序收发短信以及查询短信状态的sql语句示范： 发送短信：假设浙江联通分配给用户的企业短信号码是7016571xxx，那么用户可以在此号码的基础上以7016571xxxyyyyy号码为主叫号码向手机发送短信，其中yyyyy为0位到8位的扩展号码。下面的第1条sql语句以7016571xxx号码送短信“您好！”；第2条sql语句以7016571xxx12345号码送短信“hello!”；第3条sql语句以7016571xxx6789号码送短信“您好”，发送时间定在2004年2月2日18点0分。l insert into sms_send(mobile,content) values 您好！)l insert into sms_send(sms_number, mobile, content) values (12345, 您好！)l insert into sms_send (sms_number, mobile, content, plan_time) values (6789, 您好！, 2004-02-02 18:00:00)注意：定时发送以接口数据库服务器的时间作为基准，请务必将数据库服务器的系统时间调整为正确的时间！ 查询已发送的短信状态：请参考2.1.2节中的相应内容。 查询接收到的短信：请参考2.1.2节中的相应内容。2.3使用sybase数据库在使用sybase数据库的情况下，最好为短信接口表单独创建一个数据库，并为其单独分配一个用户，以便和其他短信应用系统使用的数据表隔离。2.3.1数据字典下面是短信接口表的初始化脚本，各字段的取值和含义已经包含在字段的注释中：- - 数据库版本表- ! 请不要增加、删除或者修改本表的记录 !- - drop table sms_ver- gocreate table sms_ver ( verint)goinsert into sms_ver values(1)go- - 短信接收表- - drop table sms_receive- gocreate table sms_receive ( idnumeric(18,0) identity not null,- 唯一id resultchar(1) default (0),- - 供用户程序使用，表示记录是否被处理，缺省为0 mobilevarchar(21) not null,- - 发送方的手机号码 recv_timevarchar(20) null,- - 短信接收时间 sms_numbervarchar(10) null,- - 扩展短号（用户发送的号码去除公司短号后的扩展部分） contentvarchar(160) null- - 接收的短信内容)gocreate unique index pk_sms_receive on sms_receive(id)gocreate index ix_sms_receive_result on sms_receive(result)gocreate index ix_sms_receive_mobile on sms_receive(mobile)gocreate index ix_sms_receive_sms_number on sms_receive(sms_number)go- - 短信发送表- - drop table sms_send- gocreate table sms_send( mobilevarchar(21) not null,- 要发送的手机号码 contentvarchar(160) not null,- 要发送的短信内容 sms_numbervarchar(10) null,- 要发送的扩展短号（自动添加在公司短信号码后面） idnumeric(18,0) identity not null,- 唯一id（自动递增） priorityint default 9,- 发送优先级，0 最高 plan_timevarchar(19) null,- 短信定时发送时间，格式为 yyyy-mm-dd hh:mm:ss- 如果不填写，表示马上发送- *- 上面的字段由发送者填写- 下面的字段由接口回填- * resultchar(1) default (0),- 状态- 0 等待提交，表示短信尚未提交到短信群发平台的服务器- 1 已提交，表示短信已经提交到短信群发服务器，但是尚未发送到网关- 2 已发送，表示短信已经发送到网关，等待用户接收- 3 已接收，表示用户的手机已经收到短信- a 提交错误，短信被短信群发服务器拒绝- b 发送错误，短信被网关拒绝- c 接收错误，因为用户关机等原因，短信最终未被用户收到- ! 注意 ! ：- 接口服务程序扫描result=0的记录并发送，然后根据结果更新result字段- 如果在sms_send表上面建触发器，请严格测试，保证result从0更新到其他- 状态的语句不会执行失败，否则该条记录会被接口服务程序重复扫描到并- 一直重复发送 ! seq_idvarchar(10) null,- 短信编号 submit_timevarchar(20) null,- 提交时间 send_timevarchar(20) null,- 网关发送时间 recv_timevarchar(20) null,- 用户接收时间 send_typechar(1) default (0)- 保留)gocreate unique index pk_sms_send on sms_send(id)gocreate index ix_sms_send_priority on sms_send(priority)gocreate index ix_sms_send_time on sms_send(plan_time)gocreate index ix_sms_send_result on sms_send(result)gocreate index ix_sms_send_mobile on sms_send(mobile)gocreate index ix_sms_send_seq_id on sms_send(seq_id)go2.3.2示范sql语句下面是短信应用程序收发短信以及查询短信状态的sql语句示范： 发送短信：假设浙江联通分配给用户的企业短信号码是7016571xxx，那么用户可以在此号码的基础上以7016571xxxyyyyy号码为主叫号码向手机发送短信，其中yyyyy为0位到8位的扩展号码。下面的第1条sql语句以7016571xxx号码送短信“您好！”；第2条sql语句以7016571xxx12345号码送短信“hello!”；第3条sql语句以7016571xxx6789号码送短信“您好”，发送时间定在2004年2月2日18点0分。如果需要发送语音短信，则将send_type字段填为 1 即可。l insert into sms_send(mobile,content) values 您好！)l insert into sms_send(sms_number, mobile, content) values (12345, 您好！)l insert into sms_send (sms_number, mobile, content, plan_time) values (6789, 您好！, 2004/02/02 18:00:00)注意：定时发送以数据库服务器的时间作为基准，请务必将数据库服务器的系统时间调整为正确的时间！ 查询已发送的短信状态：请参考2.1.2节中的相应内容。 查询接收到的短信：请参考2.1.2节中的相应内容。3安装系统服务程序系统服务程序由两个文件组成：l smssocket.exe 短信接口服务程序。l smssocket.ini 短信接口服务程序使用的配置文件。文件不需要安装，只要在系统中创建一个单独的目录并把这两个文件拷贝到该目录中即可。3.1配置文件smssocket.ini是一个文本格式的配置文件，可以用记事本打开编辑，其格式如下：databasedbtype=数据库类型dbversion=数据库版本dbusername=数据库用户名dbpassword=数据库密码dbserver=数据库服务器dbname=数据库名称odbcstring=以自定义的连接串代替上面的dbusername、dbversion、dbpassword、dbserver和dbname配置smsusername=短信接口登录用户名password=短信接口登录密码serverip=serverport=6577配置文件分为database和sms两个小节，database小节定义了接口数据库的参数，小节中各字段的含义如下：字段名称默认值取值含义dbtype0使用的数据库类型：l 0oraclel 1sqlserverl 2sybasedbversion8使用oracle数据库时的oralce客户端版本（非oracle数据库时忽略）：l 8oracle 8i及以下版本l 9oracle 9idbserver数据库服务器：l oracle数据库tnsname中配置的数据库名l sqlserver数据库数据库服务器的ip地址l sybase数据库数据库服务器的主机名dbname数据库名l oracle数据库本字段无效，被接口程序忽略l sqlserver或sybase数据库数据库名称，如master、pubs等dbusername数据库登录用户名dbpassword数据库登录密码odbcstring如果需要使用自定义的odbc连接串，可以用这个参数指定，这时dbversion、dbserver、dbname、dbusername、dbpassword参数无效，但是dbtype参数仍然需要指定。odbcstring参数的进一步说明：由于接口程序默认使用的odbc驱动版本为oracle 8和sybase 11版本，如果数据库版本有所不同，那么驱动串可能有所不同，这时可以用odbcstring字段指定指定的连接字符串，如：odbcstring= driver=oracle odbc driver;uid=user;pwd=pass;dbq=sms_dbodbcstring=driver=sql server;uid=sa;pwd=sa;server=;database=masterodbcstring=driver=sybase system 12;uid=sa;pwd=sa;srvr=local;db=mastersms小节定义了短信服务接口的参数，小节中各字段的含义如下：字段名称默认值取值含义serverip浙江联通行业应用短信平台服务器的地址serverport6577浙江联通行业应用短信平台服务器的服务端口dbserver数据库服务器：l oracle数据库tnsname中配置的数据库名l sqlserver数据库数据库服务器的ip地址l sybase数据库数据库服务器的主机名dbname数据库名l oracle数据库本字段无效，被接口程序忽略l sqlserver或sybase数据库数据库名称，如master、pubs等username登录用户名password登录密码3.2试运行服务在安装并初始化数据库表，并且根据数据库参数和连接参数配置好smssocket.ini文件后，就可以开始调试服务程序了，smssocket.exe服务程序采用控制台方式运行，开始运行前请在“开始”菜单“运行”中运行“cmd”以打开命令提示符，并切换到程序所在的目录，举例如下（假设程序拷贝在d盘的smssocket目录中）：d:cd smssocketd:smssocketdir 驱动器 d 中的卷是 data 卷的序列号是 782b-3c31 d:smssocket 的目录2007-02-12 19:42 .2007-02-12 19:42 .2007-02-10 03:25 15,872 smssocket.exe2007-02-12 19:44 179 smssocket.ini 2 个文件 16,051 字节 2 个目录 362,479,616 可用字节d:smssocket运行 smssocket d 命令可以以调试模式运行短信接口服务程序，根据屏幕上输出的结果可以得知数据库的配置是否正确、是否可以连接上接口服务器等各种信息，请按照下面的步骤进行检测：d:smssocketsmssocket -dconnecting db: connstring - driver=oracle in orahome92;uid=sms;pwd=passwod;dbq=sms_server;mts=t .【成功】connectserver:【成功】ip=, port=6577logintoserver:【成功】result=成功querydatabase:【成功】records=0, sql=select id,mobile,sms_number,content,send_type from sms_send where result=0 and nvl(plan_time,0)=to_char(sysdate,yyyy-mm-dd hh24:mi:ss) and rownum50 order by priority1、查看数据库连接是否正常查看屏幕上输出的connecting db信息（上面图中黄颜色的信息），如果最后的结果为【成功】，表示接口数据库可以连接，如果为【失败】，请重新检测到数据库服务器的网络是否正常，配置文件中的数据库类型、数据库服务器、用户名和密码是否测试正确。如果是因为数据库客户端版本的原因造成无法连接，那么请使用odbcstring方式配置连接字符串。2、查看到服务器的连接是否正常查看屏幕上输出的connectserver信息（上面图中蓝色的信息），如果结果为【成功】，表示可以连接到服务器，如果结果为【失败】，请检查配置文件中的服务器配置是否正确，并检测计算机能否连接到互联网。3、查看能否登录到短信接口服务器查看屏幕上的logintoserver信息（上图中蓝色的信息），如果结果为【成功】，表示可以登录到服务器，如果结果为【失败】，请参考信息后面的具体出错原因，如果是用户名和密码错误，请检查配置文件中的设置是否正确。注意：当程序已经以服务方式在后台运行的时候，临时需要调试的话，必须先把服务停止（参考下一节），再进行调试，否则登录时会报“帐号已经在其他地方登录”错误。4、查看查询接口表是否正确查看屏幕上的querydatabase信息（上图中白色的信息），如果结果为【成功】，表示接口表正常，如果结果为【失败】，请检查数据库中的接口表是否正常创建，如创建表的时候将字段名称输入错误等。当以上的测试通过以后，可以尝试在数据库中插入发送短信的记录（详见第2.1.2节），短信接口服务程序应该能够检测到数据的插入并发送短信：querydatabase:【成功】records=1, sql=select id,mobile,sms_number,content,send_type from sms_send where result=0 and nvl(plan_time,0)=to_char(sysdate,yyyy-mm-dd hh24:mi:ss) and rownum50 order by prioritysmssubmit :【成功】number extend=, content=短信测试！smssubmitresp: result=0, messageid=1519053sendnotify : result=0, messageid=1519053, time=2007-02-12 19:52:40querydatabase:【成功】records=0, sql=select id,mobile,sms_number,content,send_type from sms_send where result=0 and nvl(plan_time,0)=to_char(sysdate,yyyy-mm-dd hh24:mi:ss) and rownum50 order by priorityreportnotify : result=0, messag