把任何東西接進 HA：RESTful、命令列、Webhook 三招

charles

找不到整合？這三招可以接幾乎任何東西。



第一招：RESTful sensor（接 API）

任何會回傳 JSON 的網址都可以接。

基本寫法：

1. sensor:
2.   - platform: rest
3.     name: 我的API資料
4.     resource: https://api.example.com/data
5.     method: GET
6.     scan_interval: 300
7.     value_template: "{{ value_json.temperature }}"
8.     unit_of_measurement: "°C"
9.     device_class: temperature
10.     json_attributes:
11.       - humidity
12.       - pressure

複製代碼

重點：

• value_template —— 從 JSON 取出主要的值
  
• json_attributes —— 其他欄位存成屬性
  
• scan_interval —— 多久抓一次（秒）
  

一次抓一包資料，拆成多個感測器

這是更有效率的做法：

1. rest:
2.   - resource: https://api.example.com/data
3.     scan_interval: 300
4.     sensor:
5.       - name: 溫度
6.         value_template: "{{ value_json.temp }}"
7.         unit_of_measurement: "°C"
8.         device_class: temperature
9.       - name: 濕度
10.         value_template: "{{ value_json.humidity }}"
11.         unit_of_measurement: "%"
12.         device_class: humidity
13.       - name: 氣壓
14.         value_template: "{{ value_json.pressure }}"
15.         unit_of_measurement: hPa

複製代碼

只發一次請求，產生三個感測器 —— 不會被 API 限流。

需要認證的 API：

1.     headers:
2.       Authorization: !secret my_api_token
3.       Content-Type: application/json

複製代碼

或者用參數：

1.     params:
2.       key: !secret api_key
3.       format: json

複製代碼

POST 請求：

1.     method: POST
2.     payload: '{"query": "something"}'

複製代碼

RESTful switch（可以控制的）

1. switch:
2.   - platform: rest
3.     name: 我的裝置
4.     resource: http://192.168.1.50/api/relay
5.     body_on: '{"state": "on"}'
6.     body_off: '{"state": "off"}'
7.     is_on_template: "{{ value_json.state == 'on' }}"
8.     headers:
9.       Content-Type: application/json

複製代碼

可以接：

• 有 HTTP API 的裝置
  
• 自己寫的伺服器
  
• NAS 的 API
  
• 路由器的 API
  

第二招：命令列（command_line）

可以執行任何 shell 命令。

1. command_line:
2.   - sensor:
3.       name: 硬碟使用率
4.       command: "df -h / | awk 'NR==2 {print $5}' | tr -d '%'"
5.       unit_of_measurement: "%"
6.       scan_interval: 600
8.   - sensor:
9.       name: 網路延遲
10.       command: "ping -c 3 8.8.8.8 | tail -1 | awk -F '/' '{print $5}'"
11.       unit_of_measurement: ms
12.       scan_interval: 300
14.   - binary_sensor:
15.       name: NAS在線
16.       command: "ping -c 1 -W 2 192.168.1.20 > /dev/null && echo ON || echo OFF"
17.       payload_on: "ON"
18.       payload_off: "OFF"
19.       scan_interval: 60
21.   - switch:
22.       name: 喚醒電腦
23.       command_on: "wakeonlan AA:BB:CC:DD:EE:FF"
24.       command_off: "echo skip"
25.       command_state: "ping -c 1 -W 2 192.168.1.30 > /dev/null && echo ON"
26.       value_template: "{{ value == 'ON' }}"

複製代碼

注意：

• HA OS 的容器裡不一定有那些命令（wakeonlan、nc 等）
  
• 可以用 Python 腳本代替
  
• Docker 版的話要自己裝工具
  

執行 Python 腳本：

1. command_line:
2.   - sensor:
3.       name: 我的計算
4.       command: "python3 /config/scripts/my_script.py"
5.       value_template: "{{ value_json.result }}"

複製代碼

腳本輸出 JSON 就能用 value_json 取值。



第三招：Webhook（讓外部通知 HA）

前兩招是 HA 主動去拿，這招是別人主動推給 HA。

建立一個 webhook 觸發器：

1. automation:
2.   - alias: 收到外部通知
3.     triggers:
4.       - trigger: webhook
5.         webhook_id: my_secret_webhook_12345
6.         allowed_methods:
7.           - POST
8.         local_only: true
9.     actions:
10.       - action: script.通知
11.         data:
12.           等級: 一般
13.           標題: "{{ trigger.json.title }}"
14.           訊息: "{{ trigger.json.message }}"

複製代碼

呼叫的方式：

1. curl -X POST \
2.   -H "Content-Type: application/json" \
3.   -d '{"title":"測試","message":"從外部來的"}' \
4.   http://你的HA:8123/api/webhook/my_secret_webhook_12345

複製代碼

重要的安全設定：

• webhook_id 要夠長夠隨機 —— 它就是密碼
  
• local_only: true —— 只接受區網內的請求
  
• allowed_methods —— 限制方法
  

用途：

• IFTTT、Zapier 之類的服務推過來
  
• 自己寫的腳本通知 HA
  
• 路由器、NAS 的事件通知
  
• 手機捷徑（iOS Shortcuts）觸發
  

iOS 捷徑的用法：

• 建立一個捷徑
  
• 動作選「取得 URL 內容」
  
• 方法 POST，網址填你的 webhook
  
• 可以加到主畫面或 Siri
  

這樣不用裝 HA App 也能觸發自動化。



實際的例子

例一：接路由器的流量

1. sensor:
2.   - platform: rest
3.     name: 今日上傳
4.     resource: http://192.168.1.1/api/stats
5.     value_template: "{{ (value_json.tx_bytes / 1073741824) | round(2) }}"
6.     unit_of_measurement: GB
7.     scan_interval: 600
8.     headers:
9.       Authorization: !secret router_token

複製代碼

例二：檢查網站有沒有掛

1. binary_sensor:
2.   - platform: rest
3.     name: 我的網站正常
4.     resource: https://example.com/health
5.     value_template: "{{ value_json.status == 'ok' }}"
6.     scan_interval: 300
7.     device_class: connectivity

複製代碼

搭配通知：

1. automation:
2.   - alias: 網站掛了
3.     triggers:
4.       - trigger: state
5.         entity_id: binary_sensor.我的網站正常
6.         to: "off"
7.         for: "00:05:00"
8.     actions:
9.       - action: script.通知
10.         data:
11.           等級: 緊急
12.           標題: 網站掛了
13.           訊息: 已經五分鐘沒有正常回應

複製代碼

例三：接空氣品質

1. rest:
2.   - resource: https://data.example.gov.tw/api/aqi
3.     scan_interval: 1800
4.     params:
5.       station: 你的測站
6.     sensor:
7.       - name: AQI
8.         value_template: "{{ value_json.aqi }}"
9.         state_class: measurement
10.       - name: PM2.5
11.         value_template: "{{ value_json.pm25 }}"
12.         unit_of_measurement: "μg/m³"
13.         device_class: pm25

複製代碼

例四：用 shell_command 發送資料出去

1. shell_command:
2.   記錄到外部: >
3.     curl -X POST -H "Content-Type: application/json"
4.     -d '{"temp": {{ states("sensor.客廳溫度") }} }'
5.     https://my-server.com/log

複製代碼

然後在自動化裡呼叫：

1.       - action: shell_command.記錄到外部

複製代碼

除錯技巧

一、先用 curl 或瀏覽器測試 API

確認網址、認證、回傳格式都對，再寫進 HA。

二、用模板編輯器測 value_template

1. {% set value_json = {"temp": 26.5, "hum": 60} %}
2. {{ value_json.temp }}

複製代碼

三、看日誌

1. logger:
2.   logs:
3.     homeassistant.components.rest: debug

複製代碼

四、常見錯誤

• 回傳的不是 JSON → 用 value 而不是 value_json
  
• JSON 的結構比較深 → value_json.data.items[0].value
  
• API 有限流 → scan_interval 調長
  
• HTTPS 憑證問題 → 加 verify_ssl: false（自簽憑證時）
  

一個重要的提醒

scan_interval 不要設太短：

• 很多免費 API 有每日次數限制
  
• 設 60 秒的話一天就是 1440 次
  
• 天氣、空氣品質這類 600-1800 秒就夠
  
• 需要即時的話用 webhook（讓對方推給你）
  

---

下一篇：整個系列的完整檢查表。