中国电信定位调度产品定制接口规范.docx
《中国电信定位调度产品定制接口规范.docx》由会员分享，可在线阅读，更多相关《中国电信定位调度产品定制接口规范.docx（16页珍藏版）》请在冰豆网上搜索。
中国电信定位调度产品定制接口规范
保密等级：
中国电信集团公司发布
2010-××-××实施
2010-××-××发布
中国电信定位调度产品规范
定制接口规范
Q/CTXXXX.1-2010
中国电信集团公司技术标准
内部修订记录
版本
日期
负责人
描述
0.5
2010/07/22
张玉良/雷澍/吴彦津
制定规范基本框架、内容
0.6
2010/10/13
张玉良/雷澍/吴彦津
0.9
2010/11/18
雷澍/吴彦津
根据e家关爱、gota等产品需求调整部分接口
征求意见稿
2010/11/19
吴彦津
全文统稿
征求意见稿（修订稿）
2010/12/3
吴彦津/赵强
根据收集的意见，进行修订
目录
前言I
1.目的及适用范围1
2.引用标准1
3.术语及缩略语2
4.概述3
4.1.命名规则3
4.2.经纬度数据格式3
4.3.涉及系统3
4.4.业务编码3
5.接口功能5
5.1.GIS接口5
5.1.1.地图操作5
5.1.2.POI管理7
5.1.3.围栏功能7
5.1.4.地理数据编译7
5.1.5.轨迹管理8
5.1.6.人员对象管理8
5.2.定位及通信接口8
5.2.1.定位接口9
5.2.2.短信接口10
5.2.3.终端管理接口12
5.2.4.告警接口13
6.接口安全管理14
6.1.KEY生成规则15
6.2.接口鉴权流程15
7.接口使用流程17
7.1.企业客户使用流程17
7.2.SI使用流程18
8.业务资费19
8.1.资费结构与资费标准19
8.2.计费原则19
8.3.收费方式20
9.附录21
1前言
本规范是中国电信定位调度产品系列规范之一，本规范定义了定位调度平台定位能力开放接口的技术实现方案及要求。
本规范版权由中国电信集团公司所有，未经许可，不得以任何方式复制或抄袭本规范之部分或全部内容。
本规范解释权属于中国电信集团公司。
本规范起草单位：
中国电信股份有限公司广州研究院
本规范主要起草人：
吴彦津、雷澍、赵强、张玉良
1.目的及适用范围
为规范企业客户接入使用定位调度平台开放接口能力，明确定位调度平台所提供的开放能力，指导企业和应用集成商（ServiceIntegrater，以下简称SI）基于定位调度平台提供的开放能力，进行二次开发，特制定本规范。
本规范规定了中国电信定位调度平台能力开放接口（以下简称定位调度能力开放接口）的业务功能、技术实现方案，接口定义、接口使用流程等。
本规范对中国电信定位调度能力开放接口技术范畴提出规定，原则上由中国电信集团公司内部和厂商共同使用，用于定位调度产品招标选型、工程建设、运行维护及设备开发方面为集团公司和省公司提供技术依据。
2.引用标准
下列文件通过本文的参考而成为本规范的条款。
凡是注日期的参考文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本文，凡是不注日期的参考文件，其最新版本适用于本文。
【1】《中国电信CMDA定位业务相关技术要求》
【2】《800MhzCDMA无线定位业务L1接口协议基本要求》
【3】《CDMA1X数字蜂窝移动通信网移动台规范-对支持V2版定位业务移动台的要求》
【4】《800MhzCDMA无线定位业务L1接口协议较高要求》
【5】《中国电信定位调度业务规范》
【6】《中国电信定位调度技术规范》
3.术语及缩略语
CDMA
CodeDivisionMultipleAccess
码分多址
CRM
CustomerRelationshipManagemen
（中国电信）客户关系管理系统
ISMP-B
IntegratedServiceManagementPlatform-B
中国电信领航平台简称
JS
JavaScript
Java脚本语言
WebServices
WebServices
网络服务
SOAP
SimpleObjectAccessProtocol
简单对象访问协议
URL
UniformResourceLocation
统一资源定位符
XML
eXtensibleMarkupLanguage
可扩展标记语言
MDN
MobileDirectoryNumber
移动台号码簿号码
MPC
MobilePositionCenter
移动定位中心
PDE
PositionDeterminingEntity
定位实体
POI
PointOfInteresting
兴趣点
4.概述
本规范规定了中国电信定位调度能力开放接口功能，用于定位调度能力开放接口的设计和开发，同时提供给接入使用定位调度平台的企业和SI等第三方。
本规范制定的接口，将根据后续新的需求同步进行开发和升级。
4.1.命名规则
本规范接口函数名称命名规则：
以get/set方式来命名，即使用动宾结构的命名，如如获取历史位置数据的函数名为：
StringgetLastestLocationRequest（Stringkey,Stringterminals）
4.2.经纬度数据格式
本规范涉及的经纬度数据格式为：
以20位字节数值表示，格式如ddd.dddddddddddddddd，小数点前后均表示“度”值。
4.3.涉及系统
1、定位调度平台：
本规范所定义的能力开放接口的提供平台。
2、企业IT系统：
本接口的使用方，包括SI，以下统称为企业IT系统。
3、集团领航平台：
政企业务及企业客户管理平台。
4.4.业务编码
1、短信接入码
短信接入码是定位调度平台和移动终端用户以短信方式进行通信的业务接入号码。
短信接入码为：
106598511000。
2、定位调度平台IP/URL
定位调度平台IP地址是企业IT系统接入使用接口能力时访问的地址。
5.接口功能
定位调度平台接口功能主要包括两个大类：
●GIS功能及地图数据提供接口（简称GIS接口）
●定位查询及通信使用接口（简称定位及通信接口）
GIS接口主要提供对电子地图数据的展现、操作、事件管理、嵌入网页等功能，通过JavaScript将地图数据嵌入企业客户的网页中。
本接口提供与地图交互、向地图添加内容等系列方法。
定位及通信接口封装了中国电信精定位、粗定位、短信收发等功能，提供对企业终端号码的管理、告警查询等功能。
通过本系列接口，结合GIS接口，客户根据自身企业需求，实现LBS相关功能。
本章节主要描述GIS接口、定位及通信接口的功能特性及需求约束，详细的接口定义和使用示例，请参考《中国电信定位调度产品-定制接口开发文档》。
5.1.GIS接口
定位调度台提供使用flex技术开发的地图功能，嵌入到企业IT系统的相关页面内，通过JavaScript脚本，与该页面内的其他元素交互。
本规范提供的GIS接口，包括JavaScript和SOAP协议的接口描述。
本节从用户使用电子地图的角度，对GIS可提供的功能进行描述。
详细的接口使用方法请参考《中国电信定位调度产品-定制接口开发文档》。
5.1.1.地图操作
●创建地图：
根据请求生成地理信息文件。
•地图格式：
支持的格式为flex地图。
●图层管理：
可对地图划分不同的图层，同时根据请求，具备不同图层信息的地图数据。
图层可以划分为地图背景、路网信息（高速道路、国道、省道、城市主干道、一般道、细街道等）、POI层等。
•图层包括地图背景、路网信息（高速道路、国道、省道、城市主干道、一般道、细街道等）、POI层等。
•用户可指定图层，发起地图请求，不同图层数据可合并显示。
●平移地图：
系统响应用户的鼠标、键盘操作，对地图进行四向平移操作。
●设置缩放级别：
客户对地图对象设置地图缩放级别，提供地图缩放功能。
●鹰眼功能：
即缩略的示意图，是一个缩小了的整副地图，在上面可以看到当前地图的视野访问所处在整个地图的位置。
●绘图：
在已创建的地图对象上，绘制各种几何元素或地理对象。
•几何元素包括直线、折线、圆、椭圆等
•地理对象包括POI、道路、人员对象等
●几何测算（测距）：
进行几何要素的测算。
目前支持的操作包括计算两点之间的直线距离；判定点是否在某个指定的区域内。
测算功能可以通过一次请求完成多个点的测算操作。
●路径规划：
根据起点和终端，计算两点之间的各种方式（自驾车、公交车、步行）的路线。
●生成地图图片：
根据接口请求生成地图图片
•地图格式：
支持的格式为png、jpg格式。
•地图比例：
支持根据请求输出指定比例地图。
•地图大小：
最小支持180*220像素及以上。
5.1.2.POI管理
●搜索POI：
根据关键字搜索地图数据库，返回符合搜索条件的POI。
搜索方式包括距离最近查找、按范围查找、和根据属性（如名称、电话号码等）查找。
●创建POI：
在已创建的地图对象上创建POI。
在地图上创建的POI对象可以被用户用鼠标拖拽。
•编辑POI：
提供相应编辑功能，可编辑已创建的POI对象，可直接在地图上进行编辑。
•删除POI：
提供相应删除功能，删除已创建的POI对象。
可直接在地图上删除对象。
●显示/隐藏POI：
在地图上显示/隐藏已创建的POI对象。
5.1.3.围栏功能
●创建围栏：
在地图上创建电子围栏对象，围栏样式为预定义好的矩形、圆形、椭圆形、多边形、线条等。
可直接在地图上对电子围栏对象进行编辑。
•编辑围栏：
提供相应编辑功能，可编辑已创建的电子围栏对象，可直接在地图上进行编辑。
•删除围栏：
提供相应删除功能，删除已创建的电子围栏对象，可直接在地图上删除对象。
●显示/隐藏围栏：
在地图上显示/隐藏已创建的电子围栏对象。
5.1.4.地理数据编译
●地理编码：
把一个街道地址或邮编编码成一个经纬度信息，经纬度信息格式参见章节4.2数据格式。
●反向地理编码：
把一个经纬度信息反编码成一个街道地址或邮编。
5.1.5.轨迹管理
●创建轨迹：
在地图上创建一个人员（或车辆等）对象的一段时间内的活动轨迹，并显示。
•清除围栏：
提供相应清除功能，清除已创建的轨迹对象。
●播放轨迹：
根据时间顺序，在地图上以动画形式播放人员（或车辆）对象的活动轨迹。
5.1.6.人员对象管理
●创建人员：
在地图上创建人员对象，可直接在地图上对人员对象进行编辑。
•编辑人员：
提供相应编辑功能，可编辑已创建的人员对象，可直接在地图上进行编辑，如名称、号码等。
•删除人员：
提供相应删除功能，删除已创建的人员对象，可直接在地图上删除对象。
●显示/隐藏人员：
在地图上显示/隐藏已创建的人员对象。
5.2.定位及通信接口
描述定位调度平台的定位及通信接口功能，包括定位接口、短信接口、终端管理接口、告警接口。
定位及通信接口采用WebServices方式提供。
详细的接口定义包括请求要素定义、应答要素定义、业务接口返回码、接口使用示例。
5.2.1.定位接口
包括请求单次定位、请求连续定位、请求终端最新位置信息、获取终端历史位置数据等定位功能接口，用户通过该系列接口可以获取指定的移动终端的位置信息（经纬度信息）、对指定号码进行连续定位、请求终端最新位置信息和历史定位数据等。
●单次定位：
企业IT系统通过发送定位请求接口向定位调度平台发起对指定的终端（或终端列表）进行定位的请求，定位调度平台进行鉴权通过以后，返回请求处理结果。
定位调度平台获取指定终端的当前位置信息，以标准格式通过返回定位结果接口将终端经纬度信息返回给企业IT系统。
●需求约束
•定位类型：
支持的定位方式包括精定位、粗定位。
对Gota终端，可采用Gota定位原理（需Gota业务网络相关网元支持）
•目标号码：
单次请求最多支持对10个号码进行定位。
•结果描述：
若定位成功，返回经纬度信息。
如定位失败，应返回相应的失败码。
失败码详见《中国电信定位调度产品-定制接口开发文档》（下同）。
●连续定位：
企业IT系统通过发起连续定位请求接口向定位调度平台发起对指定终端（或终端列表）进行连续定位的请求，定位调度平台进行鉴权通过以后，返回请求处理结果。
定位调度平台根据接口请求设置对指定终端定位的周期，并将定位结果，按照接口请求设置的数据上报频率，通过返回定位结果接口将终端经纬度信息返回给企业IT系统。
●需求约束
•定位类型：
支持的定位方式包括精定位、粗定位。
•目标号码：
单次请求最多支持对10个号码进行定位。
•定位间隔：
连续定位允许最低的间隔时间为5（分钟）。
•结果描述：
若定位成功，返回经纬度信息。
如定位失败，返回相应的失败码。
●取消连续定位：
企业IT系统通过取消连续定位接口向定位调度平台发起对指定终端（或终端列表）取消连续定位的请求，定位调度平台进行鉴权通过以后，根据接口请求取消对指定终端定位周期定位，并向企业IT系统返回接口处理结果。
●需求约束
•目标号码：
单次请求最多支持对10个号码进行取消定位操作
•结果描述：
如请求处理失败，返回相应的失败码。
●获取终端最近一次的位置信息：
企业IT系统通过获取最新位置请求接口向定位调度平台发起对指定终端（或终端列表）获取最新的经纬度信息的请求，定位调度平台进行鉴权通过以后，在数据库检索该终端的最后一次定位结果，通过返回定位结果接口将终端经纬度信息返回给企业IT系统。
●需求约束
•目标号码：
单次请求最多支持对50个号码请求返回最近一次位置信息
•返回经纬度格式：
参考章节“数据格式”
•结果描述：
如接口请求失败，返回相应的失败码。
●获取历史定位数据：
企业IT系统通过获取历史定位数据接口向定位调度平台发起对指定终端获取历史定位数据的请求，定位调度平台进行鉴权通过以后，在数据库中检索获取该终端的一个时间段内的定位数据，并将定位结果通过返回定位结果接口将终端经纬度信息返回给企业IT系统。
●需求约束
•目标号码：
单次请求最多支持对1个号码请求获取历史位置数据。
•返回经纬度格式：
参考章节“数据格式”。
•结果描述：
如获取位置数据失败，返回相应的失败码。
5.2.2.短信接口
包括发送短信、获取短信列表、接收短信回执等短信能力接口，用户通过该系列接口可以向授权的移动终端发送短信、获取指定时间段内指定终端号码的短信内容、以及接收来自移动终端发往企业IT系统的短信等。
●发送短信：
企业IT系统通过发送短信接口向定位调度平台发起对指定的终端（或终端列表）发送短信的请求，定位调度平台进行鉴权通过以后，将短信内容单发（或群发）给指定的移动终端，并向企业IT系统返回请求处理结果。
●需求约束
•目标号码：
单次请求最多支持对10个号码发送短信。
目标号码只能是该客户BizID下对应的手机号码。
•长短信支持：
支持发送可拼接的长短信
•发送号码：
通过接口发送的短信以定位调度平台的短信接入码作为发送号码
•结果描述：
如发送短信失败，返回相应的失败码
●获取指定号码的短信列表：
企业IT系统通过获取短信列表接口向定位调度平台发起获取企业IT系统已发送过的短信列表和内容请求，定位调度平台进行鉴权通过以后，根据接口请求的号码和时间段，在数据库中检索该号码的短信列表和内容，返回请求处理结果。
●需求约束
•目标号码：
单次请求最多支持对1个号码获取短信列表。
•结果描述：
如获取列表失败，返回相应的失败码。
●返回接收到的短信：
定位调度平台收到来自终端的短信后，将短信信息包括发信人信息、短信内容等通过反调接口发送给企业IT系统。
企业IT系统将接口处理结果返回给定位调度平台。
●需求约束
•目标号码：
单次请求支持返回1个号码的发送内容
•结果描述：
如返回失败，判断失败原因
5.2.3.终端管理接口
包括终端号码激活/去激活、获取终端列表、终端变更通知等接口，用户通过该系列接口可以进行移动终端进行激活（终端必须经过激活才允许被定位）、去激活、获取终端列表信息。
定位调度平台侧的某单位帐号管辖的终端号码如果发生变更（增加、删减、修改），可通过终端变更接口通知企业IT系统。
●终端激活：
企业IT系统在对指定终端进行定位前，需要对终端进行激活操作。
通过终端号码激活/去激活请求接口向定位调度平台提交对指定终端（或列表）进行激活处理的请求，定位调度平台进行鉴权通过以后，返回将接口请求处理结果。
定位调度平台根据接口请求，对指定终端（或列表）进行激活处理完成后，通过终端号码激活回复接口向企业IT系统发送激活/去激活处理结果。
●需求约束
•目标号码：
单次请求最大支持对10个号码进行激活处理
•结果描述：
如激活处理失败，返回失败码
●终端去激活：
企业IT系统如果要解除对终端号码的定位权限，可以通过终端号码激活/去激活请求接口完成指定终端（或列表）的去激活操作。
处理流程参考上述“终端激活”流程。
●需求约束
•目标号码：
单次请求最大支持对10个号码进行去激活处理
•结果描述：
如去激活处理失败，返回失败码
●获取终端列表信息：
企业IT系统/通过获取终端列表接口向定位调度平台提交获取企业IT系统目前所受理的所有终端号码的信息，定位调度平台进行鉴权通过后，在数据库检索出属于该企业IT系统的号码列表，返回给企业IT系统。
●需求约束
•应答结果：
单次应答最多返回50个终端号码的信息，超过50个终端号码，将以分页的形式返回给请求方
•结果描述：
如请求处理失败，返回失败码
●终端变更通知：
企业IT系统在使用定位调度定制版产品过程中，可随时通过业务变更在CRM/领航平台上增加（或删减、或修改）其账号下所管理的终端号码。
业务变更受理完成后，CRM/领航平台将变更信息同步给定位调度平台，定位调度平台通过终端变更通知接口，将变更信息发送给企业IT系统。
●需求约束
•号码约束：
单次请求最大支持50个终端号码的通知，超过50个终端号码，将分多次进行通知。
•结果描述：
如请求失败，返回失败原因。
5.2.4.告警接口
目前主要提供告警查询接口，用户通过该接口可以查询其所辖的移动终端发生的告警情况，进而对告警进行处理。
告警信息主要包括进围栏告警、出围栏告警、路径偏离告警等。
●告警查询：
企业IT系统通过告警查询接口向定位调度平台提交获取其管辖移动终端的告警情况，定位调度平台进行鉴权通过后，在数据库检索出属于该企业IT系统的告警情况，返回给企业IT系统。
●需求约束
•目标号码：
单次请求支持对10个号码进行查询。
•告警类型：
包括出围栏告警、进围栏告警、路径偏离告警等。
•结果描述：
如查询失败，返回失败原因。
●告警通知：
当企业管理的终端号码发生告警，如进出围栏告警、路径偏移告警等，定位调度平台通过告警推送接口向企业IT系统推动相关的告警消息。
该接口需要企业提供相应的反向调用接口。
●需求约束
•告警类型：
包括出围栏告警、进围栏告警、路径偏离告警等。
•结果描述：
如推动失败，返回失败原因。
6.接口安全管理
定位调度平台通过多重安全机制，保证企业IT系统接入使用定位调度平台开放接口的安全性，主要包括：
•URL（或IP）地址绑定：
定位调度平台只允许在登记注册的URL（或IP）访问平台接口。
•KEY密钥：
定位调度平台为每个接入使用接口的企业分配KEY，作为企业IT系统接入使用的密钥。
•提供基于SSL协议的HTTPS访问方式。
本接口规范定义了两种基础协议的开放接口，包括JavaScript和WebServices，针对这两种协议访问方式的安全管理流程，描述如下：
•JavaScript方式访问：
企业客户申请使用定位调度平台的GIS及地图接口时，需提供访问定位调度平台的接口服务器的URL。
定位调度平台允许一个企业IT系统同时登记多个URL。
如企业登记的URL为
•WebServices方式访问：
企业客户申请使用定位调度平台的定位及通信能力时，企业客户需提供访问定位调度平台的服务器IP地址。
定位调度平台允许一个企业IT系统同时登记多个IP。
企业IT系统只允许对企业所管辖的终端号码进行定位和发送短信。
企业IT系统在申购使用定位调度开放能力时，需要现在中国电信CRM系统进行业务受理，把拟进行管理（定位/发送短信）的终端号码在中国电信CRM录入。
企业IT系统可以通过号码变更，对其所管辖的终端号码进行增加、删除。
6.1.KEY生成规则
系统根据客户申购接口能力时登记的URL/IP，自动生成KEY。
KEY是定位调度平台为每个企业IT系统生成的唯一的32个字节长度字符串，KEY是企业IT系统调用定位调度平台接口时的鉴权参数之一。
6.2.接口鉴权流程
●预置条件
•客户使用定位调度平台的开放接口前，需先在定位调度平台登记客户平台的URL/IP
•客户已获得定位调度平台根据“KEY生成规则”为企业（或SI）生成的32字节KEY
●鉴权流程
1、企业IT系统发起接口请求，需携带的请求信息包括一个URL（或IP）、KEY信息；
2、定位调度平台获取发起请求的URL、KEY信息；
3、查询提交请求的URL/IP是否已在定位调度平台登记。
如已登记，比较该URL/IP请求携带的KEY是否与平台分配的KEY信息一致，如正确，则鉴权通过；不正确，则鉴权失败；
4.1、鉴权通过：
返回请求处理结果
4.2、鉴权失败：
返回失败原因（错误代码：
KEY不存在；KEY与URL/IP不匹配）
7.接口使用流程
GIS和地图能力接口主要通过JavaScript代码方式调用，部分功能（如地理编码、反向地理编码、位置搜索接口、地图图片生成等）同时提供WebServices接口，定位及通信能力接口基于SOAP协议的WebServices方式调用。
7.1.企业客户使用流程
企业客户使用定位调度能力接口的流程如下图所示：
图企业客户使用定位调度平台接口流程图
1、企业客户在使用定位调度平台的开放接口时，需先通过各级CRM受理相关产品，设置企业的账号信息。
2、各级CRM为企业客户生成BizID，录入用户信息、终端号码
3、各级CRM将客户订购信息通过各省领航平台同步给集团领航平台，包括BizID、企业账号信息、订购业务类型（此处为“定制版”）、企业IT系统的URL/IP地址、终端号码等
4、集团领航平台，处理客户订购信息，并向定位调度平台派发施工单。
领航平台将企业的BizID和企业账号等企业信息传递给定位调度平台。
企业账号和BizID都是企业客户在领航平台的唯一标识
5、定位调度平台为企业生成KEY，并建立KEY和企业账号、BizID、URL/IP等企业相关信息的映射关系。
向领航平台返回竣工信息
6、定位调度平台将生成的KEY交付给企业客户
7、企业IT系统在访问接口时，根据本规范定义的访问方式，构建有效的URL地址，向定位调度平台提交接口请求
8、定位调度平台对请求进行鉴权（鉴权流程请
升级会员 