接口规范
JOYZL SCADA Server 同时提供了 TCP 接口和 HTTP 接口， TCP 接口基于 ODBS 二进制格式提供长连接支持，供桌面客户端登软件使用，默认端口为 1230； HTTP 接口基于 JSON 字符串格式，供 WEB 端使用，例如数据看板和手机端，默认端口为 80； TCP 和 HTTP 接口名称和数据结构定义完全相同；但受限于 HTTP 协议的限制， 少部分 TCP 接口功能 HTTP 无法支持。
首先应明确 JOYZL SCADA Server 的服务 IP 地址，例如192.168.8.2。 TCP 接口接点为192.168.8.2:1230，通过 TCP Socket 连接。 HTTP 地址为 http://192.168.8.2/actions/UserLogin ， 其中 ”actions” 为接口路径， ”UserLogin” 为接口名称。
注意：由于 JavaBean 规范和对象序列化的原因请求参数和实体 JSON 对象的属性名首字母为大写。
提示
同域部署时 HTTP 客户端接口的主机部分应省略，仅需要路径部分。
既 http://192.168.8.2/actions/UserLogin 应为 /actions/UserLogin
权限
每个接口都会根据其功能制定权限，接口权限为以下所列：
- ANY: 任意执行，无须登录无须授权；
- LOGON: 登录执行，登录用户可执行；
- AUTHORIZED: 授权执行，授权用户可执行；
- FORBIDDEN: 禁止访问，任何用户不可访问。
命名
[Name][Action]
如以下接口名称所示，其中 "Device" 为实体对象名称， "Amount"、"Create"、"Delete"、"Select"、"Single"、"Update"、 "Unique"、Move"、Change"、"Read"、"Write" 为执行动作，所有接口命名方式和动作单词所表示的含义完全相同。
- DeviceAmount：根据参数获取数量，可缺省所有参数，登录可用；
- DeviceSelect：根据条件获取多个对象，可缺省所有参数，登录可用；
- DeviceSingle：根据标识获取单个对象，必须指定必要参数，登录可用；
- DeviceUnique：校验参数是否唯一可用，必须指定必要参数，登录可用；
- DeviceCreate：新建新的实体对象，必须指定必要参数，授权可用；
- DeviceDelete：删除已有的实体对象，必须指定必要参数，授权可用；
- DeviceUpdate：修改更新实体对象普通参数，必须指定必要参数，授权可用；
- DeviceChange：修改更新实体对象关键参数，必须指定必要参数，授权可用；
- DeviceMove：更改实体对象关联，必须指定必要参数，授权可用；
- DeviceRead：修改更新实体对象，必须指定必要参数，登录可用；
以上仅列举常见接口动名词，无论如何根据业务情形始终会有例外的特殊接口。 通常情况下读取或查询数据类接口为无须特殊授权，仅登录即可使用（可能受数据范围限制）； 更改数据类接口均需要授权才能使用，否则将被拒绝。而系统类基础接口则无须登录也可正常请求， 例如获取系统枚举定义值的接口。
请求与响应
接口中涉及的所有字符串编码采用UTF-8。
TCP Socket
采用 ODBS 解析 TCP Socket 字节流时应保证服务端与客户端的实体对象和接口定义完全相同， 链路连接之后应首先发送 Signature 请求验证客户端与服务端的实体和接口定义是否一致； 如果不一致应提醒用户更新客户端或者获取与服务端定义完全相同的实体包。 链路空闲时，应维持链路状态，客户端应在3分钟之内至少发送一次 Beat 请求已检测链路有效性。 如果链路中断客户端可尝试重连，链路重新建立之后应立即发送检 Signature 验证实体和接口定义签名。 注意：在签名核对不一致的情况下，继续执行接口请求将导致解析异常和数据错乱。
接口请求与响应：
所有定义的 actions 接口均可由客户端主动发起请求， 客户端可同时发起的请求数量最多为64个接口， 超出此并发数量将导致异常； 如果客户端没有指定接口的访问权限将收到拒绝响应， 如果接口出现错误将返回错误代码或错误信息， 可通过 Action.getStatus() 或 "Status" 字段获得状态代码， Action.getError() 或 "Error" 字段获得错误文本（如果有）， 错误代码的定义请参考 返回状态及代码。
广播接收：
当服务端的业务实体被某用户更改（新建、修改、移动、删除）时，其它已登录的客户端将收到广播， 客户端应妥善接收并处理这些更改。服务端将根据登录用户的权限和数据范围决定那些用户收到广播。 广播机制仅用于业务实体对象发生变化的基础操作，这些操作的使用频率较低， 例如更改用户信息或者新建一个新区域。
状态轮询：
客户端可通过轮询方式获取变化频率较快的数据，这些接口均有特殊说明， 并且其中定义的参数和返回的数据都是相对精简的；出于对服务器性能和客户端并发限制的考虑， 这些接口应采用串行方式排队执行，既：上一个请求响应之后再请求下一个。
参数返回：
请求参数会随响应原样返回，但也会有例外情况进行特殊说明。 这些参数在接口文档描述返回结果的示例中被省略，不会加以重复描述。
HTTP JSON
请求方法：
POST（actions接口均采用POST方法，其它接口特殊说明）。
必须的请求头信息：
Content-Type: application/json; charset=UTF-8
Authorization: Basic 1vrcsuv1g5q
建议的请求头信息：
Connection: keep-alive
Accept-Encoding: gzip, deflate
请求参数：
基于 JSON 格式的请求参数，如果无任何参数可省略； JSON 字符串通过 HTTP Content 负载传递至服务端。 JSON 键名默认采用大驼峰（PascalCase）格式， 以与 JavaScript 的小驼峰格式进行区分。
请求参数示例：
{
"State": 1,
"LeaveLife": 10
}
其中的 State 和 LeaveLife 均为接口定义的参数， 如果请求时参数为默认值或无值（null），可省略。
响应结果：
响应内容以 JSON 格式返回，通过 HTTP Content 传递至客户端， HTTP Status 200 表示请求成功，其它状态均表示失败， 在失败状态下如果有可返回的 JSON 服务端也会将其传递到客户端。
响应结果示例：
{
"Error": 2,
"Token": "1vrcsuv1g5q",
"User": {
"Birthday": "2001-01-23",
"Created": "2021-08-09 11:04:07",
"Email": "931661600@qq.com",
"Employees": 1,
"Enable": true,
"Gender": true,
"Id": 6922598791422833,
"Updated": "2023-03-14 13:06:37"
},
"Username": "13883062895"
}
其中 Error 为请求状态，2表示成功，0表示未执行，其它值均表示特定错误； 错误代码的定义请参考错误代码章节。其余参数均有具体接口定义； 用户的请求参数通常情况下会随同接口一起返回，特定说明的接口不会原样返回用户参数。
注意： 接口和实体对象执行 JSON 序列化时，将忽略值为 null 的字段和值， 既：不会编码输出 key: null 这样形态的JSON键值对。 这是 ODBSJson 提供的特性，以减少无意义的空值输出。
枚举在 JSON 中的特殊处理：
当服务端响应的对象中包含有枚举时，将输出为 JSON 对象； 当执行 HTTP 请求时可仅指定枚举值。
枚举输出时示例：
{
Enum: {
"value": 1,
"name": "USING",
"text": "在用"
}
}
枚举请求时示例：
{
Enum: 1
}