Экосистема Home Assistant давно вышла за рамки простого управления освещением через локальный интерфейс. Для многих энтузиастов и разработчиков настоящим открытием становится возможность программного взаимодействия с системой. REST API (Representational State Transfer) предоставляет мощный инструмент для интеграции вашего умного дома с внешними сервисами, собственными скриптами или мобильными приложениями. Понимание принципов работы этого интерфейса открывает безграничные возможности автоматизации.
Многие пользователи ограничиваются стандартными карточками и автоматизациями внутри системы, не догадываясь, что любой датчик или выключатель может стать частью сложной внешней логики. Например, вы можете отправлять данные о температуре на собственный сервер или управлять климатом в зависимости от расписания в корпоративной системе учета. REST API выступает в роли универсального переводчика, превращая внутренние события Home Assistant в понятные HTTP-запросы.
В этой статье мы детально разберем процесс настройки доступа, методы аутентификации и основные сценарии использования api/states и api/services. Вы узнаете, как безопасно организовать обмен данными и какие подводные камни могут встретиться при работе с токенами. Это руководство поможет вам превратить вашу систему автоматизации в полноценный хаб для любых IoT-устройств.
Подготовка системы и включение API
По умолчанию, интерфейс API в Home Assistant уже активен, однако для корректной работы извне или из сторонних скриптов необходимо убедиться в правильности конфигурации сети. Доступ к API осуществляется через порт 8123, который должен быть открыт в брандмауэре, если вы планируете обращаться к системе не только с локального устройства. Проверьте файл configuration.yaml, где секция http: должна содержать корректные настройки IP-адресов.
Если ваш сервер находится за NAT или вы используете Docker-контейнер, убедитесь, что порт проброшен на хост-машину. Безопасность здесь играет первостепенную роль: никогда не открывайте порт 8123 напрямую в интернет без использования VPN или надежного прокси-сервера вроде Nginx Proxy Manager. Локальный доступ по IP-адресу вида http://192.168.1.X:8123 является базовым требованием для начала работы.
Для проверки доступности API можно использовать простой браузерный запрос. Перейдите по адресу http://IP-АДРЕС:8123/api/. Если система отвечает JSON-объектом с сообщением "API running", значит, сетевая часть настроена верно. В противном случае, проверьте логи сервера на предмет ошибок привязки сокетов.
⚠️ Внимание: Прямой доступ к порту 8123 из внешней сети без шифрования (HTTPS) и дополнительной авторизации подвергает вашу домашнюю сеть серьезному риску взлома. Используйте туннелирование или облачные решения для удаленного доступа.
Аутентификация и создание токенов доступа
Самый важный этап настройки — получение ключа доступа. Home Assistant использует систему долгосрочных токенов (Long-Lived Access Tokens), которые не истекают, пока вы их явно не отзовете. Это предпочтительный метод для серверных приложений и скриптов, так как он не требует взаимодействия с пользователем при каждом запросе. Пароли от аккаунта передавать в заголовках запросов небезопасно и не рекомендуется.
Для генерации токена войдите в веб-интерфейс под своей учетной записью. Перейдите в профиль пользователя, нажав на имя в нижнем левом углу, и выберите вкладку Безопасность. В разделе "Долгосрочные токены доступа" нажмите кнопку "Создать токен". Придумайте понятное имя, например, Python Script или Server Monitor, чтобы в будущем знать, какое приложение использует этот ключ.
Скопируйте сгенерированную строку сразу после создания. Система покажет его только один раз, и восстановить утерянный токен без создания нового будет невозможно. Этот ключ необходимо передавать в заголовке HTTP-запроса Authorization в формате Bearer ВАШ_ТОКЕН. Храните токен в защищенном месте, например, в переменных окружения или защищенных файлах конфигурации.
Пример правильного заголовка для curl-запроса выглядит следующим образом:
curl -X GET \
http://localhost:8123/api/states \
-H "Authorization: Bearer YOUR_LONG_LIVED_TOKEN" \
-H "Content-Type: application/json"
Получение состояния объектов (GET запросы)
Основная функция API для чтения данных — это получение состояния сущностей (entities). Каждая лампочка, датчик движения или медиаплеер в Home Assistant имеет свой уникальный ID и текущее состояние. Запрос к эндпоинту /api/states возвращает полный список всех объектов системы в формате JSON. Это может быть полезно для создания дашбордов или резервного копирования конфигурации состояний.
Однако загружать весь массив данных каждый раз неэффективно. Гораздо чаще требуется получить состояние конкретного устройства. Для этого используется адрес вида /api/states/entity_id. Например, чтобы узнать, включен ли свет в гостиной, вы обращаетесь к light.living_room. Ответ сервера будет содержать не только статус on или off, но и все атрибуты: яркость, цветовую температуру, время последнего обновления.
Разберем структуру ответа. JSON-объект содержит поля entity_id, state и attributes. В атрибутах может храниться дополнительная информация, такая как уровень заряда батареи для датчиков или название трека для музыкальных плееров. Обработка этих данных в вашем коде позволяет принимать интеллектуальные решения.
| Entity ID | State | Атрибуты (пример) | Тип устройства |
|---|---|---|---|
| sensor.living_room_temp | 22.5 | unit_of_measurement: °C | Датчик температуры |
| light.kitchen_led | on | brightness: 200, rgb_color: [255, 100, 0] | Умная лента |
| binary_sensor.door_front | off | device_class: door | Датчик открытия |
| media_player.lg_tv | playing | volume_level: 0.4, media_title: News | Телевизор |
Фильтрация данных на стороне сервера
Вы можете использовать параметры query string для фильтрации, но стандартный API возвращает все данные, поэтому фильтрацию лучше выполнять на стороне клиента (в вашем скрипте) для снижения нагрузки.
Управление устройствами через вызов сервисов
Чтение данных — это только половина дела. Гораздо интереснее возможность управлять устройствами программно. Для этого в Home Assistant REST API предусмотрен эндпоинт /api/services. Вызов сервиса требует указания домена (например, light), названия действия (например, turn_on) и целевого объекта. Это аналог нажатия кнопки в интерфейсе, но выполняемый внешним скриптом.
Запрос должен быть выполнен методом POST. В теле запроса (body) необходимо передать JSON с параметрами действия. Самым важным параметром обычно является entity_id, указывающий, к какому устройству применяется команда. Если вы хотите включить свет во всей комнате, можно передать список ID или использовать псевдо-сущность all, если сервис это поддерживает.
Рассмотрим пример включения лампы с конкретной яркостью. Вам нужно отправить запрос на /api/services/light/turn_on. В теле запроса укажите entity_id и параметр brightness. Система моментально выполнит команду и вернет ответ. Обратите внимание, что некоторые сложные сервисы могут требовать дополнительных параметров, специфичных для интеграции устройства.
curl -X POST \
http://localhost:8123/api/services/light/turn_on \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"entity_id": "light.bedroom", "brightness": 128}'
⚠️ Внимание: Некоторые сервисы выполняются асинхронно. Это значит, что API вернет ответ об успехе принятия команды сразу, но физическое устройство может отреагировать с задержкой в несколько секунд.
События и вебхуки для внешней интеграции
Одним из самых мощных инструментов для интеграции являются вебхуки (Webhooks). Они позволяют внешним системам отправлять данные в Home Assistant без необходимости постоянной авторизации через токен в каждом запросе. Вебхук создает уникальный URL, при обращении к которому в системе генерируется событие homeassistant_webhook. Это событие можно использовать в автоматизациях.
Чтобы создать вебхук, добавьте в configuration.yaml соответствующую секцию. Укажите уникальный идентификатор webhook_id. После перезагрузки системы вы получите URL вида /api/webhook/ВАШ_ID. Любой, кто знает этот URL, может отправить POST-запрос с данными, и система отреагирует согласно настроенной автоматизации. Это идеально подходит для интеграции с IFTTT, Zapier или платежными шлюзами.
- 🔥 Уведомления: Отправка данных о пожаре или протечке с внешнего датчика, не поддерживающего Home Assistant напрямую.
- 💰 Оплата: Триггер на включение кофеварки после успешной оплаты через платежную систему.
- 📍 Геолокация: Обновление зоны присутствия при въезде автомобиля на территорию предприятия через корпоративный шлагбаум.
☑️ Настройка вебхука
Данные, переданные в теле вебхук-запроса, становятся доступны в автоматизации через переменную trigger.json. Вы можете извлекать конкретные поля и использовать их для динамического изменения параметров устройств. Это делает вебхуки универсальным мостом между миром Home Assistant и любыми другими веб-сервисами.
Обработка ошибок и отладка запросов
При работе с API неизбежно возникнут ситуации, когда запрос не выполняется. Понимание кодов состояния HTTP поможет быстро диагностировать проблему. Код 401 Unauthorized почти всегда означает неверный токен или его отсутствие в заголовке. Код 404 Not Found говорит о том, что указанный entity_id не существует в системе или путь к сервису введен с ошибкой.
Код 400 Bad Request указывает на ошибку в формате передаваемых данных. Чаще всего это невалидный JSON или отсутствие обязательных полей в теле запроса. Для отладки удобно использовать инструменты вроде Postman или консольную утилиту curl с флагом -v (verbose), который показывает подробный обмен заголовками между клиентом и сервером.
Логи самого Home Assistant также содержат ценную информацию. Включите режим отладки для компонента http или api, чтобы видеть входящие запросы и ответы сервера в реальном времени. Это поможет понять, доходит ли запрос до ядра системы и как оно его интерпретирует.
Можно ли использовать API без токена?
Технически, некоторые публичные эндпоинты (например, карта или состояние без атрибутов) могут быть доступны без авторизации, если это явно разрешено в настройках. Однако для любых действий управления (вызов сервисов) токен обязателен. Работать без токена небезопасно и не рекомендуется.
Как обновить токен, если я его потерял?
Токены нельзя восстановить. Вам необходимо зайти в профиль пользователя в интерфейсе Home Assistant, найти список долгосрочных токенов, удалить старый (если он там есть) и сгенерировать новый. После этого обновите новый ключ во всех ваших скриптах и приложениях.
Поддерживает ли API отправку изображений с камер?
Да, вы можете получить снимок с камеры через эндпоинт /api/camera_proxy/camera.entity_id. Ответом будет бинарный поток изображения (image/jpeg или image/png), который можно сохранить в файл или отобразить в интерфейсе.
Есть ли ограничение на количество запросов в секунду?
Да, существует встроенный механизм защиты от перегрузки (Rate Limiting). Если вы будете отправлять сотни запросов в секунду, API временно заблокирует ваш IP-адрес. Для обычных сценариев автоматизации эти лимиты практически недостижимы.