HA 的 REST API 實戰：用 curl 控制你家的燈

charles

這篇講的東西平常用不到，但只要你想從 HA 以外的地方做任何事
（腳本、NAS 的排程、另一台電腦、甚至路由器），就非它不可。



第一步：拿一個長期權杖

點左下角你的名字 → 拉到最下面「長期存取權杖」→ 建立權杖

取個名字（例如 nas-script），然後馬上複製。
那串字只會顯示一次，關掉就再也看不到了，只能刪掉重建。

權杖預設效期十年。它等同於你的帳號權限，不要貼在論壇或 GitHub 上。

第二步：確認 API 通不通

1. curl -s -X GET \
2.   -H "Authorization: Bearer 你的權杖" \
3.   -H "Content-Type: application/json" \
4.   http://192.168.1.50:8123/api/

複製代碼

回傳這樣就對了：

1. {"message": "API running."}

複製代碼

如果回 401，權杖錯了或前面少了 Bearer。
如果連不上，檢查 IP 和通訊埠，還有防火牆。

查一個實體的狀態

1. curl -s -X GET \
2.   -H "Authorization: Bearer 你的權杖" \
3.   http://192.168.1.50:8123/api/states/light.客廳 | jq

複製代碼

1. {
2.   "entity_id": "light.客廳",
3.   "state": "on",
4.   "attributes": {
5.     "brightness": 204,
6.     "color_temp_kelvin": 3000,
7.     "friendly_name": "客廳燈"
8.   },
9.   "last_changed": "2026-09-21T08:12:44.123456+00:00"
10. }

複製代碼

中文實體 ID 要做 URL 編碼。用英文 ID 就沒這問題 ——
這也是為什麼我建議實體 ID 一律用英文。

開燈、關燈

1. # 開燈並設亮度
2. curl -s -X POST \
3.   -H "Authorization: Bearer 你的權杖" \
4.   -H "Content-Type: application/json" \
5.   -d '{"entity_id": "light.living_room", "brightness_pct": 40}' \
6.   http://192.168.1.50:8123/api/services/light/turn_on
8. # 關燈
9. curl -s -X POST \
10.   -H "Authorization: Bearer 你的權杖" \
11.   -H "Content-Type: application/json" \
12.   -d '{"entity_id": "light.living_room"}' \
13.   http://192.168.1.50:8123/api/services/light/turn_off

複製代碼

規則很單純：/api/services/<網域>/<服務>，body 放參數。

想知道某個服務有哪些參數？開發者工具 → 動作，
選好之後切到 YAML 模式，看到的就是 body 要放的東西。



觸發自動化或腳本

1. curl -s -X POST \
2.   -H "Authorization: Bearer 你的權杖" \
3.   -H "Content-Type: application/json" \
4.   -d '{"entity_id": "script.睡前模式"}' \
5.   http://192.168.1.50:8123/api/services/script/turn_on

複製代碼

跑一段範本（很好用的除錯工具）

1. curl -s -X POST \
2.   -H "Authorization: Bearer 你的權杖" \
3.   -H "Content-Type: application/json" \
4.   -d '{"template": "{{ states.light | selectattr(\'state\',\'eq\',\'on\') | list | count }}"}' \
5.   http://192.168.1.50:8123/api/template

複製代碼

實際用途舉三個

一：NAS 備份完成後通知

在群暉的排程任務最後加一行：

1. curl -s -X POST -H "Authorization: Bearer $TOKEN" \
2.   -H "Content-Type: application/json" \
3.   -d '{"message":"NAS 備份完成","title":"備份"}' \
4.   http://192.168.1.50:8123/api/services/notify/mobile_app_charles

複製代碼

二：電腦開機時告訴 HA

Windows 排程或 Linux 的 systemd 服務，開機時打一個 API 把
input_boolean.電腦開機中 設成 on。比用 ping 偵測可靠太多。

三：從路由器回報網路狀態

OpenWrt 的 cron 每五分鐘測一次外網，失敗就打 API 更新一個實體。

幾個踩過的坑

1. 用 https 但憑證是自簽的 → curl 要加 -k，或乾脆用內網 http。

2. Content-Type 忘了寫 → HA 會回 400，訊息不太明顯。

3. 反向代理擋掉 → 如果你走 Nginx Proxy Manager 之類的，
要確認它有把 Authorization 標頭傳下去。

4. 權杖過期或被刪 → 全部回 401。去 HA 的個人頁看權杖還在不在。

安全提醒

• 權杖不要寫死在腳本裡，放環境變數或權限 600 的檔案
  
• 每個用途發一個權杖，出事可以只撤銷那一個
  
• 不要為了這個開通訊埠對外。要外部呼叫請走 VPN 或 Nabu Casa
  

---

REST API 還有 WebSocket 版本，可以訂閱事件、即時收狀態變化，
適合寫比較正式的程式。有人想看的話我再寫一篇。