服务总线接口规范

安徽电信效劳总线接口标准安徽电信2014年02月版本记录版本号时间记录人变更原因变更描述V0.12014-1-5李超初始V0.22014-2-22李超修订增加接口参数描述第1章概述51.1概述51.2目标51.3标准使用对象及说明51.4名词解释6第2章效劳设计原那么62.1接口协议统一原那么62.2数据格式统一原那么72.3效劳定义唯一性原那么72.4效劳无状态原那么72.5效劳部署原那么82.6效劳组合原那么82.7报文内容处理的原那么82.8出入参设计原那么92.9规那么校验的原那么92.10数据量原那么92.11同步调用原那么102.12统一入口原那么102.13持久化原那么10第3章效劳接入标准103.1调用方式113.2参数说明12系统级参数123.3返回业务功能14第4章平安控制144.1访问鉴权154.2传输加密16第5章异常分类编码16第6章效劳注册、注销、变更、调用流程176.1效劳注册的流程176.2效劳注册的内容186.3测试环境效劳注册的流程19第7章效劳治理197.1目标197.2检查方法207.3效劳监控的指标217.4效劳目录树22概述概述本标准明确了安徽电信效劳总线接入及效劳使用的标准和标准，为效劳使用方和效劳提供方提供开发参考。目标本标准为了指导各业务系统与效劳总线平台的对接，实现以下目标：当效劳总线接入业务系统效劳时，为该效劳提供方提供开发依据。当效劳使用方调用效劳总线提供的效劳时，为该效劳使用方提供开发依据。为效劳使用过程中平安及控制提供标准和参考。标准使用对象及说明本标准适用于所有新建或改造的效劳接口，均需要遵守本标准约定。名词解释效劳提供方：提供原始效劳，并将效劳发布到效劳总线的内部业务系统、第三方企业或个人。效劳使用方：使用效劳总线上的效劳进行应用开发的内部应用系统、第三方企业或个人。效劳商：平台为统一管理效劳的提供方和使用方，综合其统称为效劳商。效劳：效劳是执行可重复任务的可发现资源，由外部化的效劳标准进行描述。效劳可分为技术效劳和业务效劳两种。效劳设计原那么由于各个系统和平台之间存在差异性，为确保安徽电信效劳总线的稳定高效，效劳设计原那么如下：接口协议统一原那么所有效劳的接口均基于协议。效劳提供方和效劳使用方必须同时使用同一种类型的技术来进行开发和调用，调用的效劳通过URL中特定属性进行标识，具体见接口协议。数据格式统一原那么效劳的接口数据包含业务所有的业务数据，数据采用JSON格式表示，并且符合相应的JSONSchema。效劳提供方和效劳消费方必须同时使用同一种格式进行数据交互。效劳定义唯一性原那么一个效劳应该只实现一个业务功能，业务功能的区别通过效劳编码来区分，不应通过定义不同的业务数据在同一个效劳编码下实现不同的业务功能。效劳无状态原那么效劳应是无状态的，两次请求之间无须状态和会话的保持，并可以采用轮询的方式在负载均衡器上进行注册效劳部署原那么效劳应是全局的，不应区分本地网、大区等，但可以部署多份用以提供不同优先级的效劳。效劳组合原那么效劳按照效劳粒度设计成原子效劳和组合效劳。原子效劳为最细粒度的效劳，组合效劳由原子效劳组合而成。为有效提高组合效劳的效率，跨系统的组合效劳由效劳总线调用不同的原子效劳实现组合，系统内的组合效劳由效劳提供方在应用内部进行组合。报文内容处理的原那么效劳请求和返回的的报文应符合JSONSchema格式。效劳请求方和提供方应采用通用的JSON解析器来构造和解析数据，JSON不同含义的段落应定义明确含义的字段名称，相同内容的数据应采用数组来进行描述，双方可根据JSON名称和路径进行精确定位，不应根据字段的顺序来获取字段值，字段值不受字段顺序调整的影响。报文统一采用UTF-8进行编码。出入参设计原那么为提高查询类效劳的通用性和性能，查询类效劳在入参中定义返回字段列表，效劳提供方根据入参中指定的字段返回信息。查询内接口应在入参中定义分页参数，返回参数中应包含当前页数、总页数或是已到最后一页等信息。返回参数中如返回静态编码值时应同时返回此编码值对应的名称。规那么校验的原那么效劳提供方应对请求报文格式和关键信息进行合规性和业务校验，防止非法访问和入侵。数据量原那么效劳总线所传递的单条消息大小原那么上不大于1M，否那么应建议采用文件传输、接口表传输、直连等连接方式。同步调用原那么效劳调用方和效劳提供方采用同步调用的方式进行请求，如需要使用异步调用可采用消息队列或效劳调用方定义异步通知接口来实现。统一入口原那么效劳总线对外提供统一的调用地址。持久化原那么效劳使用方在使用效劳的过程中，由效劳总线进行整个过程的日志记录，并对调用的详细信息进行持久化，便于对账和稽核。建议效劳调用方和提供方对调用的关键信息〔如流水号，源地址等〕进行持久化。效劳接入标准对于效劳调用的访问方式，平台采用标准的调用方式。调用方式接口效劳通过://ip:port/oip/rest访问平台效劳。IP和PORT根据实际生产环境情况对外公布。其中/oip/rest保持不变。实例：基于REST的效劳请求以使用“查询BSS用户短信详单”效劳为例，该效劳的具体信息如下：效劳名称：查询BSS用户短信详单；效劳编码：SelectSmsInfo；开发技术：采用协议技术；请求方式：采用GET/POST都可以调用方信息不变。根据上面这些信息，得出效劳访问地址为：GET方式：://4:7080/oip/rest?send=crm&servCode=1001.OPEN_3RD.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsInf/1末位的“1”是模拟业务参数。POST方式：://4:7080/oip/rest?send=crm&servCode=1001.OPEN_3RD.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsInf/1业务参数的内容放在的请求体中传输参数说明系统级参数以下参数是由效劳总线定义的。表格31系统级参数参数名类型是否必需描述Sendstring是客户端所属系统编码，填写请参考3.1节〔系统标志全部采用此编码〕servCodestring是客户端需要访问的效劳编码，由效劳总线在注册后统一提供msgIdstring是由调用方系统按照OIP规那么生成的唯一标识一次调用的字符串，长度小于64位。生成规那么：系统名_当前时间戳_流水号busiUrlstring是消费方传递的业务局部地址App_keyString否效劳总线分配的应用标志transactionIdString是交易流水号，由调用方生成，屡次请求均会包含此信息。格式建议为系统名_当前时间戳_流水号R1String否动态路由参数1R2String否动态路由参数2R3String否动态路由参数3transactionId：交易流水号。效劳请求需经过多个系统或多个系统模块，为了有效标志出一次业务请求经过的所有调用，效劳调用方在请求时生成一唯一的流水号，效劳总线在屡次调用过程中将会保持此交易流水号一致，效劳提供方也应记录此交易流水号。所有消息日志应统一记录到统一日志平台以供事后分析。R1-R3：动态路由参数，为了保持路由的灵活性，调用方可动态添加最多3个路由参数，如版本号，本地网等参数，效劳总线根据此参数路由到特定的效劳提供方节点上，以满足试点，灰度发布等场景。返回业务功能返回参数分为两局部，一局部为协议局部，包含了请求的状态，异常代码和异常信息，200表示本次请求完成，500表示效劳总线调用效劳提供方出现异常等；一局部为业务数据，业务数据采用JSON格式，JSON格式需符合JSONSchema的校验规那么，业务异常也在此局部定义。效劳总线后台分析系统将会对请求和返回的报文进行事后分析。平安控制访问鉴权效劳总线对外提供统一平安控制策略。所有访问能力开放平台的效劳时，都必须经过平台的鉴权，鉴权通过前方允许访问，否那么将给与拦截。能力开放的访问鉴权提供如下几种策略：效劳商鉴权：但凡使用能力开放平台的效劳使用方必须是已注册的效劳商下的一个客户端。该局部由使用方进行申请，平台完成注册，同时为效劳使用方分配可使用效劳的权限。IP地址鉴权：应用集成平台支持效劳使用方的IP地址身份认证模式。对于不在效劳使用方申请的IP地址范围内产生的效劳调用，平台给予拦截和告警。对于通过多重路由或映射导致不能获得实际IP地址时，将采用鉴权码方式替代。摘要式认证：采用标准的摘要认证方式进行访问认证，具体介绍见参考文档OAuth2.0:对于严格权限限制的场景，通过OAuth2.0协议进行认证和授权，授权由应用系统统一提供。传输加密对于平安非常高的场合，建议全流程采用S协议进行加密传输，如缴费等场景。异常分类编码在使用平台效劳的过程中，平台对不同的异常进行分类，供开发者和使用方在调测及使用过程中参考。种类编码描述正常0成功接口请求方异常2消息格式异常，例如必填参数未填、消息编码异常等3无效的路由属性10接口请求超过指定流量9接口请求包大小超过限制6权限异常〔例如无权访问此效劳〕101重复请求102无效的业务域或业务大类、小类199接口请求方其他异常接口响应方异常8接口响应方超时201接口响应超过指定流量202接口响应包大小超过限制298接口响应方内部异常299接口响应方其他异常平台异常4调用的效劳未发布5调用的效劳已注销7调用的效劳已关闭11调用的效劳不存在1效劳调用失败398平台内部异常399平台其他异常其他异常999其他异常测试异常601测试接口未实现业务定义异常>1000如果遇到上述类似异常代码或信息，可以和平台维护人员联系帮助解决。效劳注册、注销、变更、调用流程效劳注册的流程效劳注册和变更：由效劳提供方在ITSM发起申请，经效劳评审后，由ITSM调用效劳总线提供的能力进行注册和变更。效劳注销：由效劳提供方或效劳总线管理方根据实际需求和效劳的调用次数等评估后发起，经效劳提供方、效劳总线管理部门和效劳调用方会审后在ITSM中发起下线流程。效劳调用：由效劳调用方发起，经效劳提供方确认和效劳评审后在效劳总线上进行注册。效劳评审由效劳总线管理部门牵头组织。效劳注册的内容名称说明接口名称接口编码接口简要描述请求报文样例返回报文样例请求报文格式定义返回报文格式定义接口业务异常列表和描述版本号对应的效劳节点注册效劳地址探测报文〔可选〕是否进行探测〔时间，频度〕备用效劳地址〔在连续失败或拨测失败等情况下自动或手工切换效劳地址〕测试环境效劳注册的流程测试环境效劳注册由ITSM发起，在完成表单填写后自动在效劳总线上进行处理。效劳治理目标所有域的效劳按照协议标准全部接入效劳总线，防止出现效劳未在效劳总线直接使用。注册在效劳总线上的效劳必须符合效劳总线的标准，包括接口协议，数据格式，不得私自更改协议或超过注册的内容升级接口内容检查方法按照所有效劳全部由效劳总线调用或者由F5负载均衡器调用的根本原那么，效劳管理团队会定期对主机和F5上效劳的调用方IP进行审核，如果出现效劳端口出现非效劳总线或非F5主机的调用，或者F5主机上效劳端口非效劳总线的调用，那么认为出现了异常的效劳调用，由效劳提供方提供效劳调用日志或版本变化情况进行详细的解释。效劳接口参数应符合接口标准，效劳总线将定期对效劳调用异常、失败、异常代码等进行统计，给出效劳接口的符合度。效劳返回的业务数据应符合注册时提供的JSONSchema，不符合的那么认为是注册信息不全或异常升级。效劳总线将定期从效劳调用报文中进行格式校验，对不符合格式的消息请求反应效劳提供方并要求进行说明。效劳监控的指标指标类型运行类调用次数平均调用时长1秒以内调用次数1-5秒以内调用次数5秒以上调用次数调用成功次数调用失败次数调用超时次数非法调用个数常规类效劳注册个数效劳变更个数效劳注销个数标准类异常效劳接口个数接口