中国电信QChat 企业调度台与QCPS接口需求规范 0712.docx
《中国电信QChat 企业调度台与QCPS接口需求规范 0712.docx》由会员分享，可在线阅读，更多相关《中国电信QChat 企业调度台与QCPS接口需求规范 0712.docx（34页珍藏版）》请在冰豆网上搜索。
中国电信QChat企业调度台与QCPS接口需求规范0712
中国电信集团公司发布
中国电信QChat无线调度台
与QCPS接口需求规范
修订历史
时间
修订人
自审人
描述
创建文档
2011-10-31
预定义群组管理章节增加“增加群组”、“删除群组”
2011-12-20
修改http为https方式
2012-2-4
QCPS接口鉴权增加DeviceId用于识别企业调度台
2012-3-27
增加接口相关信息取值范围
2012-3-31
相关接口信息章节的接口取值
2012-4-10
用户登录账号要求为超级管理员账号
2012-5-12
系统返回码补充定义
2012-5-30
补充wsdl文档
2012-07-03
用户密码不返回
2012-07-12
增加群组成员重复错误码和描述定义
前言
本规范定义了中国电信股份有限公司（简称中国电信）CDMA网络中QChat业务部署系统（QCPS）与QChat无线调度台接口相关的接口需求和定义，以规范中国电信的QCPS和无线调度台的接口开发工作。
本规范由中国电信集团公司提出并归口。
本规范起草单位：
中国电信股份有限公司广州研究院
本规范主要起草人：
本规范参与制定单位：
1适用范围
本规范定义了中国电信股份有限公司（简称中国电信）CDMA网络中QChat业务部署系统（QCPS）与QCha无线调度台接口相关的接口需求和定义，为中国电信定制QCPS和无线调度台之间接口的研制、开发、生产、测试提供依据。
2参考资料
[1]
超文本传送协议（HypertextTransferProtocol）--HTTP/1.1---RFC2616
[2]
SOAP协议V1.1
[3]
SOAP协议V1.2
3缩略语
缩略语
英文全名
中文全名
SMS
ShortMessageService
短信息服务
GIS
GeographicInformationSystem
地理信息系统
PTT
PushToTalk
一键通呼叫
QCPS
QChatCarrierProvisioningSystem
QChat业务部署系统
4接口位置
接口位于QCPS与无线调度台之间。
QChat业务部署系统（QCPS）：
是QChat业务提供平台，它完成集团管理、群组管理、用户管理、系统配置等功能，为QChat企业调度台提供管理能力支持。
无线调度台部署在用户侧，QCPS接口应允许无线调度台通过中国电信IP专线、互联网接入，也允许无线调度台通过CTWAP接入。
5接口功能需求
5.1接口登录和操作鉴权
使用集团DeviceID、超级管理员账号和密码进行接口登录。
DeviceID长度位12的字符串，前4位代表厂家ID，由电信分配给调度台厂家。
后8位标识设备ID，调度台厂家自行分配。
集团超级管理员账号和密码是由中国电信负责创建并交给集团客户使用的。
当设备接入的时候QCPS会对DeviceID前4位厂家ID、超级管理员账号、密码进行鉴权，只有DeviceId前4位厂家ID、超级管理员账号、密码验证匹配后方可登录至QCPS进行操作。
接口只支持针对集团管理员管理范围的对象操作请求，即只无线调度台只能通过该接口完成用户、群组、群组成员进行相应的操作请求。
超出范围的操作请求，QCPS接口需拒绝。
下图是典型的接口登录和操作鉴权流程：
5.2Qchat管理功能
5.2.1集团管理
5.2.1.1查询集团
查询管理员所属集团的详细信息，包括但不限于：
集团名称、集团群组数量上限、集团用户数上限、普通管理员数量上限。
5.2.1.2集团内预定义组和用户查询
查询集团内所有预定义组（含预定义群组、预定义聊天室）、用户（含在该集团下不属于任何群组的用户）的信息。
预定义组信息包括：
群组号码，群组名称，群组主题，成员数上限，加入策略，群组类型，Domain。
用户信息包括：
用户名称、用户号码、成员默认优先级、状态、用户Domain、IMSI、用户呼叫能力配置。
如果查询结果记录数量过多，可以分多次返回查询结果。
5.2.2预定义组管理
接口支持对预定义群组进行如下管理。
接口支持通过群组号码、群组名称或群组短号码，来发起对指定群组的操作。
5.2.2.1查询群组
根据群组号码、群组名称或群组短号码查询群组的信息，信息包括但不限于：
群组号码，群组名称，群组主题，成员数上限，加入策略，群组类型，Domain。
5.2.2.2修改群组
根据群组号码、群组名称或群组短号码修改集团群组的信息，可修改的信息包括但不限于：
群组名称，群组主题，群组加入策略。
5.2.2.3添加群组
根据用户指定的群组名称、加入策略、群组类型、群组主题、成员上限等信息添加一个群组（也可以是聊天室），可指定的信息不包括群组号码。
接口创建完成（成功）后，返回被创建群组的号码。
5.2.2.4删除群组
根据群组号码删除指定的群组，删除群组前必须先删除群组内成员。
5.2.2.5查询群组成员
查询指定群组下的所有成员信息，包括：
用户号码、显示名称、成员类型、默认优先级。
如果查询结果记录数量过多，可以分多次返回查询结果。
5.2.2.6增加群组成员
在指定群组中添加一个群组成员，并设置该成员的如下信息：
用户号码、在该群组中的成员类型、显示名称、优先级。
接口支持一次增加多个组成员。
5.2.2.7修改群组成员
修改一个群组成员的相关信息，包括在该群组中的成员类型、优先级。
5.2.2.8删除群组成员
根据群组号码和用户号码删除指定群组中指定成员。
5.2.3用户管理
5.2.3.1查询用户
根据用户名称或用户号码查询用户信息，包括：
用户名称、用户号码、成员默认优先级、状态、用户Domain、IMSI、用户呼叫能力配置。
其中用户状态受“遥毙/复活”操作的影响。
5.2.3.2用户归属群组查询
根据用户名称或者用户号码查询所属群组信息（包括：
归属集团、群组号码、群组名称、群组主题、群组类型、群组加入策略）、以及用户在群组中的成员类型、显示名称、优先级。
5.2.3.3修改用户
根据用户名称或用户号码修改用户信息，可修改的用户信息包括：
密码、成员默认优先级、呼叫能力配置。
5.2.3.4呼叫限制（可选）
针对单个用户进行运营商级别的呼叫抑制配置。
包括添加用户CR、查询用户CR、修改用户CR、删除用户CR。
5.2.4遥毙/复活
接口支持对QChat用户遥毙/复活，使该用户失效/重新有效。
遥毙后的用户无法使用任何Qchat功能，复活后的用户可以恢复到正常使用状态。
遥毙/复活操作后，可以使用“查询用户”操作获取用户状态（状态包括：
活动、禁止..）。
5.2.5管理接口交互流程
典型的接口交互流程如下图：
上述交互中，如果请求应答结果记录数量过多，可以分多次返回应答结果。
6通讯协议
6.1传输层协议及应用层安全机制
传输层协议采用https协议，保障企业用户的数据安全。
服务器端（QCPS）与客户端（无线调度台）交互流程如图6-1所示：
图6-1采用https协议安全机制
6.2协议形式
无线调度台和QChat平台之间采用SOAP协议。
通信双方采用一问一答的通讯机制，即一次请求对应于一次应答。
一般情况，通信双方之间的消息发送后等待T秒后未收到响应，应立即重发，再连续发送N-1次后仍未得到响应则停发。
现阶段建议取值为：
T=60秒，N=1。
即在接口中规定的方法中，如超时后，暂时不考虑重发机制。
6.3数据类型
6.3.1日期与时间
日期与时间表示格式：
yyyy-MM-ddhh24:
mm:
ss。
表格61日期时间表示
项目
表示
说明
年
yyyy
年份；如2006年，表示为：
2006
月
MM
月份；如6月，表示为06；10月，表示为10
日
dd
日期；如5日，表示为05；20日，表示为20
时
HH24
小时，24进制；如上午9点，表示为09；下午5点，表示为17
分
mm
分钟；如5分钟，表示为05；55分钟表示为55
秒
ss
秒钟；如5秒钟，表示为05；55秒钟表示为55
6.3.2参数表示
1.接口输入参数格式表示规范：
基本类型（包括：
boolean、char、int、long、float、double、String）统一使用JAVA语言的String数据类型表示。
（举例：
StringringCode）
基本类型数组统一使用JAVA语言的String[]数据类型表示。
（举例：
String[]ringIDs）
自定义对象使用具体对象类型名称。
（举例：
OrderToneEvtevent）
自定义对象数组采用JAVA语言的对象数组表示格式：
对象类型名[]（举例：
Tone[]rings）
2.字符串长度表示规范：
格式：
String（length）
说明：
“（）”内为该字符串的长度，length为该长度的具体数值。
字符串的长度表示法分为如下三种：
区间式：
String（0-20）：
表示长度为0～20个字符的字符串
定长式：
String（14）：
表示长度为14个字符的定长字符串
离散式：
String（6,8,10）：
表示长度为6个字符或长度为8个字符或长度为10个字符的字符串
3.是否为空表示规范：
如果在详细说明中有默认值，可以为空，则若输入空，就使用默认值
4.数组长度表示规范：
格式：
Type[length]
说明：
“[]”内为该数组中元素的个数，length为该个数的具体数值。
数组表示法分为如下两种：
区间式：
String[0-20]：
表示有0～20个元素的字符串数组
UserInfo[0-50]：
表示有0～50个元素的UserInfo自定义对象数组
定长式：
String[14]：
表示有14个元素的字符串数组
UserInfo[50]：
表示有50个元素的UserInfo自定义对象数组
6.3.3接口约束
数字：
对于定长字段，右对齐、左补0；
字符：
对于定长字段，左对齐、右补空格；
XML文件中字符串编码为UTF-8；
FTP传输ASCII文件时，字符串编码为GB-2312；
文件头中“总记录数”不含文件头记录；
声明可以为空的记录字段不可填空；
6.3.4基础数据定义
6.3.4.1业务系统定义
业务系统编号
业务系统名称
说明
6.3.4.2返回代码定义
结果码（returnCode）
含义
-1
系统返回出错信息
-2
业务接口参数错误
0
成功
999999
Reserve2
9001
Head头信息不能为空
9002
非超级管理员或管理员名称或密码错误
9003
设备号长度必须为12位
9004
厂商ID不存在
9005
流水号长度必须为0-18位
1001
用户参数错误
1230
群组添加成员数不能超过10个
1232
群组删除成员数不能超过10个
1231
群组修改成员数不能超过10个
1233
非法参数值：
成员类型或优先级
2000
失败
100013
用户不存在
100014
群组成员不存在
100015
用户不归属管理员集团下
100016
被添加群组成员不能重复
300003
群组归属集团不存在/非法
300008
群组成员已达上限
300013
群组不存在/非管理员集团下
300016
用户已存在与该群组中
7接口描述
7.1服务描述WSDL文档
7.2服务端访问全地址
https:
//ip:
port/CPS_QED/services/QchatQEDService
7.3通用数据结构
1.输入参数：
将所有输入参数封装为各种类型的输入参数请求事件对象传递。
如果输入参数请求事件对象中有允空输入参数，可以不必赋值，直接保持为空即可。
如果输入参数请求事件对象中有2选1的输入参数，只需要输入其中一个，另外一个输入参数不必赋值，直接保持为空即可。
2.返回参数：
返回结果全部以各种类型的操作结果响应对象方式返回，返回内容至少包含本次操作的返回结果码。
操作结果响应对象需要返回的其他信息由各个接口具体功能决定。
8业务功能信息验证
8.1用户名密码验证
SOAP请求消息Header示例：
Header>
Password>password
Password>
Username>name
Username>
DeviceID>DeviceID
DeviceID>
Sequence>sequence
Sequence>
Header>
参数
说明
Username
集团管理员
Password
集团管理员密码,MD5加密（32位转大写），备注赋加密算法
DeviceID
DeviceID是长度位12的字符串，可以是数字或字母，前4位代表厂家ID，由电信分配给调度台厂家。
后8位标识设备ID，调度台厂家自行分配。
Sequence
操作序列号,作为一个流水号，便于在出现故障的时候查找问题，规则：
只要唯一就行，建议是：
YYYYMMDDHHMMSS+加上四位序列号,目前支持0-18位
备注：
MD5加密算法
importjava.security.MessageDigest;
MessageDigestmd=MessageDigest.getInstance（"MD5".toUpperCase（））;
byte[]result=md.digest（res）;
for（inti=0;imd.update（result[i]）;
}
byte[]hash=md.digest（）;
StringBufferd=newStringBuffer（""）;
for（inti=0;iintv=hash[i]&0xFF;
if（v<16）
d.append（"0"）;
d.append（Integer.toString（v,16）.toUpperCase（））;
}
转码结果=d.toString（）;
转码实例：
明文：
123456
加密：
4280D89A5A03F812751F504CC10EE8A5
9业务功能接口定义
9.1集团管理
9.1.1查询集团
1.接口信息
接口名称
查询集团
接口概述
查询管理员所属集团的详细信息，包括但不限于：
集团名称、集团群组数量上限、集团用户数上限、普通管理员数量上限。
请求接口
QueryCompany
应答消息名
CompanyResponse
2.请求参数说明，调用公共查询请求类QueryRequest,mainParam的值为集团管理员名称，startPos,pageSize可为空
类名
成员名
可空否
类型
说明
QueryRequest
mainParam
是
String[0-20]
查询条件参数，根据具体接口填值
startPos
否
int
起始位置
pageSize
否
int
查询条数（默认10条，可商讨）
3.应答参数说明：
类名
成员名
可空否
类型
说明
CompanyResponse
response
是
Response
返回结果码及描述
companyInfo
是
CompanyInfo
集团信息
9.1.2查询集团预定义组
1.接口信息
接口名称
查询集团预定义组
接口概述
查询集团内所有预定义组（含预定义群组、预定义聊天室）的信息。
请求接口
QueryCompanyGroup
应答消息名
CompanyGroupResponse
2.请求参数说明，调用公共查询请求类QueryRequest,mainParam的值为集团管理员名称，startPos,pageSize不为空
类名
成员名
可空否
类型
说明
QueryRequest
mainParam
是
String[0-20]
查询条件参数，根据具体接口填值
startPos
否
int
起始位置
pageSize
否
int
查询条数（默认10条，可商讨）
3.应答参数说明
类名
成员名
可空否
类型
说明
CompanyGroupResponse
response
是
Response
返回结果码及描述
count
否
int
集团内群组总数
groupInfo
是
GroupInfo[0-n]
如果查出数据量小于请求参数pageSize则返回当然系统的全部数据，如果大于pageSize,则返回请求参数pageSize条数据，用户下次请求可根据startPos与pageSize算出下次查询的起始位置
9.1.3查询集团用户
1.接口信息
接口名称
查询集团内用户
接口概述
查询集团内所有用户信息，包括：
用户名称、用户号码、成员默认优先级、状态、用户Domain、IMSI、用户呼叫能力配置。
请求接口
QueryCompanyUser
应答消息名
CompanyUserResponse
2.请求参数说明:
调用公共查询请求类QueryRequest,mainParam的值为集团管理员名称，startPos,pageSize必须填
类名
成员名
可空否
类型
说明
QueryRequest
mainParam
是
String[0-20]
查询条件参数，根据具体接口填值,可为空（服务端取值为登陆管理员名称）
startPos
否
int
起始位置
pageSize
否
int
查询条数（默认10条，可商讨）
3.应答参数说明
类名
成员名
可空否
类型
说明
CompanyUserResponse
response
是
Response
返回结果码及描述
count
否
int
集团内用户总数
userInfo
是
UserInfo[0-n]
如果查出数据量小于请求参数pageSize则返回当然系统的全部数据，如果大于pageSize,则返回请求参数pageSize条数据，用户下次请求可根据startPos与pageSize算出下次查询的起始位置
9.2预定义组管理
9.2.1查询群组
1.接口信息
接口名称
查询群组
接口概述
根据群组号码查询群组的信息，信息包括但不限于：
群组号码，群组名称，群组主题，成员数上限，加入策略，群组类型，Domain。
请求接口
QueryGroup
应答消息名
GroupResponse
2.请求参数说明:
调用公共查询请求类QueryRequest,mainParam的值为群组号码，startPos,pageSize可为空
类名
成员名
可空否
类型
说明
QueryRequest
mainParam
是
String[0-20]
查询条件参数，根据具体接口填值
startPos
否
int
起始位置
pageSize
否
int
查询条数（默认10条，可商讨）
3.应答参数说明
类名
成员名
可空否
类型
说明
GroupResponse
response
是
Response
返回结果码及描述
groupInfo
是
groupInfo
群组信息
9.2.2增加群组
1.接口信息
接口名称
增加群组
接口概述
在指定集团中添加1个群组，并设置该群组的如下信息：
群组号码、群组名称、群组主题、成员数上限、加入策略、群组类型、Domain。
请求接口
AddGroup
应答消息名
AddGroupResponse
2.请求参数说明
类名
成员名
可空否
类型
说明
AddGroupRequest
adminAccount
是
String[0-20]
集团管理员名称
groupInfo
是
GroupInfo
GroupInfo里的信息，groupCode为空
3.应答参数说明
类名
成员名
可空否
类型
说明
AddGroupResponse
response
是
Response
返回结果码及描述,reserve为群组号码
9.2.3删除群组
1.接口信息
接口名称
删除群组
接口概述
根据群组号码删除群组
请求接口
deleteGroup
应答消息名
DeleteGroupResponse
2.请求参数说明
类名
成员名
可空否
类型
说明
GroupRequest
groupInfo
是
GroupInfo
GroupInfo里的信息关键字groupCode
3.应答参数说明
类名
成员名
可空否
类型
说明
DeleteGroupResponse
response
是
Response
返回结果码及描述
9.2.4修改群组
1.接口信息
接口名称
修改群组
接口概述
根据群组号码修改群组的信息，信息包括：
群组名称，群组主题，群组成员数上限值。
请求接口
updateGroup
应答消息名
GroupUpdateResponse
2.请求参数说明
类名
成员名
可空否
类型
说明
GroupRequest
groupInfo
是
GroupInfo
群组信息，只填可修改的，目前可修改的为群组名称、群组主题，GroupInfo里的信息，关键字groupCode
3.应答参数说明
类名
成员名
可空否
类型
说明
GroupUpdateResponse
response
是
Response
返回结果码及描述
9.2.5查询群组成员
1.接口信息
接口名称
查询群组成员信息
接口概述
查询指定群组下的所有成员信息，包括：
用户号码、显示名称、成员类型、默认优先级
请求接口
queryGroupMember
应答消息名
GroupMemberResponse
2.请求参数说明:
调用公共查询请求类QueryRequest,mainParam的值为群组号码，startPos,pageSize不能为空
类名
成员名
可空否
类型
说明
QueryRequest
升级会员 