JOYZL SCADA Server

地址

首先应明确 JOYZL SCADA Server 服务的 IP 地址，例如 192.168.8.2 。

TCP 接点为 192.168.8.2:1230，默认端口 1230。

HTTP 地址为 http://192.168.8.2/actions/UserLogin 其中 "actions" 为接口类型，"UserLogin" 为接口名称，默认端口 80。

权限

每个接口都会根据其功能设定所需角色，角色可设定为以下所列：

• NONE: 接口无须任何角色，例如登录接口；
• SERVO: 边缘端角色，专为伺服端提供，特定接口可用；
• SYATEM: 系统角色，用于系统间连接，具有可读权限，特定数据可修改；
• EMPLOYEE: 员工角色，用于操作人员，可执行特定操作。
• ADMINISTRATOR：管理员权限，可执行配置。

登录

TCP 客户端和 Web 端具有完全相同的登录过程: 请求 UserLogin 接口即可， 用户的编号(Number)、手机(Mobile)、邮件(Email)均可作为用户登录名。

TCP 客户端由服务器持有令牌并标记会话，直至连接中断，令牌将自动失效； Web 端应保持令牌并在每次请求中通过 HTTP Authorization 头信息携带令牌。 如果令牌在 1 个小时内无任何活动，服务端将迫使令牌强制失效，必须重新登录获取令牌。

TCP 登录示例 (Java Client API)

// 打开连接
Client.open("192.168.8.2", 1230);
// 创建接口实例
final UserLogin login = new UserLogin() {
	@Override
	protected void success(User entity) {
		// 成功
	}

	@Override
	protected void failure() {
		// 失败
		System.out.println(errorText());
	}
};
// 设置接口参数并调用
login.setUsername("登录用户名");
login.setPassword("登录密码");
login.invoke();

接口请求成功将返回 User 对象实例； 如遇请求失败，可通过 Action.getStatus() 获取状态码，Action.getError() 获取错误文本， Action.errorText() 方法将综合 Status 和 Error 信息提供错误文本。 所有接口对象均继承于 Action 对象，接口请求全部采用异步模式返回结果， 因此 Action.invoke() 会立即返回，不会阻塞当前线程。

WEB 登录示例 (JavaScript)

// 构建请求参数
let login = {
	Username: "登录用户名",
	Password: "登录密码"
}
// 发送请求
post(http://192.168.8.2/actions/UserLogin, login);

登录成功服务端将通过 Authorization 头发回令牌； 在后续的 HTTP 请求中必须包含 Authorization 请求头和收到的令牌； 令牌(token)是由服务端随机生成，具有唯一性的无意义字符串，令牌头格式如下所示。

Authorization: [token]
Authorization: 1vrcsuv1g5q

请求与响应

接口 URL 路径和名称区分大小写；接口中涉及的所有字符串编码采用 UTF-8。

Client TCP Socket

采用 ODBS 解析 TCP Socket 字节流时应保证服务端与客户端的实体对象和接口定义完全相同， 链路连接之后应首先发送 Signature 请求验证客户端与服务端的实体和接口定义是否一致； 如果不一致应提醒用户更新客户端或者获取与服务端定义完全相同的实体包。

链路空闲时，应维持链路状态，客户端应在3分钟之内至少发送一次 Beat 请求已检测链路有效性。 如果链路中断客户端可尝试重连，链路重新建立之后应立即发送检 Signature 验证实体和接口定义签名。

提示： 在签名核对不一致的情况下，继续执行接口请求将导致解析异常和数据错误。 如果您使用 JOYZL SCADA Client JDK，它将自动完成以上过程。

并发数量

所有定义的 Action 接口均可由客户端主动发起请求， 客户端可同时发起的请求数量最多为64个接口，超出此并发数量将导致异常； 如果客户端没有特定接口的访问权限将被拒绝，如果接口出现错误将返回错误代码和错误信息， 可通过 Action.getStatus() 获得错误代码，Action.getError() 获得错误文本， 更多状态代码请参考状态码定义。

广播接收

当服务端的业务实体被某用户更改（新建、修改、移动、删除）时，其它已登录的客户端将收到广播， 客户端应妥善接收并处理这些更改。服务端将根据登录用户的权限和数据范围决定那些用户收到广播。

广播机制仅用于业务实体对象发生变化的基础操作，这些操作的使用频率较低， 例如更改用户信息或者创建一个新区域。 JOYZL SCADA Client JDK 将自动处理接收到的广播， 涉及的实体和数据位于本地缓存中。

状态轮询

客户端可通过轮询方式获取变化频率较快的数据，这些接口均有特殊说明， 并且其中定义的参数和返回的数据都是相对精简的；出于对服务器性能和客户端并发限制的考虑， 这些接口应采用串行方式排队执行，既：上一个请求响应之后再请求下一个。

WEB HTTP

请求方法

POST（actions 接口默认采用 POST 方法，采用其它请求方法的接口特殊说明）。

请求头信息

必须指定以下两个请求头信息。

Content-Type: application/json; charset=UTF-8
Authorization: 1vrcsuv1g5q

请求参数

基于 JSON 格式的请求参数，如果无任何参数可省略； JSON 字符串通过 HTTP Content 负载传递至服务端。 JSON 键名默认采用大驼峰（PascalCase）格式， 以与 JavaScript 的小驼峰格式进行区分。

请求参数示例

// UserLogin 请求参数
{
	Password: "登录用户名",
	Username: "登录密码"
}

其中的 Password 和 Username 均为接口定义的参数， 如果请求时参数为默认值或无值(Null)， 可省略字段（示例的登录接口两个字段均为必须指定）。

响应结果

响应内容以 JSON 格式返回，通过 HTTP Content 传递至客户端， HTTP Status 200 表示请求成功，其它状态均表示失败， 在失败状态下如果有可返回的 JSON 服务端也会将其传递到客户端。

响应结果示例

// UserLogin 成功响应
{
	"Company": {
		"Address": "重庆市",
		"Alias": "我的组织",
		"Created": "2025-08-24 17:31:58",
		"Id": 8086122311712769,
		"License": "0987654321234567890",
		"Name": "我的组织",
		"Phone": "13883062895",
		"Updated": "2025-08-24 17:32:49"
	},
	"User": {
		"Created": "2025-08-24 17:16:53",
		"Email": "xc@joyzl.com",
		"Enable": true,
		"Id": 4087715192635394,
		"Mobile": "13883062895",
		"Name": "小陈",
		"Number": "10001",
		"Password": "13883062895",
		"Role": {
			"value": 9,
			"name": "ADMINISTRATOR",
			"text": "管理员"
		},
		"Updated": "2025-08-24 17:16:58",
		"ZoneId": 0
	},
	"Status": 2
}

其中 Status 为请求状态，2表示成功，0表示未执行，其它值均表示特定错误， 更多关于错误代码含义的请参考状态码定义。 其余参数均由具体接口定义； 用户请求的参数默认情况下会随同接口一起返回， 特定接口不会原样返回全部或部分请求参数。

注意： 接口和实体对象执行 JSON 序列化时，将忽略值为 null 的字段和值， 既：不会编码输出 key: null 形态的 JSON 键值对。 这是 ODBSJson 提供的特性，以减少无意义的空值输出。

枚举在 JSON 中的特殊处理

当服务端响应的对象中包含有枚举类型时， 将输出为 JSON 对象；当执行 HTTP 请求时可仅指定枚举值。

枚举响应时示例

{
	"Enum": {
		"value": 1,
		"name": "USING",
		"text": "在用"
	}
}

请注意： 枚举对象中的 value、name 和 text 由序列化模块构建， 因此字段名为全小写。

枚举请求时示例

{
	"Enum": 1
}

状态码定义

命名约定

[Name][Action]

如以下接口名称所示，其中以 "Equipment" 为业务对象名称， "Amount"、 "Select"、 "State"、 "Query"、 "Create"、 "Update"、 "Enable"、 "Move"、 "Delete" 为执行动作， 所有接口命名方式和动作单词所表示的功能完全相同。

• EquipmentAmount：获取业务对象数量，可缺省所有参数；
• EquipmentSelect： 获取多个业务对象，可缺省所有参数；
• EquipmentState： 获取业务对象状态，必须指定必要参数；
• EquipmentQuery： 获取单个业务对象，必须指定必要参数；
• EquipmentCreate： 创建新的业务对象，必须指定必要参数；
• EquipmentUpdate： 修改更新业务对象，必须指定必要参数；
• EquipmentEnable： 启用或禁用业务对象，必须指定必要参数；
• EquipmentMove： 移动业务对象区域，必须指定必要参数；
• EquipmentDelete： 删除已有的业务对象，必须指定必要参数；

所有的修改接口(XxxxxxxxUpdate)，均只能修改对象本身的常规字段，例如“编号”、“名称”等； 不能修改关联性和状态性字段，例如所属区域(ZoneId)或启用禁用状态(Enable)字段， 这些关系或状态的调整有专门的接口对应。

提示： 以上仅列举常见接口动名词，具体业务情形可能会有例外的特殊情况， 业务模块将根据实际需求定义并实现所需的接口。

参数约定

接口文档以 JSON 格式示例请求参数， 每个请求参数会标以 “必要”、“单选”、“可选” 单词， 用以描述参数是否必须设置值。

• 必要：必须指定的参数；
• 单选：至少选择其一的参数；
• 可选：可缺省的参数。