一个完整的接口技术解决方案(电信

一个完整的接口技术解决方案(电信内容摘要：

数的方式。 报文中数值的单位使用国标的单位，比如货币使用“元”，长度使用“米”等。 无 国标的单位以约定为准。  报文中的日期信息，转换成 YYYYMMDD HHmmss 文本格式（ 24 小时制）。 如果是空日期，则转换成空文本。  报文中的 true 和 false 数据类型，转换成 0(表示 false)、 1（表示 true）  报文中的二进制数据，转换成 Base64字符方式发送。  报文中的记录集，放在 Records标签中；报文中一条记录，放在 Records标签中。  报文中如果存在多条记录，则在 Records标签中就包含 多个的 Record标签。 如果报文中仅有一条记录，则 Records标签中只包含一个 Record标签 .如果没有记录，则仅仅包含一个 Records标签 ,没有 Record标签。  如果返回结果数据集非常多，在性能考虑和数据量冲突的情况下，可以使用分页返回数据集的方式分批返回数据（每次返回最多 100 条记录）。 服务端提供分批结果返回的功能。 至于如何使用分页查询的功能，参见下面的 XML 框架说明。 施工系统向外协系统发送请求 施工系统向外协系统发送请求的数据目前有几点需要考虑 ：  如何请求查询一个业务数据  如何新增一条记录，新增之后如何点到记录的键值  如何修改一条记录  如何删除一条记录  文档如何上传  一条记录中一个 FileID 的字段如何上传多个文件  如何在一条记录中补充上传文档  如何在一条记录中删除一个文档  如何获得文档的基本信息  如何获得文档的所有兄弟信息  如何获得文档的所有父亲信息  如何 下载一个文档 针对这些问题，接口方案的解决方法如下： 请求查询一个业务数据 施工系统针对外协系统发送的业务数据查询请求根据业务类型有很多种。 为了简化接口，而不是在接口上进行业务操作，所以，外协系统将施工系统发起的数据查询请求看作是数据下载的一种方式，而不为了复杂的业务查询请求提供复杂的条件解析。 外协系统提供的数据查询接口是从数据下载和数据延期性来考虑的。 为了满足数据的下载，外协系统提供了按照某一个表的主键来下载数据和按照记录的变更时间范围来下载数据的两种方式查询请求。 请求报文： ?xml version= encoding=utf8 ? XmlData UserInfo UserZhangSan/User PassWord123456/PassWord /UserInfo Description RowID0/RowID KeyValue123/KeyValue QueryBeginTime20202018 153000/QueryBeginTime QueryEndTime20202019 153000/QueryEndTime /Description /XmlData 响应报文： ?xml version= encoding=utf8? XmlData Description RowID100/RowID /Description Records Record Field1Value1/Field1 Field2Value2/Field2 Field3Value3/Field3 Field4Value4/Field4 /Record Record Field1Value1/Field1 Field2Value2/Field2 Field3Value3/Field3 Field4Value4/Field4 /Record Record Field1Value1/Field1 Field2Value2/Field2 Field3Value3/Field3 Field4Value4/Field4 /Record /Records /XmlData 报文说明： 标签名 说明 XmlData 报文数据主体 Description 报文头部信息 Records 记录集合 Record 一行记录 UserInfo 业务认证的用户信 息 User 业务用户登录名 PassWord 业务用户验证口令 RowID 第一次请求的时候，客户端 RowID 发送 0，表示从第 0 条记录开发返回。 服务端根据条件查询，发现结果超过 100 条记录，则在返回的结果中， RowID的值为 99，表示服务端当前的记录位置处在第 100条的位置上，后面还会有剩余的记录。 客户端检查返回的结果，如果发现 RowID 大于 0,则继续发送请求进行查询。 但是，客户端第二次发送请求继续查询的时候， RowID的值要赋值为第一次返回的值，即RowID=99。 服务端第二次收到请求 的时候，发现 RowID 是 99,则从第100条返回结果。 以此类推循环调用，直到服务端达到记录的末尾，这时候，服务端在返回的结果中 RowID= RowID=0，终止循环调用。 字典、用户信息、单位信息，因为返回的字段比较少，不受 100条记录返回的限制。 一次调用，就返回全部的结果。 KeyValue 查询时主键的值。 这个 KeyValue和下面的QueryBeginTimeQueryEndTime是互斥的。 如果在请求的时候提供了主键的值，表示客户端要求服务器按照主键的值查询一条记 录。 如果客户端提供了主键的值，则服务端将忽略QueryBeginTimeQueryEndTime中的值。 字典、用户信息、单位信息，因为没有查询时间范围，所以KeyValue即表示字典类型。 QueryBeginTime QueryEndTime 查询时时间段范围。 QueryBeginTime是起始时间，QueryEndTime是结束时间。 表示客户端要求服务端查询在这个时间范围之内所有变更过的记录（包括新增、修改、删除）。 在外协中，一条记录新增的时候，它的创建时间和最后修改时 间是一样的，以后修改记录的时候，创建时间不变，改变的仅仅是最后修改时间。 同时，外协系统中删除记录仅仅在“记录是否删除”字段中标记“ 1”，并不是真正的物理删除记录。 这里的时间指的是记录变更的时间，不是记录中的某个业务时间。 如果用户需要按照业务时间来查询数据，则施工系统把外协系统的数据获取到本地进行保存，在施工系统中提供按照业务时间查询的功能。 QueryBeginTimeQueryEndTime和 KeyValue是互斥的。 如果客户端需要按照时间范围来查询，则必须 KeyValue空。 Field1 Field2 Field3 Field4 一行记录中的英文字段名称。 实际中，这些标签都是字典的英文名。 字段的标签全部是大写。 具体的字段名称请参见提供的数据模型 新增一条记录，得到记录的键值 为了简化数据模型的处理，本方案不考虑主从表的并发处理情况。 如果存在主从表的数据需要上传，那么，在一个事务中，施工单位首先先上传主表的记录，从反馈信息中获得主表的主键值。 然后，把刚刚获得的主表的主键值赋值给从表的对应外键，再上传从表数据，得到从表的主键值。 如果不是主从表，而 是单表，则直接上传数据，从反馈信息中得到主键值。 这种情况的优点是：数据和表相关，施工单位可以灵活的控制表之间的关系；同时，数据包中的报文比较简单，容易解析；接口上面比较清晰，与业务的耦合比较低。 缺点是：一个业务涉及的主从表不能在同一个报文中（这个缺点可以通过施工系统灵活的控制表之间关系来解决）；一个业务中可能会使用到两个或两个以上的接口，造成业务完整性上面的分离（这种缺点可以通过把业务放在一个事务中来解决）； 键值的返回：在调用新增接口之后，外协会按照记录的 顺序 返回外外协中所生成的键值。 施工单位获得键 值之后，可以在本地表中更新记录的主键值。 请求报文： ?xml version= encoding=utf8? XmlData UserInfo UserZhangSan/User PassWord123456/PassWord /UserInfo Description Note开工报告 /Note /Description Records Record KeyField/KeyField NormalField1Value1/NormalField1 NormalField2Value2/NormalField2 NormalField3Value3/NormalField3 NormalField4Value4/NormalField4 /Record Record KeyField/KeyField NormalField1Value1/NormalField1 NormalField2Value2/NormalField2 NormalField3Value3/NormalField3 NormalField4Value4/NormalField4 /Record /Records /XmlData 响应报文： ?xml version= encoding=utf8? XmlData Description Result成功 /Result !如果失败，则 Result里面内容是：失败：（错误原因） /Description Records Record KeyFieldValue1/KeyField /Record Record KeyFieldValue2/KeyField /Record /Records /XmlData 报文说明： 标签名 说明 XmlData 报文数据主体 Description 报文头部信息 Records 记录集合 Record 一行记录 UserInfo 业务认证的用户信息 User 业务用户登录名 PassWord 业务用户验证口令 Note 业务的简单描述。 比如：开工报告、施工组织方案 等 请求中的 KeyField 一行记录中的主键字段。 在新增的时候，施工系统所给的主键字段内容为空。 外协系统中根据主键字段内容为空，认为这是一条新增的记录 响应中的 KeyField 一行记录中的主键字段。 外协系统返回的主键值。 这里的主键值和施工系统发送的记录的顺序是一一对应的。 Result 反馈报文中的保存成功与否信息。 如果保存成功，则信息是“成功” 如果保存失败，则信息是“失败：（后面是错 误的详细信息）” 修改一条记录 施工系统在修改了一条记录的时候，上传的报文中与新增的报文类似，只是主键的信息不能为空。 外协系统判断主键的信息，如果发现主键的信息不为空，则认为是修改了一条记录。 如果施工系统报文中主键不为空，而外协系统在数据库对应的表中又没有发现对应的记录，则自动转换成新增的方式来处理这条记录。 外协系统在反馈中，还是会把主键返回给施工系统。 但是，这种情况下，施工系统可能不再需要维护这个主键。 即使是仅仅修改了一个字段，施工单位还得需要上传全部的字段信 息（包含被修改的字段）给外协系统。 施工系统不是对记录做物理删除，而仅仅是作了逻辑删除，即仅仅在记录的删除标志位上面做了“ 1”的标志。 这种情况对记录来说，也是修改的范围。 只是需要在 Note业务的简单描述中说明“逻辑删除”。 即使是逻辑删除记录，施工系统也必须上传全部的字段到外协系统。 请求报文： ?xml version= encoding=utf8? XmlData UserInfo UserZhangSan/User PassWord123456/PassWord /UserInfo。