MAS服务器WebService接口用户开发指导手册.doc

MAS 移动信息机 Web Service API 接口用户手册 1 MAS 服务器 Web Service 接口 用户开发指导手册 V2 2 嘉讯软件 2007 12 MAS 移动信息机 Web Service API 接口用户手册 2 修订记录 ID修订历史修改人日期 初稿 V1 0陈铁钢2006 4 1 修改稿 V1 1高乐平2006 12 12 修改稿 V2 1何小波2007 12 17 修改稿 V2 2王斌2007 12 27 修改稿 V2 2陶永江2008 09 25 MAS 移动信息机 Web Service API 接口用户手册 3 目目 录录 1简介简介 4 2访问访问 WEBSERVICE 服务地址服务地址 4 3创建创建 WEBSERVICE 接口接口 4 4WEBSERVICE 接口方法说明接口方法说明 5 4 1Init 方法 5 4 2sendSM 方法 6 4 3sendSM 方法 7 4 4sendSM 方法 7 4 5sendSM 方法 8 4 6sendSM 方法 9 4 7sendSM 方法 9 4 8sendPDU 方法 10 4 9sendPDU 方法 11 4 10sendSmAndPDU 方法 12 4 11release 方法 13 5客户端调用方法 客户端调用方法 MT 发送短信 发送短信 14 6接收接收 MO 和状态报告的方式切换和状态报告的方式切换 15 7接收接收 MO 和状态报告和状态报告 15 7 1前提条件 15 8被动接收被动接收 MO 上行短信上行短信 16 8 1被动接收 MO 上行短信的 XML 定义 16 8 2如何被动接收上行 XML 16 8 3小结 18 9被动接收状态报告被动接收状态报告 18 9 1被动接收状态报告的 XML 定义 18 10主动接收主动接收 MO 上行短信上行短信 19 11主动接收状态报告主动接收状态报告 19 12错误码使用说明错误码使用说明 19 13附录附录 20 13 1短信发送方法返回错误码 20 MAS 移动信息机 Web Service API 接口用户手册 4 13 2回执编码列表 20 13 3回执编码列表 21 1 简介简介 本文档用于客户端 通过 MAS 提供的 WebService 服务发送和接收各种短信的开发指导 缩略语清单 client 所有通过Web Service 接口接入 MAS 的客户端 MAS 中国移动代理服务器 Web Service接口API功能概述 1 MT短信发送 2 MO短信接收 3 RPT 状态报告接收 2 访问访问 WebService 服务地址服务地址 WSDL http 127 0 0 1 80 axis services SMsg wsdl 地址 http 127 0 0 1 80 axis services SMsg 注意 这里 127 0 0 1 只是 IP 示例 实指用户 MAS 机器的 IP 地址 这里 80 只是端口示例 实指用户 MAS 服务的端口号 代码中写死 80 建议不要更 改 在 IE 中任意输入以上两个 url 地址 如可以访问到服务 没有出现异常 则表示 WebService 服务已正常启动 可以进行以下开发 3 创建创建 WebService 接口接口 在 web 页面中登陆信息机 进入系统管理 接口管理新增页面如下图 MAS 移动信息机 Web Service API 接口用户手册 5 1 选择接口类型为 web service 接口 2 如果不需要回执 回执要求一项选择为不支持回执 3 短信回执目标 url 一项为客户端被动接收回执的 URL 根据用户自己需要填写 4 mo 目标 url 一项为客户端被动接收 MO 的 URL 根据用户自己需要填写接口说明 5 如果不需要回执和 mo 短信回执目标 url 和 mo 目标 url 可填空 6 接口状态选运行状态 否则短信无法发送成功 7 其他几项用户根据自己需要填写 4 WebService 接口方法说明接口方法说明 适用的 MAS 版本 MAS 1 1 070807 SRC MAS1 1 P10D071225 MAS1 1 P10D071225 webService API2 2 M01D071228 4 14 1 InitInit 方法方法 方法说明 方法说明 在进行 MT MO RPT 操作前必须调用该方法 使用中修改了某个 DB 连接参 数必须重新调用该方法 操作中出现数据库异常需重新调用该方法 当客户调用了 release 方法后 需要重新调用该方法才可进行发送和接收短信 public int init String dbIp String dbName String dbPort String user MAS 移动信息机 Web Service API 接口用户手册 6 String pwd 参数说明 参数说明 参数参数描描 述述 dbIpMas 的 ip 地址 必填 dbName数据库名称 必填 dbPort数据库端口 必填 user接口创建时的接口登录用户名 必填 pwd接口创建时的接口登录密码 必填 返回值返回值0 表示成功 其它表示失败 详情查看本文档 api 返回 值列表 4 24 2 sendSMsendSM 方法方法 方法说明 方法说明 发送一条 MT 短信到一个手机号码 手机号码集 没有 SRCID public int sendSM String apiCode String loginName String loginPwd String mobiles String content long smID 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 Content短信内容 超过 260 个字符部分会被截断 必填 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 缺省值 0 可为空 返回值返回值0 表示成功 其它表示失败 MAS 移动信息机 Web Service API 接口用户手册 7 4 34 3 sendSMsendSM 方法方法 方法说明 方法说明 发送一条 MT 短信到一个手机号码 手机号码集 public int sendSM String apiCode String loginName String loginPwd String mobiles String content long smID long srcID 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 content短信内容 超过 260 个字符部分会被截断 必填 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 缺省值 0 可为空 SrcID终端源地址 返回值返回值0 表示成功 其它表示失败 4 44 4 sendSMsendSM 方法方法 方法说明 方法说明 发送一条 MT 短信到一个手机号码 手机号码集 Public int sendSM String apiCode String loginName String loginPwd String mobiles String content long smID String url MAS 移动信息机 Web Service API 接口用户手册 8 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 Content短信内容 超过 260 个字符部分会被截断 必填 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 必填 urlWAP Push 短信的 URL 为 或 null 时则发送常规 短信 返回值返回值0 表示成功 其它表示失败 4 54 5 sendSMsendSM 方法方法 方法说明 方法说明 发送一条 MT 短信到一个手机号码 手机号码集 Public int sendSM String apiCode String loginName String loginPwd String mobiles String content long smID long srcID String url 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 Content短信内容 超过 260 个字符部分会被截断 必填 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 必填 srcID终端源地址 缺省值为 smID 可为空 MAS 移动信息机 Web Service API 接口用户手册 9 urlWAP Push 短信的 URL 为 或 null 时则发送常规 短信 返回值返回值0 表示成功 其它表示失败 4 64 6 sendSMsendSM 方法方法 方法说明 方法说明 发送一条 MT 短信到一个手机号码 手机号码集 public int sendSM String apiCode String loginName String loginPwd String mobiles String content String sendTime long smID long srcID 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 Content短信内容 超过 260 个字符部分会被截断 必填 sendTime定时发送时间 为空时立即发送 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 必填 srcID终端源地址 0 到 99999999 中的某一整数 返回值返回值0 表示成功 其它表示失败 4 74 7 sendSMsendSM 方法方法 方法说明 方法说明 发送一条 MT 短信到一个手机号码 手机号码集 public int sendSM String apiCode MAS 移动信息机 Web Service API 接口用户手册 10 String loginName String loginPwd String mobiles String content long smID long srcID String url String sendTime 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 Content短信内容 超过 260 个字符部分会被截断 必填 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 必填 srcID终端源地址 缺省值为 smID 可为空 urlWAP Push 短信的 URL 为 或 null 时则发送常规 短信 可为空 sendTime定时发送时间 为空时立即发送 返回值返回值0 表示成功 其它表示失败 4 84 8 sendPDUsendPDU 方法方法 方法说明 方法说明 发送 PDU 短信内容到一群手机号码 public int sendPDU String apiCode String loginName String loginPwd String mobiles byte content long smID int msgFmt int tpPID int tpUdhi String feeTerminalID String feeType MAS 移动信息机 Web Service API 接口用户手册 11 String feeCode int feeUserType 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 Content短信内容 超过 260 个字符部分会被截断 必填 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 必填 msgFmt短信编码格式 最终通过 cmpp21 协议发送至网关的 短信格式 具体类型请参见 cmpp21 或 cmpp30 协议 文档 默认为 0 tpPID默认为 0 具体请参见 cmpp21 或 cmpp30 协议文档 tpUdhi默认为 0 具体请参见 cmpp21 或 cmpp30 协议文档 feeTerminalID被计费用户的号码 默认为空 feeType资费类别 默认为空 feeCode资费代码 默认为空 feeUserType计费用户类型 默认为 0 返回值返回值0 表示成功 其它表示失败 4 94 9 sendPDUsendPDU 方法方法 方法说明 方法说明 发送 PDU 短信内容到一群手机号码 public int sendPDU String apiCode String loginName String loginPwd String mobiles byte content long smID long srcID int msgFmt int tpPID int tpUdhi MAS 移动信息机 Web Service API 接口用户手册 12 String feeTerminalID String feeType String feeCode int feeUserType 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 Content短信内容 超过 260 个字符部分会被截断 必填 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 必填 SrcID终端源地址 0 到 99999999 中的某一整数 msgFmt短信编码格式 最终通过 cmpp21 协议发送至网关的 短信格式 具体类型请参见 cmpp21 或 cmpp30 协议 文档 默认为 0 tpPID默认为 0 具体请参见 cmpp21 或 cmpp30 协议文档 tpUdhi默认为 0 具体请参见 cmpp21 或 cmpp30 协议文档 feeTerminalID被计费用户的号码 默认为空 feeType资费类别 默认为空 feeCode资费代码 默认为空 feeUserType计费用户类型 默认为 0 返回值返回值0 表示成功 其它表示失败 4 104 10 sendSmAndPDUsendSmAndPDU 方法方法 方法说明 方法说明 发送 PDU 短信内容到一群手机号码 private int sendSmAndPdu String apiCode String loginName String loginPwd String mobiles String content long smID MAS 移动信息机 Web Service API 接口用户手册 13 long srcID String url String sendTime int msgFmt int tpPID int tpUdhi String feeTerminalID String feeType String feeCode int feeUserType int smType 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 mobiles短信发送的目的手机号码 可以填写多个 但必须以 英文分号隔开 必填 如13500000001 必填 Content短信内容 超过 260 个字符部分会被截断 必填 smID短信 ID 0 到 99999999 中的某一整数 确保唯一后 可以用来找到对应的回执 回复 必填 SrcID终端源地址 0 到 99999999 中的某一整数 urlWAP Push 短信的 URL 为 或 null 时则发送常规 短信 url 的长度不能超过 85 原 API 中判断不能 110 现改为不能 85 必填 sendTime定时发送时间 为空时立即发送 msgFmt短信编码格式 最终通过 cmpp21 协议发送至网关的 短信格式 具体类型请参见 cmpp21 或 cmpp30 协议 文档 默认为 0 tpPID默认为 0 具体请参见 cmpp21 或 cmpp30 协议文档 tpUdhi默认为 0 具体请参见 cmpp21 或 cmpp30 协议文档 feeTerminalID被计费用户的号码 默认为空 feeType资费类别 默认为空 feeCode资费代码 默认为空 feeUserType计费用户类型 默认为 0 SmType短信类型 默认为 0 普通短信 PDU 短信 值为 2 返回值返回值0 表示成功 其它表示失败 MAS 移动信息机 Web Service API 接口用户手册 14 4 114 11 releaserelease 方法方法 方法说明 方法说明 释放资源 调用该方法后 不能再发短信和主动接收 MO RPT private int release 参数说明 参数说明 无参数 5 客户端调用方法 客户端调用方法 MT 发送短信 发送短信 摘要 摘要 本章详细介绍了如何使用客户端组件提交发送短信请求 采用 Java 语言开发 支持目前主流的各种平台 包括 Windows Unix Linux 操作系统 实例程序参考 Demo 目录下 DemoFrame java 短信平台客户端编程实例 描述 开发语言为 JAVA 该说明适用于 JAVA 程序员 该实例适用于 windows Linux 所有 UNIX 可安装 JDK1 4 以上版本和 JCE 操作系统 不能用于手持设备 注 如果使用 JDK1 4 以上版本不需要额外安装 JCE 如果使用 JDK1 3x 请安装 JCE 该实例采用了 Apache 组织的 axis 项目的库完成 SOAP 协议 Over HTTP 功能 版本是 1 1RC2 你也可以采用其他你所熟悉的 SOAP 兼容库 Apache AXIS 的详细介绍请参见 http ws apache org axis 通过 SSL 发送短信的实现参照该方式自行解决 该程序的逻辑说明请参见短信平台客户端开发的相关文档 该程序只作为参考实现 未考虑运行效率 请客户端开发者根据自己的实际情况修改 例如尽量减少网络连接请求次数等 使用步骤 以下仅供参考 1 利用 axis 的 wsdl2java 工具生成 java 客户端程序 b 直接使用批处理文件生成客户端 先通过记事本打开 smg wsdl 文件 修改所有的 http 127 0 0 1 80 axis services SMsg 将 IP 地址和端口改成 WebService 服务端的 IP 地址和端口 再执行发布包根目录下的 create bat 文件 则会自动生成 client 文件夹 b 可以直接通过命令行生成客户端 方法为 java cp org apache axis wsdl WSDL2Java MAS 移动信息机 Web Service API 接口用户手册 15 例如 假设 axis 1 2 装在 E ProgramFiles java cp E ProgramFiles axis 1 2 lib mail jar E ProgramFiles axis 1 2 lib activation jar E ProgramFiles axis 1 2 lib axis jar E ProgramFiles axis 1 2 lib axis ant jar E ProgramFiles axis 1 2 lib commons discovery 0 2 jar E ProgramFiles axis 1 2 lib commons logging 1 0 4 jar E ProgramFiles axis 1 2 lib jaxrpc jar E ProgramFiles axis 1 2 lib log4j 1 2 8 jar E ProgramFiles axis 1 2 lib saaj jar E ProgramFiles axis 1 2 lib wsdl4j 1 5 1 jar org apache axis wsdl WSDL2Java c smg wsdl p client p 后面为生成的 java 类的包名 用户可根据需要自己定义 注意 注意 127 0 0 1127 0 0 1 实际填写是实际填写是 MASMAS 机器的机器的 IPIP 地址 地址 2 在 c 根目录下生成 client 文件夹 里面有 java 客户端代理程序 SMsg PortType java SMsgService java SMsgServiceLocator java SMsgSoapBindingStub java 3 将这几个 java 类导入你的开发工程 4 如实例程序 DemoFrame java 所示的进行调用 SMsgService service new SMsgServiceLocator SMsg PortType client service getSMsg String result client sendSM apiCode loginName loginPwd mobiles content smId 5 切记要引入 lib 目录下的 jar 文件 6 接收接收 MO 和状态报告的方式切换和状态报告的方式切换 MAS 提供主动接收 MO 状态报告和被动接收 MO RPT 两种方式 两种方式可以灵 活切换 方法如下 用任意一种文本编辑器打开 mas WEB INF 目录下的 umaconfig Att xml 文件可以看 到 true 默认状态下 isPassivityMOnRPT 元素值为 true 即为使用被动接收 MO RPT 的方式 具体实现方法参考文档第 7 8 9 点 将其修改为 false 或者 0 保存修改后重新启 动 TOMCAT 即可切换为主动接收 MO RPT 具体实现方法参考文档第 7 10 11 点 MAS 移动信息机 Web Service API 接口用户手册 16 7 接收接收 MO 和状态报告和状态报告 MAS 通过 HTTP 的方式向客户端推送 MO 短信和状态报告 7 17 1 前提条件前提条件 确保用户已经创建 webservice 接口 与上行相关的信息有以下几点 Mo 目标 url 客户端接收 MO 短信的 url 地址 如 http 客户端 IP 端口 UPReceiver asp 短信回执目标 url 客户端接收回执的 url 地址 如 http 客户端 IP 端口 UPReceiver asp 8 被动接收被动接收 MO 上行短信上行短信 摘要摘要 本章详细介绍了如何被动接收用户手机的上行短信 8 18 1 被动接收被动接收 MOMO 上行短信的上行短信的 XMLXML 定义定义 节点说明 节点说明 节节 点点描描 述述 apicode接口编号 mobile发送短信的手机号码 sm idMO 短信的短信 ID content短信内容 1 移动服务器端的上行组件将上行短信组织成 XML 然后根据 API 调用程序所在地址调用程序所在地址主动 提交给特定的 jsp 文件处理 2 服务端每次最多只返回 200 个 MO 短信 MAS 移动信息机 Web Service API 接口用户手册 17 8 2 如何被动接收上行如何被动接收上行 XML 在此以 java jsp 为例 jsp1 begin end 本节介绍了如何编写被动接收上行短信 XML 流的 jsp 文件 linux unix 其中 jsp 只是 简单的将此 XML 流存成文件 企业可以根据自己的需要做更多的事情 8 38 3 小结小结 本章介绍了如何被动接收上行短信 可以将此理解为被动接收 MO 的时候是移动 服务器向企业客户端 PUSH 推 MO 短信的过程 9 被动接收状态报告被动接收状态报告 被动接收状态报告的过程和被动接收上行短信处理方法一致 9 19 1 被动接收状态报告的被动接收状态报告的 XMLXML 定义定义 节点说明 节点说明 节节 点点描描 述述 MAS 移动信息机 Web Service API 接口用户手册 19 apicode接口编号 mobile发送短信的手机号码 sm id发送短信的短信 ID code回执编码 desc回执描述 1 移动服务器端的上行组件将上行短信组织成 XML 然后根据 API 调用程序所在地址主动 提交给特定的 jsp 文件处理 2 服务端每次最多只返回 200 个 RPT 10主动接收主动接收 MO 上行短信上行短信 主动接收 MO 上行短信的方式和发送短信的方式类似 主要是通过调用 MAS 提 供的 webService 接口所提供的接收方法而实现 可以理解为主动接收是客户系统主动 往 MAS 系统获得 MO 短信的过程 Java 方法如下 方法说明 方法说明 主动接收短信上行 public String recvMo String apiCode String loginName String loginPwd 参数说明 参数说明 参数参数描描 述述 apicode接口编码 必填 loginName接口创建时的接口登录名 必填 loginPwd接口创建时的接口登录密码 必填 返回值返回值返回信息 例如接收到的短信或者提示 11主动接收状态报告主动接收状态报告 主动接收状态报告的