仪表板数据 API
功能概述
Dashboard Data API 是 Weincloud Dashboard 提供的开放式应用程序接口（Open API），可让用户以程序化方式访问仪表板中的 HMI 标签数据与报警数据，不必通过网页界面手动查询。通过此 API，可将标签历史数据、实时数值与报警记录整合至外部系统（例如 Power BI、Grafana，或自行开发的应用程序），用于数据分析、报表制作或跨系统监控。
使用流程分为三个阶段：在 Weincloud 创建 API 密钥 → 在 HTTP Request Header 中带上密钥进行验证 → 调用对应的 API 获取数据。
使用场景与适用对象
适用于下列场景：
- 将 HMI 数据导入第三方 BI／可视化工具，建立自定义报表或仪表板
- 以程序化方式定期获取标签历史数据，进行数据分析或备份
- 将报警数据整合至现有的运维通知或工单系统
主要适用对象为熟悉 HTTP API 调用方式的系统集成人员与开发者。
权限与访问范围
可管理 API 密钥的权限
只有具备下列任一权限时，左侧菜单才会出现 API 密钥管理页面：
- Domain Superuser
- Subdomain Superuser
- 文件夹层级的 Dashboard-Manage 权限
创建密钥时，〔用户〕列表仅列出当前账号有权管理的用户，默认带入自己。
密钥可访问的数据范围
每一把 API 密钥都隶属于一位指定的用户。密钥可访问的数据范围，等同该密钥所属用户在 Dashboard 中可查看的数据范围，而非创建者的权限范围。
每位用户最多只能持有一把 API 密钥。若列表中已有该用户的密钥，创建对话框会显示“此用户已有 API 密钥”并无法提交；需先撤销旧密钥才能重新创建。
创建与管理 API 密钥
前往管理页面
在左侧菜单的〔Dashboard〕分组点击〔仪表板 API 密钥〕，即可查看与管理 API 密钥。
列表默认将自己的密钥排在最前，并提供下列列：
- 〔名称〕：创建时输入的密钥名称，可排序
- 〔用户名称〕：密钥所属的用户；自己的密钥会标注〔你〕
- 〔API 密钥〕：密钥内容，默认以圆点遮蔽
- 〔创建时间〕：密钥创建日期，可排序
- 〔到期状态〕：显示〔永久有效〕、到期日期、剩余天数或〔已过期〕；剩余 7 天内以警示色标示，可排序
创建 API 密钥
- 点击右上角的〔新增 API 密钥〕，打开〔创建新 API 密钥〕对话框。
- 在〔用户〕选择密钥所属的用户。
- 在〔密钥名称〕输入名称，长度上限为 32 个字符。
- 在〔到期时间〕选择下列其中一项：
- 〔1 年后（预设）〕
- 〔永久有效〕
- 〔自定义日期〕：自行指定到期日，最早可选择次日
- 点击〔新增 API 密钥〕完成创建。
密钥创建后即出现在列表中，且可随时展开查看；不需在创建当下另行抄录保存。
查看与复制密钥
- 点击〔API 密钥〕列的眼睛图标，可切换显示或遮蔽密钥内容。
- 点击复制图标可将密钥复制到剪贴板。复制图标仅出现在自己所属的密钥，他人的密钥无法通过此按钮复制。
延长到期时间
点击密钥行右侧的时钟图标，选择延长幅度：+1 Day、+30 Days、+180 Days、+1 Year。延长成功后，〔到期状态〕列会立即更新。
撤销密钥
点击密钥行右侧的垃圾桶图标，在确认对话框按下〔删除〕即撤销该密钥。撤销为不可恢复的操作；密钥撤销后，所有沿用该密钥的集成将无法再访问 API，需重新创建密钥并更新至外部系统。
搜索、排序与列显示
- 搜索框可按密钥名称或用户名称筛选列表。
- 点击〔名称〕、〔创建时间〕、〔到期状态〕的列标题可切换升序／降序排序；拖曳列标题右缘可调整列宽。
- 点击〔更多〕展开面板，在〔栏位〕勾选要显示的列；此面板中也有前往 API 文档的〔API 档案〕按钮。
- 列表底部可调整每页显示条数（10／20／50／100）并切换页码。
使用 API 密钥进行验证
调用任何开放 API 时，都需在 HTTP Request Header 中带上密钥：
X-API-KEY: {API 密钥}验证通过后即可访问该密钥所属用户权限范围内的数据。
查阅 API 文档
Weincloud 提供在线 API 文档，列出所有已开放的 API 及其请求格式：
- 全球服务器文档位置：
https://www.weincloud.net/open-api - 中国服务器文档位置：
https://www.weincloud.net.cn/open-api
也可在〔仪表板 API 密钥〕页面点击〔更多〕→〔API 档案〕，在新窗口打开同一份文档。
文档页面会列出所有开放 API；点击右上角的 Authorize 按钮，即可放置 API 密钥以测试调用。
在 Value 字段输入 API 密钥即可完成授权。
可用 API 一览
目前提供下列 API 以获取仪表板相关数据，详细请求格式与参数请参考查阅 API 文档。
获取标签属性
GET /dashboard/api/v2/open_api/hmi/{hw_key}/tags
获取指定 HMI 的所有标签信息，包含标签名称、数据类型、单位等属性。
获取标签历史数据
POST /dashboard/api/v2/open_api/history
获取指定标签的历史数据，可指定时间范围与采样方式，适合用于绘制趋势图或进行数据分析。
- 可一次获取多个标签的历史数据，并单独指定各标签的采样方式（平均、总和、最大值、最小值等）
- 本 API 有数据条数限制，详见限制条件与注意事项
获取标签最新数据
POST /dashboard/api/v2/open_api/latest
获取指定标签的最新数值，适合用于实时监控或仪表板显示。
- 可一次获取多个标签的最新数据
- 本 API 有数据条数限制，详见限制条件与注意事项
获取报警分类
GET /dashboard/api/v2/open_api/alarms/categories
获取系统中所有报警分类的列表，用于报警管理与分类查询。
获取报警规则
POST /dashboard/api/v2/open_api/hmi/{hw_key}/alarms/rules
获取指定 HMI 的报警规则设置，包含触发条件、报警等级等信息。
获取报警历史记录
POST /dashboard/api/v2/open_api/hmi/{hw_key}/alarms/history
获取指定 HMI 的报警历史记录，可指定时间范围与筛选条件，用于报警追踪与分析。
限制条件与注意事项
为确保系统稳定性，获取标签历史数据的 API 目前设有下列限制。
单次请求上限 4,320 条
- 趋势图实时模式以 5 秒为单位获取数据，换算后单次最多可获取 6 小时内的数据：60 秒 × 60 分 × 6 小时 ÷ 5 秒 = 4,320 条。
- 若已开启合计设置，系统改以〔集合大小〕为单位获取数据；例如集合大小设为 1 分钟时，单次最多可获取 3 天内的数据：60 秒 × 60 分 × 24 小时 × 3 天 ÷ 60 秒 = 4,320 条。
超出单次请求上限时，可采取下列任一方式应对：
- 将时间范围调整至限制以内
- 开启合计设置，并将〔集合大小〕调大，以减少每次获取的数据量
- 将时间范围切分为多个区段，分批获取后再自行合并结果
单一 HMI 流量限制
单一 HMI 在 15 分钟内最多允许获取约 100 MB 的数据，超过此限制将导致获取失败。
密钥管理注意事项
- 密钥等同该用户的数据访问权限，请以机密信息方式保管，勿写入公开的代码仓库或分享至外部。
- 每位用户最多一把密钥；若需轮换密钥，须先撤销旧密钥再创建新密钥，期间相关集成会中断。
- 密钥到期后调用将失效，建议在到期前使用延长功能，或改用〔永久有效〕。
常见问题
左侧菜单没有〔仪表板 API 密钥〕，该如何处理？
该页面需要 Domain Superuser、Subdomain Superuser 或 Dashboard-Manage 权限才会显示，请确认账号权限或咨询 Domain 管理者。
可以为同一位用户创建多把密钥吗？
不行，每位用户最多一把。需要更换密钥时，请先撤销现有密钥再重新创建。
密钥忘记保存怎么办？
密钥不会隐藏丢失，随时可在列表中点击眼睛图标重新查看。
为什么有些密钥没有复制按钮？
复制按钮仅出现在自己所属的密钥。若需将密钥交给其他用户使用，请由该用户自行登录后复制。
密钥已过期，数据还能获取回来吗？
不会。请先使用延长到期功能，或撤销后重新创建密钥并更新至外部系统。