设备维护平台接口技术规范说明书[20130513]...doc

设备维护平台设备维护平台 接口技术规范说明书接口技术规范说明书 版本号 V1 0 杭州天梦科技有限公司杭州天梦科技有限公司 二二 一一 年五月年五月 更改履历 版本版本 号号 修改编修改编 号号 更改时间更改时间 更改的更改的 图表和章节图表和章节 更改简要描述更改简要描述更改人更改人批准人批准人 V1 02013 05 13创建 形成初稿叶庆国 V1 12014 06 09维修业务操作接口调整 仅开放维保单位相关操作 接口 叶庆国 注 更改人除形成初稿 以后每次修改在未批准确认前均需采用修订的方式 进行修改 设备维护平台接口技术规范说明书 I 目 录 1概述概述 2 1 1 编写目的 2 1 2 预期读者 2 1 3 参考文献 2 2接口平台设计接口平台设计 2 2 1 技术架构 2 2 1 1 接口架构图 2 2 1 2 业务流图 3 2 2 部署方式 4 2 3 接口标准 4 2 3 1 技术标准 4 2 3 2 数据规约 5 2 3 3 示例 6 3WEBSERVICE 服务服务 7 3 1 设备维护平台提供的服务 7 3 1 1 接口服务清单 7 3 1 2 接口服务设计 8 设备维护平台接口技术规范说明书 2 1概述 1 1 编写目的 为设备维护平台的信息同步和共享 制定了统一的接口规范 用来指导各系 统的接口设计 开发 联调及迁移工作 范围 本文档主要是对设备维护平台与外围业务系统的数据交互需求进行说 明 1 2 调试要求 强烈要求第三方调用者 先做测试库的接口调试 确保接口及参数调用正确 否则将对正式库可能出现的系统故障承担主要责任 1 3 预期读者 项目组人员 各交互系统涉及到的开发厂家 1 4 参考文献 智能交通设备维护管理系统设备接入标准 杭州天梦科技有限公司 2接口平台设计 2 1 技术架构 2 1 1接口架构图 暂缺 设备维护平台接口技术规范说明书 3 2 1 2业务流图 说明 用户通过接口 设备维护平台接口技术规范说明书 4 2 2 部署方式 接口服务层包括 Webservice 服务 展现集成服务 1 Webservice 服务 各系统提供的接口服务统一部署在设备维护平台接口服务层上 各系统客户 端和接口服务层用 SOAP 协议通过 HTTP 来交互 客户端根据 WSDL 描述文档生 成 SOAP 请求消息发送到服务端 服务端解析收到的 SOAP 请求 调用 Web service 然后再生成相应的 SOAP 应答送回到客户端 2 展现集成服务 展现集成服务主要是应用界面集成服务 由服务提供方提供详细的 URL 及 相关参数说明 调用方传入参数 调用服务方提供的页面进行展现 3 平台 Service 组件服务 平台 Service 组件服务统一部署在设备维护平台接口服务层上 通过平台接 口服务层进行查询操作 2 3 接口标准 2 3 1技术标准 2 3 1 1 简述 客户端和服务器用 SOAP 协议通过 HTTP 来交互 客户端根据 WSDL 描述文 档生成 SOAP 请求消息发送到服务端 服务端解析收到的 SOAP 请求 调用 Web service 然后再生成相应的 SOAP 应答送回到客户端 2 3 1 2 认证机制 设备维护平台提供的所有 WebService 服务均需要认证授权才能被调用 Webservice 服务接收到请求后从传入参数中获取用户名和密码 进行认证 认证 通过后再调用具体服务 设备维护平台接口技术规范说明书 5 2 3 2数据规约 2 3 2 1 简述 客户端和服务端采用 XML 格式的字符串来交互业务数据 客户端将业务数 据组织成 XML 格式的字符串作为最后一个入参调用服务端接口 服务端解析 XML 格式的字符串得到业务数据处理业务并把结果组织成 XML 格式的字符串返 回给客户端 接口调用的结果 自动序列化后 以 XML 格式的字符串返回 其中包含了 接口调用中出现的错误描述 2 3 2 2 格式约定 若是业务接口调用 将以 DataItem Rsp 类实例序列化 表示单一数据项 内容包括操作结果 错误描述 无数据集 若是查询接口调用 将以 EntSetSerialize Rsp 类实例序列化 表示查询 结果 其中包括错误描述 有数据集 XML 字符串中 若是节点取值为null 则是 在节点中存在属性 xsi nil true 若是节点取值为空字符串 则是 XML 编码格式为 UTF 8 字段为日期的遵循以下约定 1 年月日格式统一为 YYYY MM DD 如 2006 06 22 2 年月格式为 YYYYMM 如 200606 3 包含时间的日期格式统一为 YYYY MM DDTHH MI SS 如 2006 06 22T14 00 00 4 如果未约定日期格式 则 DATE 类型的默认为 YYYY MM DD 如 2006 06 22 2 3 2 3 格式 DTD 暂缺 设备维护平台接口技术规范说明书 6 2 3 3示例 2 3 3 1 示例 查询接口 包含数据集 0 0 操作成功 3 3 10 0 1 true e4fb99cf 108b 4688 b124 43ae8a2b5787 可控的故障维修 900308010 ead3b6fb 0c5e 482c 892d d629f57b75ef 900501010 900308010 10 1 可控的故障维修 2011 09 26T17 20 17 true 195a341c 35dc 43ab a2fc b050be12ea0c 不可控的故障维修 900308020 ead3b6fb 0c5e 482c 892d d629f57b75ef 900501010 900308020 20 1 不可控的故障维修 2011 09 26T17 20 32 187 设备维护平台接口技术规范说明书 7 true c648d4d3 9a7e 4f3f 8a2f 96f94cb9d978 频繁上下线 900308030 ead3b6fb 0c5e 482c 892d d629f57b75ef 900501010 900308030 22 1 频繁上下线 2011 11 24T23 28 17 953 2 3 3 2 示例 业务接口 只有返回标识 0 0 0 0 授权帐号验证失败授权帐号验证失败 System BooleanSystem Boolean FalseFalse 3Webservice 服务 3 1 设备维护平台提供的服务 由于各用户单独安装部署 故对于 WebService 服务地址 另外单独提供 3 1 1接口服务清单 序 号 服务名称接口名称说明调用方频率 1ClientUserCheck客户端信息验证第三方实时 2BaseData DevList基础数据 设备清单查询第三方实时 3BaseData OrgList基础数据 组织机构及设备分组 清单查询 第三方实时 设备维护平台接口技术规范说明书 8 4BaseData DictionaryList基础数据 数据字典代码项查询第三方实时 5DevRep FaultSearch业务流程 故障上报查询第三方半小时 6DevRep FaultReport故障上报第三方半小时 7DevRep RepairSearch业务流程 报修查询第三方半小时 8DevRep RepFeeApp维修报价申请第三方半小时 9DevRep FaultRsp维修响应第三方半小时 10DevRep FaultFeedback维修反馈第三方半小时 11DevRep RepairAudit维修审核第三方半小时 12 3 1 2接口服务设计 3 1 2 1 客户端信息验证 服务名称ClientUserCheck 接口声明public DataItem Rsp ClientUserCheck string clientUser string clientPwd string clientIp 描述客户端信息验证 中文名字段名长度类型非空说明及数据要求 登录帐号clientUserstringY 登录密码clientPwdstringY 用户 IPclientIpstringY 入参 IsError 0 有错误 1 无错误 ItemType 数据项类型 ItemValue数据项取值 出参 ErrorDesc错误描述 部署情况设备维护平台 3 1 2 2 基础数据 设备清单查询 服务名称BaseData DevList 接口声明public EntSetSerialize Rsp BaseData DevList string 设备维护平台接口技术规范说明书 9 devType string devIp string devGuid string devCodeSdk string devChannel string unitRepGuid Int32 pageIndex string clientUser string clientPwd string clientIp 描述基础数据 设备清单查询 中文名字段名长度类型非空说明及数据要求 设备类型devTypestringN 设备 IPdevIpstringN 设备 GUIDdevGuidstring N 设备接口编号 devCodeSdkstring N 来自第三方设备平台 设备通道号devChannelstring N 维保单位 GUID unitRepGuidstring N作为维保方 其登录帐 号所属单位 GUID 可作 为维保单位 GUID 页索引pageIndexInt32Y 登录帐号clientUserstringY 登录密码clientPwdstringY 入参 用户 IPclientIpstringY IsError 0 有错误 1 无错误 ErrorDesc错误描述 TotalCount数据查询结果的总记录数 RspCount实际返回的记录数 RspPageSize分页查询的页大小 RspPageIndex分页查询的页索引 RspPageTotal分页查询的页总数 出参 EntList 数据查询结果列表 采用泛 型集合 List 自动序 列化产生 根据查询接口 不同 其中嵌套的对象及 其字段名称也不同 以实 际返回结果为准 部署情况设备维护平台 3 1 2 3 基础数据 组织机构及设备分组查询 服务名称BaseData OrgList 接口声明public EntSetSerialize Rsp BaseData OrgList Int32 设备维护平台接口技术规范说明书 10 pageIndex string clientUser string clientPwd string clientIp 描述基础数据 组织机构及设备分组清单查询 中文名字段名长度类型非空说明及数据要求 页索引pageIndexInt32Y 登录帐号clientUserstringY 登录密码clientPwdstringY 用户 IPclientIpstringY IsError 0 有错误 1 无错误 ErrorDesc错误描述 TotalCount数据查询结果的总记录数 RspCount实际返回的记录数 RspPageSize分页查询的页大小 RspPageIndex分页查询的页索引 RspPageTotal分页查询的页总数 出参 EntList 数据查询结果列表 采用泛 型集合 List 自动序 列化产生 根据查询接口 不同 其中嵌套的对象及 其字段名称也不同 以实 际返回结果为准 部署情况设备维护平台 3 1 2 4 基础数据 数据项查询 服务名称BaseData DictionaryList 接口声明public EntSetSerialize Rsp BaseData DictionaryList Int32 pageIndex string nodeCategory string nodeType string clientUser string clientPwd string clientIp 描述基础数据 数据字典代码项查询 中文名字段名长度类型非空说明及数据要求 页索引pageIndexInt32Y 节点大类nodeCategorystringY 故障原因大类 900501010 故障原因细类 900501020 节点细类nodeTypestringN 登录帐号clientUserstringY 登录密码clientPwdstringY 设备维护平台接口技术规范说明书 11 用户 IPclientIpstringY IsError 0 有错误 1 无错误 ErrorDesc错误描述 TotalCount数据查询结果的总记录数 RspCount实际返回的记录数 RspPageSize分页查询的页大小 RspPageIndex分页查询的页索引 RspPageTotal分页查询的页总数 出参 EntList 数据查询结果列表 采用泛 型集合 List 自动序 列化产生 根据查询接口 不同 其中嵌套的对象及 其字段名称也不同 以实 际返回结果为准 部署情况设备维护平台 3 1 2 5 业务流程 故障上报查询 服务名称DevRep FaultSearch 接口声明public EntSetSerialize Rsp DevRep FaultSearch string reportUnitGuid string faultAuditStatus string devType string faultType string faultTimeStart string faultTimeEnd string repStatus string jobNo string deviceGuid int pageIndex string clientUser string clientPwd string clientIp 描述业务流程 故障上报查询 中文名字段名长度类型非空说明及数据要求 上报单位 GUID reportUnitGuidstringN 作为维保方 其登录帐 号所属单位 GUID 可作 为上报单位 GUID 故障审核状态faultAuditStatusstringN 设备类型devTypestring N 故障类型faultTypestring N 开始时间faultTimeStartstring N 故障时间 结束时间faultTimeEndstring N 故障时间 维修状态repStatusstring N 入参 工单号jobNostring N 设备维护平台接口技术规范说明书 12 设备 GUIDdeviceGuidstring N 页索引pageIndexInt32Y 登录帐号clientUserstringY 登录密码clientPwdstringY 用户 IPclientIpstringY IsError 0 有错误 1 无错误 ErrorDesc错误描述 TotalCount数据查询结果的总记录数 RspCount实际返回的记录数 RspPageSize分页查询的页大小 RspPageIndex分页查询的页索引 RspPageTotal分页查询的页总数 出参 EntList 数据查询结果列表 采用泛 型集合 List 自动序 列化产生 根据查询接口 不同 其中嵌套的对象及 其字段名称也不同 以实 际返回结果为准 部署情况设备维护平台 3 1 2 6 业务流程 故障上报 服务名称DevRep FaultReport 接口声明public DataItem Rsp DevRep FaultReport string deviceGuid string fault Time string fault Type string fault Remark string clientUser string clientPwd string clientIp 描述故障上报 中文名字段名长度类型非空说明及数据要求 设备 GUIDdeviceGuidstring Y 故障时间fault Timestring Y 故障类型fault Typestring Y故障类型编号 可在数 据项中查询 参考参数 如下 节点大类 900501005 节点细类 900504050 故障描述fault Remarkstring Y 设备维护平台接口技术规范说明书 13 登录帐号clientUserstringY 登录密码clientPwdstringY 用户 IPclientIpstringY IsError 0 有错误 1 无错误 ItemType 数据项类型 ItemValue数据项取值 出参 ErrorDesc错误描述 部署情况设备维护平台 3 1 2 7 业务流程 报修查询 服务名称DevRep RepairSearch 接口声明public EntSetSerialize Rsp DevRep RepairSearch string reportUnitGuid string repTransferStatus string devType string faultType string faultTimeStart string faultTimeEnd string repStatus string jobNo string deviceGuid int pageIndex string clientUser string clientPwd string clientIp 描述业务流程 报修查询 中文名字段名长度类型非空说明及数据要求 上报单位 GUID reportUnitGuidstringN 作为维保方 其登录帐 号所属单位 GUID 可作 为上报单位 GUID 维修移交状态repTransferStatusstringN 设备类型devTypestring N 故障类型faultTypestring N 开始时间faultTimeStartstring N 故障时间 结束时间faultTimeEndstring N 故障时间 维修状态repStatusstring N 工单号jobNostring N 设备 GUIDdeviceGuidstring N 入参 页索引pageIndexInt32Y 设备维护平台接口技术规范说明书 14 登录帐号clientUserstringY 登录密码clientPwdstringY 用户 IPclientIpstringY IsError 0 有错误 1 无错误 ErrorDesc错误描述 TotalCount数据查询结果的总记录数 RspCount实际返回的记录数 RspPageSize分页查询的页大小 RspPageIndex分页查询的页索引 RspPageTotal分页查询的页总数 出参 EntList 数据查询结果列表 采用泛 型集合 List 自动序 列化产生 根据查询接口 不同 其中嵌套的对象及 其字段名称也不同 以实 际返回结果为准 部署情况设备维护平台 3 1 2 8 业务流程 维修报价申请 服务名称DevRep RepFeeApp 接口声明public DataItem Rsp DevRep RepFeeApp string fault Repair Unit Guid string repFeeMemo decimal repFee string clientUser string clientPwd string clientIp 描述维修报价申请 中文名字段名长度类型非空说明及数据要求 维修记录 GUID fault Repair Unit G uid string Y 申请描述repFeeMemostring Y 申请费用repFeedecimal Y 登录帐号clientUserstringY 登录密码clientPwdstringY 用户 IPclientIpstringY IsError 0 有错误 1 无错误 ItemType 数据项类型 出参 ItemValue数据项取值 设备维护平台接口技术规范说明书 15 ErrorDesc错误描述 部署情况设备维护平台 3 1 2 9 业务流程 维修响应 服务名称DevRep FaultRsp 接口声明public DataItem Rsp DevRep FaultRsp string fault Repair Unit Guid string fault Reason Memo string clientUser string clientPwd string clientIp 描述维修响应 中文名字段名长度类型非空说明及数据要求 维修记录 GUID fault Repair Unit G uid string Y 维修响应说明fault Reason Memostring Y 登录帐号clientUserstringY 登录密码clientPwdstringY 用户 IPclientIpstringY IsError 0 有错误 1 无错误 ItemType 数据项类型 ItemValue数据项取值 出参 ErrorDesc错误描述 部署情况设备维护平台 3 1 2 10 业务流程 维修反馈 服务名称DevRep FaultFeedback 接口声明public DataItem Rsp DevRep FaultFeedback string fault Repair Unit Guid string feedback Memo int repairMinute DelayAppaly string fault Reason Category string fault Reason Type string clientUser string clientPwd