安徽电信服务总线接口规范安徽电信有限公司2014年02月版本记录第1章概述 (4)1.1概述 (4)1.2目标 (4)1.3规范使用对象及说明 (4)1.4名词解释 (4)第2章服务设计原则 (5)2.1接口协议统一原则 (5)2.2数据格式统一原则 (6)2.3服务定义唯一性原则 (6)2.4服务无状态原则 (6)2.5服务部署原则 (6)2.6服务组合原则 (6)2.7报文内容处理的原则 (7)2.8出入参设计原则 (7)2.9规则校验的原则 (8)2.10数据量原则 (8)2.11同步调用原则 (8)2.12统一入口原则 (8)2.13持久化原则 (8)第3章服务接入规范 (9)3.1调用方式 (9)3.2参数说明 (10)3.2.1 系统级参数 (10)3.3返回业务功能 (12)第4章安全控制 (12)4.1访问鉴权 (12)4.2传输加密 (13)第5章异常分类编码 (13)第6章服务注册、注销、变更、调用流程 (15)6.1服务注册的流程 (15)6.2服务注册的内容 (15)6.3测试环境服务注册的流程 (16)第7章服务治理 (16)7.1目标 (16)7.2检查方法 (17)7.3服务监控的指标 (18)7.4服务目录树 (19)第1章概述1.1概述本规范明确了安徽电信服务总线接入及服务使用的标准和规范，为服务使用方和服务提供方提供开发参考。

1.2目标本规范为了指导各业务系统与服务总线平台的对接，实现以下目标：1)当服务总线接入业务系统服务时，为该服务提供方提供开发依据。

2)当服务使用方调用服务总线提供的服务时，为该服务使用方提供开发依据。

3)为服务使用过程中安全及控制提供标准和参考。

1.3规范使用对象及说明本规范适用于所有新建或改造的服务接口，均需要遵守本规范约定。

1.4名词解释1)服务提供方：提供原始服务，并将服务发布到服务总线的内部业务系统、第三方企业或个人。

2)服务使用方：使用服务总线上的服务进行应用开发的内部应用系统、第三方企业或个人。

3)服务商：平台为统一管理服务的提供方和使用方，综合其统称为服务商。

4)服务：服务是执行可重复任务的可发现资源，由外部化的服务规范进行描述。

服务可分为技术服务和业务服务两种。

第2章服务设计原则由于各个系统和平台之间存在差异性，为确保安徽电信服务总线的稳定高效，服务设计原则如下：2.1接口协议统一原则所有服务的接口均基于Http协议。

服务提供方和服务使用方必须同时使用同一种类型的技术来进行开发和调用，调用的服务通过HTTP URL中特定属性进行标识，具体见接口协议。

2.2数据格式统一原则服务的接口数据包含业务所有的业务数据，数据采用JSON 格式表示，并且符合相应的JSON Schema。

服务提供方和服务消费方必须同时使用同一种格式进行数据交互。

2.3服务定义唯一性原则一个服务应该只实现一个业务功能，业务功能的区别通过服务编码来区分，不应通过定义不同的业务数据在同一个服务编码下实现不同的业务功能。

2.4服务无状态原则服务应是无状态的，两次请求之间无须状态和会话的保持，并可以采用轮询的方式在负载均衡器上进行注册2.5服务部署原则服务应是全局的，不应区分本地网、大区等，但可以部署多份用以提供不同优先级的服务。

2.6服务组合原则服务按照服务粒度设计成原子服务和组合服务。

原子服务为最细粒度的服务，组合服务由原子服务组合而成。

为有效提高组合服务的效率，跨系统的组合服务由服务总线调用不同的原子服务实现组合，系统内的组合服务由服务提供方在应用内部进行组合。

2.7报文内容处理的原则服务请求和返回的的报文应符合JSON Schema格式。

服务请求方和提供方应采用通用的JSON解析器来构造和解析数据，JSON不同含义的段落应定义明确含义的字段名称，相同内容的数据应采用数组来进行描述，双方可根据JSON 名称和路径进行精确定位，不应根据字段的顺序来获取字段值，字段值不受字段顺序调整的影响。

报文统一采用UTF-8进行编码。

2.8出入参设计原则为提高查询类服务的通用性和性能，查询类服务在入参中定义返回字段列表，服务提供方根据入参中指定的字段返回信息。

查询内接口应在入参中定义分页参数，返回参数中应包含当前页数、总页数或是已到最后一页等信息。

返回参数中如返回静态编码值时应同时返回此编码值对应的名称。

2.9规则校验的原则服务提供方应对请求报文格式和关键信息进行合规性和业务校验，防止非法访问和入侵。

2.10数据量原则服务总线所传递的单条消息大小原则上不大于1M，否则应建议采用文件传输、接口表传输、直连等连接方式。

2.11同步调用原则服务调用方和服务提供方采用同步调用的方式进行请求，如需要使用异步调用可采用消息队列或服务调用方定义异步通知接口来实现。

2.12统一入口原则服务总线对外提供统一的调用地址。

2.13持久化原则服务使用方在使用服务的过程中，由服务总线进行整个过程的日志记录，并对调用的详细信息进行持久化，便于对账和稽核。

建议服务调用方和提供方对调用的关键信息（如流水号，源地址等）进行持久化。

第3章服务接入规范对于服务调用的访问方式，平台采用标准的HTTP调用方式。

3.1调用方式接口服务通过 http://ip:port/oip/rest 访问平台服务。

IP和PORT根据实际生产环境情况对外公布。

其中/oip/rest 保持不变。

实例：基于REST的服务请求以使用“查询BSS用户短信详单”服务为例，该服务的具体信息如下：服务名称：查询BSS用户短信详单；服务编码：SelectSmsInfo；开发技术：采用HTTP协议技术；请求方式：采用GET/POST都可以调用方信息不变。

根据上面这些信息，得出服务访问地址为：GET方式：http://220.102.110.34:7080/oip/rest?send=crm&servCode=1001. OPEN_3RD.Sync&msgId=crm_20130718_10001&busiURl=/Sel ectSmsInf/1末位的“1”是模拟业务参数。

POST方式：http://220.102.110.34:7080/oip/rest send=crm&servCode=1001.OPEN_3 RD.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsIn f/1业务参数的内容放在http的请求体中传输3.2参数说明3.2.1系统级参数以下参数是由服务总线定义的。

表格 3-1 系统级参数transactionId：交易流水号。

服务请求需经过多个系统或多个系统模块，为了有效标志出一次业务请求经过的所有调用，服务调用方在请求时生成一唯一的流水号，服务总线在多次调用过程中将会保持此交易流水号一致，服务提供方也应记录此交易流水号。

所有消息日志应统一记录到统一日志平台以供事后分析。

R1-R3：动态路由参数，为了保持路由的灵活性，调用方可动态添加最多3个路由参数，如版本号，本地网等参数，服务总线根据此参数路由到特定的服务提供方节点上，以满足试点，灰度发布等场景。

3.3返回业务功能返回参数分为两部分，一部分为HTTP协议部分，包含了请求的状态，异常代码和异常信息，200表示本次请求完成，500表示服务总线调用服务提供方出现异常等；一部分为业务数据，业务数据采用JSON格式，JSON格式需符合JSON Schema的校验规则，业务异常也在此部分定义。

服务总线后台分析系统将会对请求和返回的报文进行事后分析。

第4章安全控制4.1访问鉴权服务总线对外提供统一安全控制策略。

所有访问能力开放平台的服务时，都必须经过平台的鉴权，鉴权通过后方允许访问，否则将给与拦截。

能力开放的访问鉴权提供如下几种策略：服务商鉴权：凡是使用能力开放平台的服务使用方必须是已注册的服务商下的一个客户端。

该部分由使用方进行申请，平台完成注册，同时为服务使用方分配可使用服务的权限。

IP地址鉴权：应用集成平台支持服务使用方的IP地址身份认证模式。

对于不在服务使用方申请的IP地址范围内产生的服务调用，平台给予拦截和告警。

对于通过多重路由或映射导致不能获得实际IP地址时，将采用鉴权码方式替代。

摘要式认证：采用标准的HTTP摘要认证方式进行访问认证，具体介绍见参考文档OAuth2.0: 对于严格权限限制的场景，通过OAuth2.0协议进行认证和授权，授权由应用系统统一提供。

4.2传输加密对于安全非常高的场合，建议全流程采用HTTPS协议进行加密传输，如缴费等场景。

第5章异常分类编码在使用平台服务的过程中，平台对不同的异常进行分类，供开发者和使用方在调测及使用过程中参考。

如果遇到上述类似异常代码或信息，可以和平台维护人员联系帮助解决。

第6章服务注册、注销、变更、调用流程6.1服务注册的流程服务注册和变更：由服务提供方在ITSM发起申请，经服务评审后，由ITSM调用服务总线提供的能力进行注册和变更。

服务注销：由服务提供方或服务总线管理方根据实际需求和服务的调用次数等评估后发起，经服务提供方、服务总线管理部门和服务调用方会审后在ITSM中发起下线流程。

服务调用：由服务调用方发起，经服务提供方确认和服务评审后在服务总线上进行注册。

服务评审由服务总线管理部门牵头组织。

6.2服务注册的内容6.3测试环境服务注册的流程测试环境服务注册由ITSM发起，在完成表单填写后自动在服务总线上进行处理。

第7章服务治理7.1目标1、所有域的服务按照协议规范全部接入服务总线，避免出现服务未在服务总线直接使用。

2、注册在服务总线上的服务必须符合服务总线的规范，包括接口协议，数据格式，不得私自更改协议或超过注册的内容升级接口内容7.2检查方法1、按照所有服务全部由服务总线调用或者由F5负载均衡器调用的基本原则，服务管理团队会定期对主机和F5上服务的调用方IP进行审核，如果出现服务端口出现非服务总线或非F5主机的调用，或者F5主机上服务端口非服务总线的调用，则认为出现了异常的服务调用，由服务提供方提供服务调用日志或版本变化情况进行详细的解释。

2、服务接口参数应符合接口规范，服务总线将定期对服务调用异常、失败、异常代码等进行统计，给出服务接口的符合度。

3、服务返回的业务数据应符合注册时提供的JSONSchema，不符合的则认为是注册信息不全或异常升级。

服务总线将定期从服务调用报文中进行格式校验，对不符合格式的消息请求反馈服务提供方并要求进行说明。

7.3服务监控的指标7.4服务目录树服务总线上注册的服务按照服务目录树进行组织，新增的服务需按照服务的类别进行归类。

服务目录由服务总线统一维护和发布，服务使用方和调用方均可以访问服务总线平台获取服务的详细信息。