# light **Repository Path**: sunyiming0328/light ## Basic Information - **Project Name**: light - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-07-03 - **Last Updated**: 2024-10-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 市-区景观照明数据接入 WEB API 接口协议 ### 1. 基本说明 市-区景观照明数据接入 WEB-API 接口主要用于市、区两级景观照明集中控 制平台间的数据、控制指令互联互通，同时也可作为市、区两级平台同各自辖区 内重要单体建筑或重要景观照明区域的互联互通。 主要包括： 1） 控制指令及参数设置接口 用于实现市景观照明控制系统对区景观照明控制系统获取控制权，释放控 制权，进行当日开关灯时间、开关灯模式设置，实时进行亮灯模式调用等； 2） 基础数据上报接口 用于实现区景观照明集控向市景观照明控制系统上报景观照明控制终端 基础数据，实时亮灯状态反馈数据，实时开灯计划及模式数据等 ### 2. 接口定义 ### 2.1 接口请求方式 采用 POST 和 GET 两种请求方式；请求参数和返回结果均包装为 Json String。 GET 请求的参数在 url 之后 所有返回均包含 status 和 message，data 中包含的为实际业务数据，以下接 口只描述 data。 { status: "200", message: "OK", data: { 属性名 1: "属性值 1" , 属性名 2 "属性值 2" } } 字段名 类型 含义 必 填 可为 空 备注 status String 200 表示成功，其它表示异常 Y N message String 成功或异常的提示信息 Y Y data Object 返回结果，业务数据，json 格 式 Y Y ### 2.2 接口一般性约束 • 所有接口和外链的 url 均使用 https 协议； • 市区两级接口应包含全部接口，返回值则可以根据自身提供的功能实现； • 接口路径前缀：https://host name Or IP/ lighting-rest/api/v1/； • 所有接口请求中的 header 都包含以下内容(平台登录接口除外)： 字段名 类型 含义 必填 可为 空 备注 authorization String 用户验证通过后的 token Y Y ### 2.3 环境参数 市局：https://xxx.xxx.xxx.xxx:21086/lighting-rest/api/v1/ 区局：由各区提供 ### 3. 接口名称 ### 3.1 平台登录接口 通过给定的用户名及密码向对端平台进行身份验证请求，对端平台验证成功 后返回用于数据通信的 token，后续的请求均需要使用该 token 进行； 单一用户/密码不支持多重登录，最后成功验证的 token 将取代之前的验证结 果。 ### 3.1.1 请求消息 Method URL GET https://host name Or IP/ lighting-rest/api/v1/DoLogin ### 3.1.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 String 外部集控系统 ID sysname 是 否 string 外部集控系统名称 password 是 否 String 密码 *注：以上参数包含在 Params 中。 ### 3.1.3 返回结果 参数名称 必填 可为空 参数类型 备注 token 是 否 string 128 位 SHA1 加密 token,用于 后续接口访问，默认有效期 24 小时 expirationDate 是 是 String token 时限 ### 3.2 获取控制权 市集中控制系统向区控制系统申请获取控制权，完成控制权获取后，区集中 控制系统才会响应市的控制指令请求。 ### 3.2.1 请求消息 Method URL POST https://host name Or IP/ lighting-rest/api/v1/permission/Request ### 3.2.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID duration 是 否 int 申请权限时长，单位秒 *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 ### 3.2.3 返回结果 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID validity 是 否 Int 权限有效性，0：无效，1：有效 expirationDate 是 否 string 权限有效时限， YYYY-MM-DD HH:mm:ss ### 3.3 释放控制权 市集中控制系统完成当日控制任务后，向区控制系统发送释放控权操作，完 成释放控权操作后，区控制系统回收控制权，并不在响应市控制系统的控制指令 和参数修改指令，数据查询指令则不受影响。 当区控制系统在市集控系统申请权限时长到达也自动收回控制权。 ### 3.3.1 请求消息 Method URL POST https://host name Or IP/ lighting-rest/api/v1/permission/Release ### 3.3.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 ### 3.2.3 返回结果 无。 ### 3.4 查询控制权状态 市景观照明集控系统向区集控系统查询当前的权限分配情况及信息。 ### 3.4.1 请求消息 Method URL GET https://host name Or IP/ lightingrest/api/v1/permission/QueryStatus ### 3.4.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID *注：authorization 参数包含在 header 中。 *注：以上参数包含在 Params 中。 ### 3.4.3 返回结果 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID validity 是 否 Int 权限有效性，0：无效，1：有效 expirationDate 是 否 string 权限有效时限，YYYY-MM-DD HH:mm:ss ### 3.5 设置站点开灯时间、模式 用于市集控系统向区集控系统中的单个或者批量站点设置当日的开关灯参数， 包括开关灯时间及模式等。 ### 3.5.1 请求消息 Method URL POST https://....../ lightingrest/api/v1/control/SetStationLightingParams ### 3.5.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID sysname 是 否 string 外部集控系统名称 operateTime 是 是 string 操作指令生成时间 stationParamList 是 否 Json StationParam JSON 对象列 表，具体见表 3.5.2-1 *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 StationParam JSON 对象格式 参数名称 必填 可为空 参数类型 备注 stationId 是 否 string 控制站点 ID turnonTime 否 是 string 当日开灯时间，HH:mm:ss turnoffTime 否 是 string 当日关灯时间，HH:mm:ss lightingMode 否 是 Int 当日开关灯模式，0 不使用，1 日常，2 节假日，3 重大节假日， 4-99 为自定义，其他为无效； 表：3.5.2-1 StationParam JOSN 对象定义 ### 3.5.3 返回结果 无。 ### 3.6 设置分组开灯时间、模式 用于市集控系统向区集控系统中的单个或多个开关灯分组设置开关灯参数， 包括开关灯时间及模式等。 区景观照明集控系统开关灯分组中包含的站点信息应通过“报送控制终端分 区分组信息“接口进行报送，市集控系统也可以通过”控制终端分区分组信息查询 接口“主动获取。 ### 3.6.1 请求消息 Method URL POST https://....../ lightingrest/api/v1/control/SetGroupLightingParams ### 3.6.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID operateTime 是 是 string 操作指令生成时间 GroupParamList 是 否 Json GroupParam JSON 对象列表， 具体见表 3.6.2-1 *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 GroupParam JSON 对象格式 参数名称 必填 可为空 参数类型 备注 groupId 是 否 Int 分组 ID turnonTime 否 是 string 当日开灯时间，HH:mm:ss turnoffTime 否 是 string 当日关灯时间，HH:mm:ss lightingMode 否 是 Int 当日开关灯模式，0 不使用，1 日常，2 节假日，3 重大节假日， 4-99 为自定义，其他为无效； 表：3.6.2-1 GroupParam JOSN 对象定义 ### 73.6.3 返回结果 无。 ### 3.7 实时切换亮灯动态节目 用于实现市集控系统实时调用区控制系统中的动态场景节目，区控制系统收 到指令后，按照事先约定的节目编号，进行节目播放，完成播放后恢复到当日设 定的亮灯模式。 ### 3.7.1 请求消息 Method URL POST https://....../ lighting-rest/api/v1/control/PlayDynamicProgram ### 3.7.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID operateTime 是 是 string 操 作 指 令 生 成 时 间 ， YYYYMM-DD HH:mm:ss programId 是 否 int 节目 id，范围 1-100 *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 ### 3.7.3 返回结果 参数名称 必填 可为空 参数类型 备注 programId 是 否 Int 播放的节目 id， duration 是 否 Int 节目持续时间，单位秒 ### 3.8 获取当前亮灯动态节目状态 市集控用于向区集控系统查询当前亮灯动态节目播放状态。 ### 3.8.1 请求消息 Method URL GET https://....../ lightingrest/api/v1/control/GetDynamicProgramStatus ### 3.8.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID *注：authorization 参数包含在 header 中。 *注：以上参数包含在 param 中。 ### 3.8.3 返回结果 参数名称 必填 可为空 参数类型 备注 programStatus 是 否 Int 播放的节目状态，0 未播放，1 正在播放 programId 否 否 Int 播放节目 id，如正在播放需填 充 startTime 否 否 String 节目开始时间，HH:mm:ss，如 正在播放需填充 ### 3.9 报送控制终端基础信息 用于区集控系统向市集控系统报送终端基础信息 ### 3.9.1 请求消息 Method URL POST https://....../ lighting-rest/api/v1/data/StationInfo ### 3.9.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID sysname 是 否 string 外部集控系统名称 operateMode 是 否 Int 1：增加站点操作 2：更新站点信息 3：删除站点操作 operateTime 是 否 String 操 作 时 间 YYYY-MM-DD HH:mm:ss StationInfoList 是 否 Json 数组 StationInfo JSON 对象列表，具 体参考表 3.9.1-1 *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 StationInfo JSON 对象格式 参数名称 必填 可为空 参数类型 备注 districtId 是 否 Int 行政区划代码，例：310105 stationId 是 否 int 站点 id stationName 是 否 String 站点名称 groupId 是 是 Int 站点所属开灯分组 address 是 否 String 站点地址 longitude 是 否 String 经度 latitude 是 否 String 纬度 circuitNum 否 否 Int 强电回路数 DMXNum 否 否 Int DMX 通道数 energyMeter 否 否 Int 是否装有电表，0 未安装，1 已 安装 表：3.6.2-1 StationInfo JOSN 对象定义 ### 3.9.3 返回结果 无。 ### 3.10 报送控制终端实时开灯状态 用于区集控系统向市集控系统报送站点开灯状态，包括实时开关灯状态，电 压、电流数据，能耗等。 ### 3.10.1 请求消息 Method URL POST https://....../ lighting-rest/api/v1/data/StationStatus ### 3.10.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID sysname 是 否 string 外部集控系统名称 updateTime 是 否 String 操作时间 YYYY-MM-DD HH:mm:ss StationStatusList 是 否 Json 数组 StationStatus JSON 对象列表， 具体参考表 3.10.1-1 *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 StationStatus JSON 对象格式 参数名称 必填 可为空 参数类型 备注 districtId 是 否 Int 行政区划代码，例：310105 stationId 是 否 int 站点 id stationName 是 否 String 站点名称 groupId 是 是 Int 站点所属开灯分组 inputDis 是 是 Int 数组 强电回路反馈，0：关闭，1： 开启 currentPhaseA 否 否 double A 相电流 currentPhaseB 否 否 double B 相电流 currentPhaseC 否 否 double C 相电流 voltagePhaseA 否 否 double A 相电压 voltagePhaseB 否 否 double B 相电压 voltagePhaseC 否 否 double C 相电压 activePower 否 否 double 有功功率 elecConsumption 否 否 Int 累计电量 表：3.6.2-1 StationStatus JOSN 对象定义 ### 3.10.3 返回结果 无。 ### 3.11 报送控制终端当日开灯计划 区景观照明集控系统向市集控系统上传当日景观照明开关灯计划，包括开关 灯时间，开关灯模式等。 开灯计划可按照定期上报结合逢变则报方式进行推送。 ### 3.11.1 请求消息 Method URL POST https://....../ lighting-rest/api/v1/data/StationLightingPlan ### 3.11.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID sysname 是 否 string 外部集控系统名称 updateTime 是 否 String 操作时间 YYYY-MM-DD HH:mm:ss LightingPlanList 是 否 Json 数组 LightingPlan JSON 对象列表， 具体参考表 3.11.3-1 *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 LightingPlan JSON 对象格式 参数名称 必填 可为空 参数类型 备注 districtId 是 否 Int 行政区划代码，例：310105 stationId 是 否 int 站点 id stationName 是 否 String 站点名称 groupId 是 是 Int 站点所属开灯分组 trunonTime 否 是 string 当日开灯时间，HH:mm:ss turnoffTime 否 是 string 当日关灯时间，HH:mm:ss lightingMode 否 是 Int 当日开关灯模式，0 不使用，1 日常，2 节假日，3 重大节假日， 4-99 为自定义，其他为无效； 表：3.11.3-1 LightingPlan JSON 对象字段表 ### 3.11.3 返回结果 无 ### 3.12 报送控制站点分区分组信息 区景观照明集控系统向市集控系统上传当前控制站点分组基本信息，可采用 定时上传或者逢变则报方式。 3.11.1 请求消息 Method URL POST https://....../ lighting-rest/api/v1/data/GroupInfo ### 3.12.2 请求参数 参数名称 必填 可为空 参数类型 备注 sysId 是 否 string 外部集控系统 ID sysname 是 否 string 外部集控系统名称 updateTime 是 否 String 操 作 时 间 YYYY-MM-DD HH:mm:ss GroupInfoList 是 否 Json 数组 GroupInfo JSON 对象列表，具 体参考表 3.12.3-1 *注：authorization 参数包含在 header 中。 *注：以上参数包含在 body 中。 GroupInfo JSON 对象格式 参数名称 必填 可为空 参数类型 备注 districtId 是 否 Int 行政区划代码，例：310105 groupId 是 否 int 开灯组 id groupName 是 否 String 开灯组名称 stationNum 是 否 Int 开灯组内站点数量 stationIdList 是 是 int 数组 开灯组内站点 id 列表 表：3.12.3-1 LightingPlan JSON 对象字段表 ### 3.12.3 返回结果 无