JOYZL SCADA Server

能源类接口

URL /actions/energy/*

PKG com.joyzl.scada.action.energy.*

**能源类接口**
模块	接口	用途	权限
Energy	EnergyAmount	获取抄表数量	SYATEM
Energy	EnergySelect	获取抄表记录	SYATEM
Energy	MeterAmount	获取表计数量	SYATEM
Energy	MeterSelect	获取多个表计	SYATEM
Energy	MeterQuery	获取单个表计	SYATEM
Energy	MeterState	获取表计状态	SYATEM
Energy	MeterUnique	校验表计编号	ADMINISTRATOR
Energy	MeterCreate	新建表计	ADMINISTRATOR
Energy	MeterUpdate	修改表计	ADMINISTRATOR
Energy	MeterChange	更换表计	ADMINISTRATOR
Energy	MeterEnable	启用或禁用表计	ADMINISTRATOR
Energy	MeterMove	移动表计	ADMINISTRATOR
Energy	MeterDelete	删除表计	ADMINISTRATOR
Energy	SignalSelect	获取遥测信号	SYATEM

能源类型(EnergyType)

UNKNOWN(0) 未知
WATER(1) 水 m³
ELECTRIC(2) 电 kW·h
GAS(3) 气 m³
HEAT(4) 暖 GJ

抄表

抄表接口用于获取表计服务每日自动抄读的抄表记录。表计必须配置通信参数才能自动生成并抄读每日能耗，表计服务将在每日深夜 23:00 执行抄读作业。服务端(JOYZL SCADA Server) 会持久存储能耗记录，通常会配置数据的有效时间，防止磁盘写满。

获取抄表数量(EnergyAmount)

URL /actions/device/EnergyAmount

PKG com.joyzl.scada.client.device.EnergyAmount

获取全部或指定区域的抄表记录数量，可见范围取决于用户所在的区域。缺省所有参数时，返回当前用户可见范围的所有最新抄表记录数量；指定区域标识(ZoneId)参数时，仅返回指定区域（含子区域）的抄表记录数量；指定表计标识(MeterId)或表计编号(MeterNumber)参数时，仅返回指定表计的抄表记录数量；指定开始(Begin)和结束(End)时间时将统计指定时间段的记录数量，如果未指定开始(Begin)和结束(End)时间则仅统计每个表计最新记录。

请求示例

{
	// 能源类型（必要）
	"Type":2,
	// 区域标识（可选）
	"ZoneId": 6892182778556009,
	// 表计标识（单选）
	"MeterId": 6892182769831190,
	// 表计编号（单选）
	"MeterNumber": "M0001",
	// 开始时间（可选）
	"Begin": "2022-12-13 00:00:00",
	// 结束时间（可选）
	"End": "2022-12-13 23:59:59"
}

响应示例

{
	"Type": {
		"name": "ELECTRIC",
		"value": 2,
		"text": "电",
		"unit": "kW·h"
	},
	"ZoneId": 6892182778556009,
	"MeterId ": 6892182769831190,
	"MeterNumber": "M0001",
	"Begin": "2022-12-13 00:00:00",
	"End": "2022-12-13 23:59:59",

	// 抄表记录数量
	"Energy": 892,
	// 总能耗
	"Total": 7654,
	// 响应状态码
	"Status": 2
}

获取抄表记录(EnergySelect)

URL /actions/device/EnergySelect

PKG com.joyzl.scada.client.device.EnergySelect

获取全部或指定区域的抄表记录，可见范围取决于用户所在的区域。缺省所有参数时，返回当前用户可见范围的所有最新抄表记录；指定区域标识(ZoneId)参数时，仅返回指定区域（含子区域）的抄表记录；指定表计标识(MeterId)或表计编号(MeterNumber)参数时，仅返回指定表计的抄表记录；指定开始(Begin)和结束(End)时间时将返回指定时间段的记录。

请求示例

{
	// 能源类型（必要）
	"Type":2,
	// 区域标识（可选）
	"ZoneId": 6892182778556009,
	// 表计标识（单选）
	"MeterId": 6892182769831190,
	// 表计编号（单选）
	"MeterNumber": "M0001",
	// 开始时间（可选）
	"Begin": "2022-12-13 00:00:00",
	// 结束时间（可选）
	"End": "2022-12-13 23:59:59"
}

响应示例

{
	"Type": {
		"name": "ELECTRIC",
		"value": 2,
		"text": "电",
		"unit": "kW·h"
	},
	"ZoneId": 6892182778556009,
	"MeterId": 6892182769831190,
	"MeterNumber": "M0001",
	"Begin": "2022-12-13 00:00:00",
	"End": "2022-12-13 23:59:59",

	// 记录集合
	"Energys": [
		{
			// 表计标识
			"MeterId": 6892182769831190,
			// 表显读数
			"Metering": 87654,
			// 增量
			"Increment": 89,
			// 累计
			"Accumulate": 386,
			// 创建时间
			"Created": "2022-12-13 23:59:59"
		}
		… 
	],
	// 响应状态码
	"Status": 2
}

表计

获取表计数量(MeterAmount)

URL /actions/device/MeterAmount

PKG com.joyzl.scada.client.device.MeterAmount

获取全部或指定区域的表计数量，可见范围取决于用户所在的区域。缺省所有参数时，返回当前用户可见范围的所有表计数量；指定区域标识(ZoneId)参数时，仅返回指定区域（含子区域）的表计数量；指定能源类型(Type)参数时，仅返回指定能源类型的表计数量。

请求示例

{
	// 区域标识（可选）
	"ZoneId": 6892141150584634,
	// 能源类型（可选）
	"Type": 2
}

响应示例

{
	"ZoneId": 3358725158993927,
	"Type": {
		"name": "ELECTRIC",
		"value": 2,
		"text": "电",
		"unit": "kW·h"
	},

	// 表计数量
	"Meter ": 142,
	// 启用数量
	"Enable ": 140,
	// 供应数量
	"Off": 108,
	// 中断数量
	"On ": 30,
	// 响应状态码
	"Status": 2
}

获取多个表计(MeterSelect)

URL /actions/device/MeterSelect

PKG com.joyzl.scada.client.device.MeterSelect

获取全部或指定区域的表计，可见范围取决于用户所在的区域。缺省所有参数时，返回当前用户可见范围的所有表计；指定区域标识(ZoneId)参数时，仅返回指定区域（不含子区域）的表计；指定能源类型(Type)参数时，仅返回指定能源类型的表计；指定启用或禁用(Enable)参数时，仅返回指定状态的表计。

请求示例

{
	// 区域标识（可选）
	"ZoneId": 6892141150584634,
	// 启用或禁用（可选）
	"Enable": true,
	// 能源类型（可选）
	"Type": 2
}

响应示例

{
	"ZoneId": 6892141150584634,
	"Enable": true,
	"Type": {
		"name": "ELECTRIC",
		"value": 2,
		"text": "电",
		"unit": "kW·h"
	},

	// 表计集合
	"Meters": [
		{
			// 表计标识
			"Id: 6892189876541566,
			// 区域标识
			"ZoneId": 4000605404135427,
			// 表计名称
			"Name": "2-5-6",
			// 能源类型
			"Type": {
					"value": 2,
					"name": "ELECTRIC",
					"text": "电",
					"unit": "kW·h"
			},
			// 表计编号
			"Number": "M0001",
			// 启用或禁用
			"Enable": true,
			// 备注
			"Remark": "电表",
			// 创建时间
			"Created": 2025-08-26 10:15:00",
			// 更新时间
			"Updated": 2025-08-26 11:15:00",
			
			// 设备标识
			"DeviceId": 821196270600196,
			// 计量属性标识
			"MeteringId": 821177815662595,
			// 余量属性标识
			"ResidualId": 0,
			// 充量属性标识
			"RechargeId": 0,
			// 通断属性标识
			"WorkingId": 0,
			
			// 表显读数
			"Metering": 123,
			// 供应状态
			"State": {
				"value": 1,
				"name": "ON",
				"text": "供应"
			},
			// 状态更新时间戳
			"Timestamp": 76543234567543
		}
		…
	],
	// 响应状态码
	"Status": 2
}

获取单个表计(MeterQuery)

URL /actions/device/MeterQuery

PKG com.joyzl.scada.client.device.MeterQuery

用于通过表计标识或编号获取单个表计。

请求示例

{
	// 表计标识（单选）
	"Id": 6892141164168701,
	// 表计编号（单选）
	"Number": "M0001"
}

响应示例

{
	"Id": 6892141164168701,
	"Number": "M0001",

	// 表计
	"Meter": {
		// 表计标识
		"Id: 6892189876541566,
		// 区域标识
		"ZoneId": 4000605404135427,
		// 表计名称
		"Name": "2-5-6",
		// 能源类型
		"Type": {
				"value": 2,
				"name": "ELECTRIC",
				"text": "电",
				"unit": "kW·h"
		},
		// 表计编号
		"Number": "M0001",
		// 启用或禁用
		"Enable": true,
		// 备注
		"Remark": "电表",
		// 创建时间
		"Created": 2025-08-26 10:15:00",
		// 更新时间
		"Updated": 2025-08-26 11:15:00",

		// 设备标识
		"DeviceId": 821196270600196,
		// 计量属性标识
		"MeteringId": 821177815662595,
		// 余量属性标识
		"ResidualId": 0,
		// 充量属性标识
		"RechargeId": 0,
		// 通断属性标识
		"WorkingId": 0,

		// 表显读数
		"Metering": 123,
		// 供应状态
		"State": {
			"value": 1,
			"name": "ON",
			"text": "供应"
		},
		// 状态更新时间戳
		"Timestamp": 76543234567543
	},
	// 响应状态码
	"Status": 2
}

获取表计状态(MeterState)

URL /actions/device/MeterState

PKG com.joyzl.scada.client.device.MeterState

获取指定表计的最新状态。此接口仅返回表计状态，不会返回表计的其它字段。

请求示例

{
	// 表计标识（单选）
	"Id": 6892141164168701,
	// 表计编号（单选）
	"Number": "M0001"
}

响应示例

{
	"Id": 6892141164168701,
	"Number": "M0001"，

	// 表显读数
	"Metering": 123,
	// 供应状态
	"State": {
		"value": 1,
		"name": "ON",
		"text": "供应"
	},
	// 状态更新时间戳
	"Timestamp": 76543234567543,
	// 响应状态码
	"Status": 2
}

校验表计编号(MeterUnique)

URL /actions/device/MeterUnique

PKG com.joyzl.scada.client.device.MeterUnique

校验表计编号是否可用。系统中不允许存在相同的表计编号，指定表计标识参数时，将排除指定表计的编号。

请求示例

{
	// 表计标识（可选）
	"Id": 249934146174993,
	// 编号（必要）
	"Number": "M0001"
}

响应示例

{
	"Id": 249934146174993, 
	"Number": "M0001",

	// 是否可用
	"Available": true,
	// 响应状态码
	"Status": 2,
}

新建表计(MeterCreate)

URL /actions/device/MeterCreate

PKG com.joyzl.scada.client.device.MeterCreate

创建新的表计用于抄表和监控。表计必须必须指定其所属的区域标识(ZoneId)参数；表计的编号应确保唯一不重复，可先通过校验表计编号(MeterUnique)接口验证；新创建的表计处于禁用状态，后续还须为表计绑定设备和属性。

请求示例

{
	// 区域标识（必要）
	"ZoneId": 4000605404135427,
	// 表计名称（必要）
	"Name": "2-5-6",
	// 能源类型（必要）
	"Type": 2,
	// 表计编号（必要）
	"Number": "M0001",
	// 备注（可选）
	"Remark": "电表",
	// 启用或禁用
	"Enable": true
}

响应示例

{
	"ZoneId": 4000605404135427,
	"Name": "2-5-6"
	"Type": {
		"name": "ELECTRIC",
		"value": 2,
		"text": "电",
		"unit": "kW·h"
	},
	"Number": "M0001",
	"Enable": true,
	"Remark": "电表",

	// 表计标识
	"Id": 249934146174993,
	// 创建时间
	"Created": "2024-4-25 10:16:01",
	// 响应状态码
	"Status": 2
}

修改表计(MeterUpdate)

URL /actions/device/MeterUpdate

PKG com.joyzl.scada.client.device.MeterUpdate

通过表计标识(Id)修改表计的常规字段值。表计所需的区域调整须通过 移动表计(MeterMove) 接口实现；表计启用或禁用须通过 启用或禁用表计(MeterEnable) 接口实现。

请求示例

{
	// 表计标识（必要）
	"Id": 618936194301960,
	// 表计名称（必要）
	"Name": "2-5-6",
	// 能源类型（必要）
	"Type": 2,
	// 表计编号（必要）
	"Number": "M0001",
	// 备注（可选）
	"Remark": "电表"
}

响应示例

{
	"Id": 618936194301960,
	"Name": "2-5-6"
	"Type": {
		"name": "ELECTRIC",
		"value": 2,
		"text": "电",
		"unit": "kW·h"
	},
	"Number": "M0001",
	"Remark": "电表",

	// 更新时间
	"Updated": "2023-08-11 11:44:47",
	// 响应状态码
	"Status": 2
}

更换表计(MeterChange)

URL /actions/device/MeterChange

PKG com.joyzl.scada.client.device.MeterChange

表计与设备(Device)并非绝对的一对一关系，在日常所见的每户水电气表场景下，通常一对一关系；但对于其它领域还存在多合一表具，单个表具即可为多户或多能源提供计量。

请求示例

{
	// 表计标识（必要）
	"Id": 6892141152267000,
	// 设备标识（可选）
	"DeviceId": 821196270600196,
	// 计量属性标识（可选）
	"MeteringId": 821177815662595,
	// 余量属性标识（可选）
	"ResidualId": 0,
	// 充量属性标识（可选）
	"RechargeId": 0,
	// 通断属性标识（可选）
	"WorkingId": 0
}

响应示例

{
	"Id": 6892141152267000,
	"DeviceId": 821196270600196,
	"MeteringId": 821177815662595,
	"ResidualId": 0,
	"RechargeId": 0,
	"WorkingId": 0,

	// 更新时间
	"Updated": "2023-07-31 14:26:01",
	// 响应状态码
	"Status": 2
}

启用或禁用表计(MeterEnable)

URL /actions/device/MeterEnable

PKG com.joyzl.scada.client.device.MeterEnable

被禁用的表计将不会纳入抄表序列也不会更新表计状态。

请求示例

{
	// 表计标识（必要）
	"Id": 6892141152267000,
	// 禁用或启用（必要）
	"Enable": true
}

响应示例

{
	"Id": 6892141152267000,
	"Enable": true,

	// 更新时间
	"Updated": "2023-07-31 14:26:01",
	// 响应状态码
	"Status": 2
}

移动表计(MeterMove)

URL /actions/device/MeterMove

PKG com.joyzl.scada.client.device.MeterMove

将表计从当前区域移动到其它的区域。表计改变区域不会影响表计的抄表数据。

请求示例

{
	// 表计标识（必要）
	"Id": 6892141152267000,
	// 区域标识（必要）
	"ZoneId": 6892141150584634
}

响应示例

{
	"Id": 6892141152267000,
	"ZoneId": 6892141150584634,

	// 更新时间
	"Updated": "2023-07-31 14:26:01",
	// 响应状态码
	"Status": 2
}

删除表计(MeterDelete)

URL /actions/device/MeterDelete

PKG com.joyzl.scada.client.device.MeterDelete

删除表计后，表计的抄表记录将无法读取，占用的存储空间将在数据过期后释放。

请求示例

{
	// 表计标识（必要）
	"Id": 6892180868975489
}

响应示例

{
	"Id": 6892180868975489,

	// 响应状态码
	"Status": 2
}

数据

获取表计任意时段时序数据的步骤：

获取遥测信号(SignalSelect)，查询诸如“功率”、“电流”、“电压”等信号的标识；
获取时序数据(ValueSelect)，按具体信号和时间段查询历史时序数据。

提示： 大部分时序数据都为浮点数或整数，可通过面积图或折线图以图形方式展现于最终用户，这有助于直观反应表计当时的工况。

获取遥测信号(SignalSelect)

URL /actions/device/SignalSelect

PKG com.joyzl.scada.client.device.SignalSelect

获取表计（设备）遥测的信号项。这些信号项（遥测信号）在生产加工过程中将被记录时序数据。表计（设备）通常有多项遥测信号（属性），接口会过滤掉不产生数据或仅用于控制的信号项。

遥测信号的属性标识(AttributeId)可用于获取时序数据，请参考通信类接口获取时序数据(ValueSelect) 了解更多信息。

请求示例

{
	// 设备标识（单选）
	"DeviceId": 821196270600196,
	// 表计标识（单选）
	"MeterId": 6892182769831190,
	// 表计编号（单选）
	"MeterNumber": "M0001"
}

响应示例

{
	"DeviceId": 2815031825661954,
	"MeterId": 6892182769831190,
	"MeterNumber": "M0001",

	// 信号集合
	"Signals": [
		{
			// 属性标识
			"AttributeId": 345659483765364,
			// 属性名称
			"Name": "电压",
			// 单位
			"Unit": "V"
		}
		…
	],
	// 响应状态码
	"Status": 2
}