用 iOS 捷徑呼叫 HA 的 API：五個實際範例

charles

「家庭」App 能做的事有限。
iOS 的捷徑（Shortcuts）配上 HA 的 API，彈性大很多。

這篇給五個我天天在用的。



三種呼叫方式，先選一個

方式一：HA 官方 App 的捷徑動作（最簡單）

裝了 Home Assistant Companion App 之後，
捷徑裡會多出 「Call Service」 和 「Render Template」 等動作。

• 優點：不用處理權杖和網址，App 已經知道了
  
• 缺點：功能比直接打 API 少一些
  

方式二：Webhook（不用權杖）

前面有一篇專門講。捷徑裡用「取得 URL 內容」POST 到 webhook。

• 優點：最簡單，不用管權杖
  
• 缺點：只能觸發，不能查資料。而且 webhook_id 就是密碼
  

方式三：REST API + 長期權杖（最彈性）

• 優點：能查能寫，什麼都做得到
  
• 缺點：要保管權杖
  

權杖怎麼存比較安全：
在捷徑裡用「文字」動作存權杖，然後把那個捷徑設成
「不在共享表單中顯示」，並且不要分享那個捷徑給別人。

（iOS 沒有真正安全的捷徑機密存放機制，所以權杖建議只給有限權限的用途。）

範例一：一鍵睡前模式（放在主畫面）

用官方 App 的動作：

1. 1. 動作：Call Service
2.    服務：script.turn_on
3.    實體：script.睡前模式
5. 2. 動作：顯示通知
6.    「晚安，已關燈鎖門」

複製代碼

用 API 的話：

1. 1. 文字 → https://ha.example.com/api/services/script/turn_on
2. 2. 字典 →
3.    entity_id : script.bedtime
4. 3. 取得 URL 內容
5.    URL：（上面的文字）
6.    方法：POST
7.    標頭：
8.      Authorization : Bearer <你的權杖>
9.      Content-Type  : application/json
10.    要求內容：JSON（上面的字典）

複製代碼

加到主畫面：捷徑詳細資料 → 加入主畫面。
變成一個圖示，點一下就執行。

範例二：問「現在家裡怎麼樣」（會講話的）

這個用 Siri 叫最順。

1. 1. 取得 URL 內容
2.    URL：https://ha.example.com/api/template
3.    方法：POST
4.    標頭：Authorization / Content-Type
5.    要求內容（JSON）：
6.    {
7.      "template": "客廳 {{ states('sensor.living_room_temperature') }} 度，濕度 {{ states('sensor.living_room_humidity') }}%。{% set n = states.light | selectattr('state','eq','on') | list | count %}{% if n > 0 %}有 {{ n }} 盞燈開著。{% else %}燈都關著。{% endif %}"
8.    }
10. 2. 動作：說出文字
11.    （上一步的結果）

複製代碼

捷徑命名為「家裡狀況」，
然後對 Siri 說「嘿 Siri，家裡狀況」。

這個比打開 App 快太多了。



範例三：用 iOS 自動化觸發 HA（這個很強）

iOS 的「自動化」可以偵測很多 HA 看不到的事件：

• 連上 / 離開某個 Wi-Fi
  
• 連上 CarPlay 或藍牙
  
• 打開某個 App
  
• 設定的鬧鐘響了 / 關掉了
  
• 睡眠模式開始 / 結束
  
• 電量低於某個百分比
  
• 到達 / 離開某個地點
  

最實用的組合：鬧鐘關掉 → 告訴 HA 你起床了

1. iOS 自動化：
2.   觸發：鬧鐘 → 停止鬧鐘
3.   動作：取得 URL 內容 → POST 到 HA 的 webhook
5. HA 這邊：
6.   webhook 觸發 → 開燈、煮咖啡、播新聞

複製代碼

為什麼這個好：HA 不知道你的鬧鐘什麼時候響，
也不知道你有沒有按掉。這個資訊只有手機知道。

第二個：連上 CarPlay → 開車庫門

1. iOS 自動化：
2.   觸發：CarPlay → 已連接
3.   動作：POST 到 HA webhook
5. HA：
6.   條件：距離家裡 500 公尺內
7.   動作：開車庫門

複製代碼

一定要加距離條件，不然你在公司上車也會開家裡的門。

第三個：睡眠模式 → 切換家的狀態

iOS 的睡眠專注模式開始時，通知 HA 切到「睡覺」狀態。

這比「晚上 11 點自動切」準確太多，因為它跟著你的實際作息。

範例四：在鎖定畫面顯示家裡的資訊

捷徑可以做成小工具（Widget）：

1. 1. 取得 URL 內容（查詢溫度）
2. 2. 從輸入取得詞典值 → state
3. 3. 顯示結果

複製代碼

然後在主畫面長按 → 加入小工具 → 捷徑。

不過老實說：HA 官方 App 已經有原生的小工具了，
而且效能更好。捷徑做的小工具會比較慢。

範例五：離家檢查清單

出門前跑一次，把該檢查的一次問完。

1. 1. 取得 URL 內容 → /api/template
2.    {
3.      "template": "{% set problems = [] %}{% if states.light | selectattr('state','eq','on') | list | count > 0 %}{% set problems = problems + ['有燈沒關'] %}{% endif %}{% if is_state('lock.front_door','unlocked') %}{% set problems = problems + ['門沒鎖'] %}{% endif %}{% if is_state('climate.living_room','cool') %}{% set problems = problems + ['冷氣開著'] %}{% endif %}{% if problems | count == 0 %}都好了，可以出門{% else %}{{ problems | join('、') }}{% endif %}"
4.    }
6. 2. 如果（結果包含「都好了」）
7.      說出文字：「都好了」
8.    否則
9.      詢問：「{結果}。要幫你處理嗎？」
10.      如果選「是」→ Call Service: script.turn_on / script.離家

複製代碼

這個我每天都在用。



實用技巧

技巧一：內網和外網用不同網址

在捷徑開頭加一個判斷：

1. 1. 取得網路詳細資訊 → 目前的網路（Wi-Fi 名稱）
2. 2. 如果（等於「你家的 SSID」）
3.      文字：http://192.168.1.50:8123
4.    否則
5.      文字：https://ha.example.com
6. 3. 之後的 URL 都用這個變數 + 路徑

複製代碼

在家用內網 IP 會快很多，而且不依賴外部連線。

技巧二：加錯誤處理

捷徑預設出錯就跳一個醜醜的錯誤。

用「如果」判斷回傳內容，或者在「取得 URL 內容」
後面接一個「如果沒有值就顯示自訂訊息」。

技巧三：用「選單」做多功能捷徑

不要做二十個捷徑。做一個「家」，裡面用選單分：

1. 從選單中選擇
2.   - 睡前模式
3.   - 離家檢查
4.   - 家裡狀況
5.   - 看電影
6.   - 全部開燈

複製代碼

主畫面只放一個圖示，但能做五件事。

技巧四：Apple Watch 上也能用

捷徑會同步到 Watch。
手錶上點一下開燈，比掏手機快。

技巧五：NFC 標籤

iOS 自動化可以用 NFC 標籤觸發。

• 床頭貼一張 → 睡前模式
  
• 玄關貼一張 → 離家模式
  
• 書桌貼一張 → 工作模式
  

NFC 標籤很便宜（一張幾十塊），
而且HA 本身就有 NFC 標籤功能（設定 → 標籤），
可以直接寫入 HA 的標籤 ID，用 HA 的自動化接。

安全提醒

• 不要在捷徑裡放能開門鎖的權杖，除非你的手機有嚴格的鎖定
  
• 危險動作用 HA 的可操作通知 + authenticationRequired 做二次確認
  
• 分享捷徑給別人之前，確認裡面沒有權杖或 webhook id
  
• 權杖每個用途發一個，出事可以單獨撤銷
  

---

我自己主畫面上只有兩個捷徑：「家」（選單式）和「出門」。

其他的都靠 iOS 自動化在背景跑，完全不用手動。

最好的捷徑是你根本不用點的那種。