儀表板資料 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 管理者。
可以為同一位使用者建立多把金鑰嗎？
不行，每位使用者最多一把。需要更換金鑰時，請先撤銷既有金鑰再重新建立。
金鑰忘記保存怎麼辦？
金鑰不會隱藏遺失，隨時可在清單中點擊眼睛圖示重新檢視。
為什麼有些金鑰沒有複製按鈕？
複製按鈕僅出現在自己所屬的金鑰。若需將金鑰交給其他使用者使用，請由該使用者自行登入後複製。
金鑰已過期，資料還取得回來嗎？
不會。請先使用延長到期功能，或撤銷後重新建立金鑰並更新至外部系統。