【接進 HA】沒有整合的東西怎麼辦：REST、Webhook、命令列的正確用法與三個假成功

charles

這篇的內容（19 段）

1. 步驟 0：先決定要走哪一條
2. JSON 結構比較深的時候
3. 步驟 3：需要認證的 API
4. 一、Bearer token（最常見）
5. 二、網址參數
6. 三、HTTP 基本認證
7. 一次性的動作：`rest_command`
8. 先建立共用的通知腳本
9. 建立 webhook 自動化
10. `local_only: true` 的意思
11. iOS 捷徑的實際操作
12. 那命令列還能做什麼
13. `shell_command` 的三個硬限制
14. 步驟 7：三個完整的實際例子
15. 步驟 8：除錯的固定順序
16. 第一招：先在 HA 外面打一次
17. 第三招：開 REST 的除錯日誌
18. 常見錯誤對照
19. 這篇的驗收

你想接的那個東西在「新增整合」裡找不到。這篇處理這件事。

做完這篇，你會有一顆從真實 API 抓回來的感測器、一條可以被外部程式呼叫的 webhook、一個共用的通知腳本，而且你知道怎麼分辨「它沒在動」跟「它在動但我看錯地方」。

這篇會特別花篇幅在一件事上：這三招都有「設定寫錯了但 HA 不會報錯」的失敗模式。最惡劣的是命令列那一招 —— 它做出來的死實體，跟正常實體在畫面上長得一模一樣。



步驟 0：先決定要走哪一條

三招不是替代關係，是看資料往哪個方向流。

1. 資料方向                      用哪一招            典型例子
2. ------------------------------------------------------------------
3. 對方有網址，HA 去拿           REST                天氣 API、路由器統計頁
4. 對方主動推給 HA               Webhook             IFTTT、iOS 捷徑、你的腳本
5. HA 要送一個指令出去           rest_command        呼叫別人的 API 做一件事
6. HA 要控制一個開關             RESTful switch      有 HTTP API 的繼電器
7. 要在主機上跑指令              （多半不要用）      往下看步驟 6

複製代碼

先排除一件事：在寫任何 YAML 之前，去「設定 → 裝置與服務 → 新增整合」搜尋那個品牌名、以及那個裝置用的晶片名（Tuya、Shelly、Tasmota、ESPHome）。官方整合有一千多個，而且 Ping、DNS、Wake on LAN、系統監控這些「大家以為要自己寫指令」的東西全部都有原生整合。步驟 6 會一個一個對。

---

步驟 1：用一個真的會動的 API 練一次 REST

先用一個不用申請金鑰、現在就能打的 API，確認整條路是通的。這裡用 Open-Meteo 的天氣 API（免費、不用註冊）。

先在瀏覽器打開這個網址（座標是台北市，你可以換成自己的）：

1. https://api.open-meteo.com/v1/forecast?latitude=25.033&longitude=121.565&current=temperature_2m,relative_humidity_2m&timezone=Asia/Taipei

複製代碼

你會看到什麼：瀏覽器顯示一段 JSON，長這樣（2026-09-25 實際打出來的）：

1. {"latitude":25.06,"longitude":121.52,"timezone":"Asia/Taipei",
2. "current_units":{"temperature_2m":"°C","relative_humidity_2m":"%"},
3. "current":{"time":"2026-09-25T13:15","interval":900,
4.             "temperature_2m":32.2,"relative_humidity_2m":59}}

複製代碼

這一步不能跳過。 先在瀏覽器確認網址對、有回東西、結構長什麼樣，再去寫 YAML。否則之後出問題你會分不出是 API 的錯還是 YAML 的錯。

看不到 JSON 只看到錯誤訊息 → 網址打錯，檢查 `&` 有沒有變成別的字元。

接著寫進 configuration.yaml（放在最外層，跟 `homeassistant:` 同一層）：

1. # configuration.yaml
3. rest:
4.   - resource: https://api.open-meteo.com/v1/forecast
5.     scan_interval: 900
6.     params:
7.       latitude: "25.033"
8.       longitude: "121.565"
9.       current: "temperature_2m,relative_humidity_2m"
10.       timezone: "Asia/Taipei"
11.     sensor:
12.       - name: Outdoor temperature
13.         unique_id: openmeteo_outdoor_temp
14.         value_template: "{{ value_json.current.temperature_2m }}"
15.         unit_of_measurement: "°C"
16.         device_class: temperature
17.         state_class: measurement
18.       - name: Outdoor humidity
19.         unique_id: openmeteo_outdoor_humidity
20.         value_template: "{{ value_json.current.relative_humidity_2m }}"
21.         unit_of_measurement: "%"
22.         device_class: humidity
23.         state_class: measurement

複製代碼

存檔後：設定 → 工具 → YAML → 「檢查設定」，再按「全部重新載入」。

（注意路徑：HA 2026.2 把「開發者工具」搬進「設定」底下，2026.8 又改名叫「工具」。舊教學寫的「側邊欄 → 開發者工具」已經不存在。）

你會看到什麼：去「設定 → 工具 → 狀態」，搜尋 `sensor.outdoor_temperature`，應該有一個像 `32.2` 的數值。

對照表：

1. 狀態顯示            意思                        怎麼辦
2. --------------------------------------------------------------------
3. 一個合理的數字      成功                        往下
4. unknown             value_template 取不到值     步驟 8 的第二招
5. unavailable         請求失敗（網址、網路、憑證） 步驟 8 的第一招
6. 整個實體不存在      YAML 沒載入                 檢查縮排，rest: 要在最外層

複製代碼

三個一定要寫的欄位，以及為什麼

• unique_id —— 沒寫的話這顆感測器不能在 UI 裡改名、改圖示、改單位，也不能指派到區域。而且之後你想改名只能改 YAML 的 name，一改名實體 ID 就換掉，所有引用到它的自動化全部斷掉而且不報錯
  
• state_class: measurement —— 沒寫的話這顆不會進長期統計，歷史圖表只留得住 recorder 的十天
  
• scan_interval —— 預設是 30 秒。天氣資料每 30 秒抓一次是沒有意義的，而且免費 API 大多有每日次數上限。900 秒（15 分鐘）一天是 96 次
  

---

步驟 2：一次請求拆成多個感測器（這就是 `rest:` 跟 `platform: rest` 的差別）

上面那份設定只發一次請求就做出兩顆感測器。這是 `rest:` 這個寫法存在的全部理由。

舊教學常見的寫法是這樣：

以下還有約 81% 的內容
登入後即可閱讀完整教學

登入繼續閱讀使用 Google 登入