Weincloud Support
Search K

正體中文 (繁體)

English
中文 (简体)

正體中文 (繁體)

English
中文 (简体)

Appearance

透過 Webhook 接收推播通知 ​

您可以設定自訂 Webhook 來接收人機的推播通知。這讓您能夠：

  • 將推播通知整合到您自己的系統或應用程式中
  • 使用自己的 LINE 官方帳號或 Telegram Bot
  • 與企業通知系統或自訂應用程式整合
  • 將推播通知轉換為其他自動化工作流程的事件觸發器

要求：

  • 已啟用 EasyAccess 2.0 的人機
  • 在 EasyBuilder Pro 中啟用了推播通知
  • 一個 Webhook 端點（建議使用 HTTPS）
  • 設定 Webhook 的 Domain Admin 權限

在 Weincloud 中設定 Webhook ​

建立 Webhook ​

  1. 透過社群登入登入 Weincloud（詳情請參考 社群登入）
  2. 從左側欄選擇 警報通知 進入「社群登入設定/警報通知」頁面
  3. 點選 建立 Webhook
  4. 填寫 Webhook 設定：
    • Webhook 名稱：為您的 Webhook 取一個描述性名稱
    • 端點 URL：將傳送 Webhook 請求的 URL（例如：https://your-server.com/webhook）
    • API 金鑰：（選用但建議）用於身分驗證的金鑰

關聯人機與 Webhook ​

建立 Webhook 後，您需要將其與特定的人機關聯：

  1. 選擇您建立的 Webhook（右側面板將預設顯示 資訊 標籤）
  2. 切換到 HMIs 標籤
  3. 點選 新增 選擇人機
  4. 選擇應向此 Webhook 傳送推播通知的人機
  5. 點選 新增

測試您的 Webhook ​

您可以在部署前測試 Webhook 設定：

  1. 選擇您設定的 Webhook
  2. 點選 測試 按鈕
  3. Weincloud 將向您的端點傳送測試資料
  4. 檢查回應狀態並驗證您的端點是否正確接收到請求

Webhook 請求格式 ​

當關聯的人機上發生事件時，Weincloud 將向您設定的 Webhook URL 傳送 HTTP POST 請求。

HTTP 標頭 ​

X-API-KEY: <your api key>
Content-Type: application/json

注意： 您可以在伺服器中驗證 X-API-KEY 標頭，以確保它與設定的 API 金鑰相符，從而進行身分驗證。

資料內容示例 ​

json
{
  "hwkey": "<hardware key>",
  "message": {
    "de": "Online",
    "en-US": "Online",
    "es-ES": "En linea",
    "fr-FR": "En ligne",
    "it": "Online",
    "ja": "オンライン",
    "ko": "온라인",
    "pl": "Online",
    "ru": "Онлайн",
    "zh-CN": "在线",
    "zh-TW": "連線"
  },
  "hmiName": "<device name>",
  "hmiTime": "2025-01-01 00:00:00",
  "serverTime": "2025-01-01 00:00:00",
  "eventType": "event-online-offline"
}

注意： message 物件中的語言鍵可能與此範例不同。實際的語言取決於您的 HMI 專案設定。

欄位說明 ​

欄位類型說明
hwkeystring人機裝置的唯一硬體金鑰
hmiNamestring人機的顯示名稱（如果設定了暱稱則為暱稱，否則為裝置名稱）
messageobject多語言事件訊息（鍵值對）
hmiTimestring事件在人機上發生的時間戳記（格式：YYYY-MM-DD HH:MM:SS）。時區遵循人機的設定。
serverTimestring事件到達伺服器的時間戳記（格式：YYYY-MM-DD HH:MM:SS）。時區取決於伺服器區域：全球區域為 UTC+0，中國區域為 UTC+8。
eventTypestring觸發通知的事件類型（見下文）

事件類型 ​

事件類型說明
event-trigger觸發事件 - 警報或條件被觸發
event-recover恢復事件 - 之前觸發的警報已恢復
event-online-offline設備在線/離線事件

實作範例 ​

以下是流行的無伺服器平台的實作範例。這些範例展示了如何接收 Webhook 請求、驗證身分以及將通知轉發到訊息平台。

AWS Lambda ​

AWS Lambda 是一種無伺服器運算服務，可回應 HTTP 請求執行您的程式碼，無需管理伺服器。

設定步驟（AWS Lambda） ​

  1. 建立 Lambda 函式

    • 前往 AWS Lambda 主控台
    • 點選 建立函式
    • 選擇 從頭開始撰寫
    • 輸入函式名稱
    • 選擇 Python 3.13 執行階段
    • 建立函式

  2. 設定環境變數

    • 進入 組態 → 環境變數
    • 新增所需的變數（請參考下面的 環境變數）
    • 點選 儲存

  3. 部署程式碼

    • 從下面的 範例程式碼下載 下載範例檔案
    • 將程式碼複製到 Lambda 函式編輯器中
    • 點選 部署

  4. 建立函式 URL

    • 進入 組態 → 函式 URL
    • 點選 建立函式 URL
    • 驗證類型：NONE（您可以使用 API 金鑰實作自己的驗證）
    • 點選 儲存
    • 複製產生的 URL

  5. 在 Weincloud 中設定

    • 使用 Lambda 函式 URL 作為您的 Webhook 端點
    • 將 API 金鑰設定為與 EXPECTED_API_KEY 環境變數相符
    • 在 Weincloud 中點選 測試 驗證設定

Cloudflare Workers ​

Cloudflare Workers 是一個無伺服器平台，可在 Cloudflare 的全球邊緣網路上執行您的程式碼。

設定步驟（Cloudflare Workers） ​

  1. 建立 Worker

    • 登入 Cloudflare 控制面板
    • 導覽至 Workers & Pages
    • 點選 建立應用程式
    • 點選 從 Hello World 開始!
    • 為您的 Worker 命名
    • 點選 部署

  2. 部署程式碼

    • 從下面的 範例程式碼下載 下載範例檔案
    • 在您的 Worker 中點選 編輯程式碼
    • 用範例程式碼替換預設程式碼
    • 點選 部署

  3. 設定環境變數

    • 進入 設定 → 變數和祕密
    • 新增所需的變數（請參考下面的 環境變數）
    • 點選 儲存

  4. 取得 Worker URL

    • 複製您的 Worker 的 URL（例如：https://your-worker.your-subdomain.workers.dev）
    • 在 Weincloud 中使用此 URL 作為您的 Webhook 端點
    • 在 Weincloud 中點選 測試 驗證設定

範例程式碼下載 ​

以下是在不同平台上實作 Webhook 端點的完整範例程式碼檔案。這些範例展示了如何接收來自 Weincloud 的 Webhook 請求、驗證 API 金鑰、解析酬載並將訊息轉發到 LINE 或 Telegram。

AWS Lambda 範例 ​

📥 下載 aws_lambda_line.py (Python - LINE)

📥 下載 aws_lambda_telegram.py (Python - Telegram)

Cloudflare Workers 範例 ​

📥 下載 cloudflare_worker_line.js (JavaScript - LINE)

📥 下載 cloudflare_worker_telegram.js (JavaScript - Telegram)

這些範例包括：

  • API 金鑰身分驗證驗證
  • Webhook 酬載解析和驗證
  • 訊息轉發到 LINE Messaging API 或 Telegram Bot API
  • 環境變數設定

環境變數 ​

所有範例程式碼都需要在您的無伺服器平台（AWS Lambda 或 Cloudflare Workers）中設定以下環境變數：

LINE 整合 ​

變數說明如何取得
EXPECTED_API_KEY用於 Webhook 身分驗證的 API 金鑰設定為與 Weincloud 中設定的 API 金鑰相符
LINE_CHANNEL_ACCESS_TOKENLINE Messaging API 頻道存取權杖LINE Developers 主控台 → 建立/選擇頻道 → 頻道設定
LINE_USER_ID要傳送訊息的 LINE 使用者 ID 或群組 ID個人聊天：從您的 LINE 個人檔案取得，或使用 LINE Bot 收集使用者 ID
群組聊天：將您的 LINE Bot 加入群組，然後檢查 LINE Webhook 日誌或使用 LINE Bot SDK 取得群組 ID

外部資源：

Telegram 整合 ​

變數說明如何取得
EXPECTED_API_KEY用於 Webhook 身分驗證的 API 金鑰設定為與 Weincloud 中設定的 API 金鑰相符
TELEGRAM_BOT_TOKENTelegram 機器人權杖使用 @BotFather 建立機器人
TELEGRAM_CHAT_ID要傳送訊息的聊天室 ID個人聊天：使用像 @userinfobot 這樣的機器人取得您的聊天室 ID
群組聊天：將您的 Bot 加入群組，傳送一則訊息，然後造訪 https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates 找到群組聊天室 ID（負數）

外部資源：

設定說明：

  • 對於 AWS Lambda：在 組態 → 環境變數 中新增環境變數
  • 對於 Cloudflare Workers：在 設定 → 變數 中新增變數
  • EXPECTED_API_KEY 必須與您在 Weincloud Webhook 設定中設定的 API 金鑰相符
  • 保護所有憑證和金鑰，避免洩露給未經授權的人員