广东联通物联网B2B联合运营服务平台设计规则

广东联通物联网B2B联合运营服务平台设计规则概述说明

本文档是对物联网联合运营平台（以下简称运营平台）的设计规则、机制、原因进行详细说明，通过该文档让合作伙伴及第三方接入方进一步了解本平台。虽运营平台仍有未完善之处，但在开发初期已结合旧平台的优缺点及遇到的实际问题进行重构及设计升级。因数据来源来自集团底层平台，运营平台涉及多方同步及接口开放，因此，设计原则以高稳定、高并发为主，合作伙伴接入时可能会因个别设计难以理解。本文档尽量描述清楚，如有不足之处望指出纠正。

设备生命周期

为保证设备的准确性及稳健性，运营平台建立了设备的生命周期，包括何时开卡、实名、激活、设立套餐、状态变更、设备变更、停用等等。

设备生命周期由系统自动维护及人工维护组成，通常情况下由用户操作及设备触发自动完成，用户操作指在系统界面完成，设备触发由数据同步及自动化完成。极端情况下，当系统或同步出现异常时由人工（维护人员及开发人员）介入，生命周期的每次变更出现异常时系统均会捕捉异常信息，维护人员及开发人员可在维护工作台中查看。由于涉及多方同步，平台设计5次的重试机制，每次间隔时间逐级递增。所有重试失败才会由开发人员介入。通过该方式保障设备生命周期不受系统因素、外部环境丢失。
生命周期目前仍不完善，后续会考虑将该接口开放。

接口设计规则

openApi分两种，一种是实时返回数据，另一种是采用回调的方式将结果返回给客户端。什么时候用哪种接口？

实时返回数据Api

原则上，所有实时返回数据的Api均不是设备的实时数据，而是存在运营平台中最近一次同步的数据，数据可能会有延迟。一般用于需要向用户马上展示数据的场景。如设备列表、用量列表。设备何时会同步?下两章节中的《同步机制》有解释。

设备实时Api（回调方式）

个别场景需要获取设备的实时数据或者需要实时更改设备的状态，由于集团底层平台才是数据来源，如果通过直接请求的方式整个请求时间将非常长，集团底层平台本身有做限流并发，数据量大时无法保证返回的是有效数据（异常情况）。运营平台未来可能会有亿级数据，直连方式平台本身也无法保证并发量及稳定性。因此，一般需要实时的API均采用回调方式。运营平台优先处理API请求，次处理设备同步。所有回调的接口均是设备的实时数据。

队列

每个客户帐号均有队列，不建议频繁的调用运营平台的API，平台本身会做限流降速，调用的越频繁就越慢。具体可查看限流降速章节。

容错

平台设计5次的重试机制，每次间隔时间逐级递增。最后同步失败后由人工介入。

升级

未来大部分接口可能有两套，一套是实时返回数据Api，另一套是设备实时API（回调方式），不符合该规则的API将废弃。

回调推送机制

签名

回调及推送都带签名sign，接入方可根据文档及pushKey解密签名，验证推送来源，保障安全性。

重试补偿
回调及推送近期均会加入重试及补偿机制，该机制是为应对网络异常、接收方系统升级等情况。同样有5次重试，间隔时间逐级递增，从几分钟到几个小时。如果均未成功，系统将自动发送邮件到接收方指定邮箱，接收方可在平台中手动重发。通过该机制保证数据不丢失。

同步机制

同步权重

每个设备的同步周期都是动态的，平台加入了权重算法，同步周期受剩余用量、用量大小、总量大小、到期时间、上一次同步时间等等因素影响。每个设备的权重值均不一样，权重越大同步越频繁。原理是优先给更需要更新数据的设备同步。例如大流量同步周期会比小流量更频繁，快到期的设备比刚使用的设备同步周期更频繁。

容错机制

为保证同步的每一次同步均成功，同样有5次重试机会，间隔时间逐级递增。所有重试失败才会由开发人员介入。

自动化规则

自动化是根据业务需求根据同步信息自动处理业务数据，更新设备状态。
后续为减轻平台压力及合作伙伴能及时接收设备更新信息，未来平台会增加自动化推送比例，客户端可根据自身业务需求设置自动化规则，由主动变被动，不需要每次都主动请求。

限流降速

限流

为保障平台的稳定性，平台拥有限流机制，根据每个同步帐号的做限流，虽前期数据量不大暂未开启，未来会根据数据量动态限流，请不要在代码中设定过于频繁的请求。否则开启后需要更新代码。

降速

因平台处理的数据量较大，因此会有队列机制。主动调用的接口权重会比算法权重更大，如果接入方额外的频繁请求，该帐号下的设备同步周期将整体降速，无法保障更需要同步的设备。
并不是说最好不要调用接口，平台讲究的是平衡、稳健，如果确实需要，调用平台的接口是没有问题的，在这里只是建议适当请求，平台本身做了容错机制。不需要在短时间内没推送结果就不断的调用。

容错机制

涉及到同步及开放接口，平台均会加入容错机制，不建议客户端再做容错机制。如果实在要做，请根据以上规则进行容错设计。

虽目前容错机制仍有不完善的地方，我司将尽快完善。如有不足之处亦欢迎各合作伙伴提出指正。