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

charles · 發表於 3 天前

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

第一步：拿一個長期權杖

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

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

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

第二步：確認 API 通不通

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

複製代碼

回傳這樣就對了：

{"message": "API running."}

複製代碼

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

查一個實體的狀態

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

複製代碼

{
"entity_id": "light.客廳",
"state": "on",
"attributes": {
"brightness": 204,
"color_temp_kelvin": 3000,
"friendly_name": "客廳燈"
},
"last_changed": "2026-09-21T08:12:44.123456+00:00"
}

複製代碼

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

開燈、關燈

# 開燈並設亮度
curl -s -X POST \
-H "Authorization: Bearer 你的權杖" \
-H "Content-Type: application/json" \
-d '{"entity_id": "light.living_room", "brightness_pct": 40}' \
http://192.168.1.50:8123/api/services/light/turn_on
# 關燈
curl -s -X POST \
-H "Authorization: Bearer 你的權杖" \
-H "Content-Type: application/json" \
-d '{"entity_id": "light.living_room"}' \
http://192.168.1.50:8123/api/services/light/turn_off

複製代碼

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

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

觸發自動化或腳本

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

複製代碼

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

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

複製代碼

實際用途舉三個

一：NAS 備份完成後通知

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

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"NAS 備份完成","title":"備份"}' \
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 版本，可以訂閱事件、即時收狀態變化，
適合寫比較正式的程式。有人想看的話我再寫一篇。

		自動登入	找回密碼
密碼			立即註冊

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

瀏覽過的版塊