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	MeterReport	报告表计故障	SYATEM
Device	SignalSelect	获取遥测数据	SYATEM

能源类型(EnergyType)

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

能耗

能耗(Energy)是表计在每个轮值周期内记录的能耗用量。服务端(JOYZL SCADA Server) 会持久存储能耗记录，并根据配置的能耗数据有效时间自动清理过期数据，防止磁盘写满。

获取能耗总量(EnergyAmount)

URL /actions/energy/EnergyAmount

PKG com.joyzl.scada.client.energy.EnergyAmount

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

如果开始时间(Begin)和结束时间(End)颠倒，请求将返回数据错误(ERROR_DATA:7)；如果指定区域(ZoneId)或表计(MeterId/MeterNumber)不存在，请求将返回不存在(NOEXISTS:5) ；如果指定区域(ZoneId)或表计(MeterId/MeterNumber)位于当前用户所在区域之外，请求将被拒绝(DENIED:3) 。

请求示例

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

响应示例

{
	// 回显参数
	"ZoneId": 6892182778556009,
	"MeterId ": 6892182769831190,
	"MeterNumber": "M0001",
	"Type": {
		"Name": "ELECTRIC",
		"Value": 2,
		"Text": "电",
		"Unit": "kW·h"
	},
	"Begin": "2022-12-13 00:00:00",
	"End": "2022-12-13 23:59:59",

	// 能耗记录数量
	"Energy": 892,
	// 总能耗
	"Consumption": 7654,

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

获取能耗记录(EnergySelect)

URL /actions/energy/EnergySelect

PKG com.joyzl.scada.client.energy.EnergySelect

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

请求示例

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

响应示例

{
	// 回显参数
	"ZoneId": 6892182778556009,
	"MeterId": 6892182769831190,
	"MeterNumber": "M0001",
	"Type": {
		"Name": "ELECTRIC",
		"Value": 2,
		"Text": "电",
		"Unit": "kW·h"
	},
	"Begin": "2022-12-13 00:00:00",
	"End": "2022-12-13 23:59:59",

	// 能耗集合
	"Energys": [
		{
			// 表计标识
			"MeterId": 6892182769831190,
			// 表显读数
			"Metering": 87654,
			// 能耗量
			"Consumption": 89,
			// 开始时间
			"Begin": "2022-12-13 00:00:00",
			// 结束时间
			"End": "2022-12-13 23:59:59",
		}
		… 
	],

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

响应的能耗集合(Energys)数组不保证任何顺序。

表计

表计(Meter)表示能耗计量表，例如户用电表；为便于与通信装置进行区分，表计(Meter)视为能耗计量表，而设备(Device)对应通信装置。表计由系统中配置的设备自动生成，单个通信设备可能对应多个表计。

获取表计数量(MeterAmount)

URL /actions/energy/MeterAmount

PKG com.joyzl.scada.client.energy.MeterAmount

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

如果指定区域标识(ZoneId)不存在，请求将返回不存在(NOEXISTS:5) ；如果指定区域标识(ZoneId)位于当前用户所在区域之外，请求将被拒绝(DENIED:3) 。

请求示例

{
	// 区域标识（可选）
	"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/energy/MeterSelect

PKG com.joyzl.scada.client.energy.MeterSelect

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

如果指定区域标识(ZoneId)不存在，请求将返回不存在(NOEXISTS:5) ；如果指定区域标识(ZoneId)位于当前用户所在区域之外，请求将被拒绝(DENIED:3) 。

请求示例

{
	// 区域标识（可选）
	"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",
			// 表计编号
			"Number": "M0001",
			// 类型
			"Type": "E",
			// 生产厂商
			"Manufacturer": "WS",
			// 表计型号
			"Model": "ESD-002",
			// 能源类型
			"Energy": {
				"Value": 2,
				"Name": "ELECTRIC",
				"Text": "电",
				"Unit": "kW·h"
			},			
			// 启用或禁用
			"Enable": true,
			// 创建时间
			"Created": "2025-08-26 10:15:00",
			// 更新时间
			"Updated": "2025-08-26 11:15:00",

			// 供应状态
			"State": {
				"Value": 1,
				"Name": "ON",
				"Text": "供应"
			},
			// 告警状态
			"Alarm": {
				"Name": "NONE",
				"Text": "无",
				"Value": 0
			},
			// 报告状态
			"Report": {
				"Name": "NORMAL",
				"Text": "正常",
				"Value": 0
			},
			// 表显读数
			"Metering": 87654,
			// 能耗量
			"Consumption": 89,
			// 状态更新时间戳
			"Timestamp": 1789019713528
		}
		…
	],

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

响应的表计集合(Meters)数组不保证任何顺序。能耗量(Consumption)仅表示当前轮值班次，在下一值班次会自动重置。

供应状态(State)可能值有：未知(UNKNOWN:0)、供应(ON:1)、中断(OFF:2)；告警状态(Alarm)可能值有：无(NONE:0)、四级（低级）(NOTICE:1)、三级（中级）(WARNING:2)、二级（高级）(DANGER:3)、一级（紧急）(CRITICAL:4)；报告状态(Report)可能值有：正常(NORMAL:0)、故障(FAULT:1)；

获取单个表计(MeterQuery)

URL /actions/energy/MeterQuery

PKG com.joyzl.scada.client.energy.MeterQuery

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

如果指定表计(Id/Number)不存在，请求将返回不存在(NOEXISTS:5) ；如果指定表计(Id/Number)位于当前用户所在区域之外，请求将被拒绝(DENIED:3) 。

请求示例

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

响应示例

{
	// 回显参数
	"Id": 6892141164168701,
	"Number": "M0001",

	// 表计
	"Meter": {
		// 表计标识
		"Id": 6892189876541566,
		// 区域标识
		"ZoneId": 4000605404135427,
		// 表计名称
		"Name": "电能表 2-5-6",
		// 表计编号
		"Number": "M0001",
		// 类型
		"Type": "E",
		// 生产厂商
		"Manufacturer": "WS",
		// 表计型号
		"Model": "ESD-002",
		// 能源类型
		"Energy": {
			"Value": 2,
			"Name": "ELECTRIC",
			"Text": "电",
			"Unit": "kW·h"
		},			
		// 启用或禁用
		"Enable": true,
		// 创建时间
		"Created": "2025-08-26 10:15:00",
		// 更新时间
		"Updated": "2025-08-26 11:15:00",
		
		// 供应状态
		"State": {
			"Value": 1,
			"Name": "ON",
			"Text": "供应"
		},
		// 告警状态
		"Alarm": {
			"Name": "NONE",
			"Text": "无",
			"Value": 0
		},
		// 报告状态
		"Report": {
			"Name": "NORMAL",
			"Text": "正常",
			"Value": 0
		},
		// 表显读数
		"Metering": 87654,
		// 能耗量
		"Consumption": 89,
		// 状态更新时间戳
		"Timestamp": 1789019713528
	},

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

能耗量(Consumption)仅表示当前轮值班次，在下一轮值班次会自动重置。

获取表计状态(MeterState)

URL /actions/energy/MeterState

PKG com.joyzl.scada.client.energy.MeterState

获取指定表计的最新状态。此接口仅返回表计状态，不会返回表计的其它字段。此接口通常用于逐个轮询获取表计的最新状态。

如果指定表计(Id/Number)不存在，请求将返回不存在(NOEXISTS:5) ；如果指定表计(Id/Number)位于当前用户所在区域之外，请求将被拒绝(DENIED:3) 。

请求示例

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

响应示例

{
	// 回显参数
	"Id": 6892141164168701,
	"Number": "M0001",

	// 供应状态
	"State": {
		"Value": 1,
		"Name": "ON",
		"Text": "供应"
	},
	// 告警状态
	"Alarm": {
		"Name": "NONE",
		"Text": "无",
		"Value": 0
	},
	// 报告状态
	"Report": {
		"Name": "NORMAL",
		"Text": "正常",
		"Value": 0
	},
	// 表显读数
	"Metering": 87654,
	// 能耗量
	"Consumption": 89,
	// 状态更新时间戳
	"Timestamp": 1789019713528,

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

能耗量(Consumption)仅表示当前轮值班次，在下一轮值班次会自动重置。

报告表计故障(MeterReport)

URL /actions/energy/MeterReport

PKG com.joyzl.scada.client.energy.MeterReport

由人工报告表计故障。

如果指定表计(Id/Number)不存在，请求将返回不存在(NOEXISTS:5) ；如果指定表计(Id/Number)位于当前用户所在区域之外，请求将被拒绝(DENIED:3) 。

请求示例

{
	// 表计标识（单选）
	"Id": 6892141164168701,
	// 表计编号（单选）
	"Number": "M0001",
	// 故障状态（必要）
	"Report": 1
}

响应示例

{
	// 回显参数
	"Id": 6892141164168701,
	"Number": "M0001",
	"Report": {
		"Name": "FAULT",
		"Text": "故障",
		"Value": 1
	},

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

数据

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

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

可获取的数据时段受限于服务端配置的数据保存时限，假设服务端配置存储历史数据最多20年，那么20年前的数据将被自动清理，如果查询20年前的数据则不会有数据返回。

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

获取遥测信号(SignalSelect)

URL /actions/device/SignalSelect

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

获取指定设备的遥测信号（数据项）。这些信号（数据项）在设备运行过程中将被记录时序数据。每个设备有多项遥测信号（每个数据项对应一个设备属性），接口会过滤掉不产生数据或仅用于控制的信号。

指定设备标识(DeviceId)可获取单个设备的数据项（设备属性）；指定设备编号(DeviceNumber)可获取多个相同编号设备的数据项（设备属性）；表计编号(MeterNumber)即为设备编号(DeviceNumber)，如果要获取表计的数据项，将表计编号赋予此接口的设备编号即可。

如果指定设备(DeviceId)不存在，请求将返回不存在(NOEXISTS:5) ；如果指定设备(DeviceId)位于当前用户所在区域之外，请求将被拒绝(DENIED:3) 。如果指定设备(DeviceNumber)编号，并且存在多个相同编号的设备时，仅返回当前用户所在区域内的设备属性。

请求示例

{
	// 设备标识（单选）
	"DeviceId": 821196270600196,
	// 设备编号（单选）
	"DeviceNumber": "M0001"
}

响应示例

{
	// 回显参数
	"DeviceId": 821196270600196,
	"DeviceNumber": "M0001",

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

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

响应的信号集合(Signals)数组不保证任何顺序。遥测信号的属性标识(AttributeId)可用于获取指定时段的时序数据，请参考通信类接口获取时序数据(ValueSelect) 了解更多信息。