Web Server API

ESPHome 包含一个内置的 Web Server，可用于查看状态和发送命令。除了 Web Server 根目录下可用的 Web 前端外，Web Server 目前还提供另外两个功能：实时事件源和 REST API。

请注意，Web Server 只是也永远只是用于查看和编辑状态。具体来说，不能用于配置节点，因为这会迅速增加所需的闪存和内存大小。

首先，要使用 Web Server，可以通过代码直接调用 App.init_web_server() 启用，或在 ESPHome 中使用 Web Server 配置部分。然后，通过节点的 IP 或使用 mDNS <name>.local/ 访问前端界面。例如，要访问名为 livingroom 的节点的 Web Server，您可以在浏览器中输入 livingroom.local/。

虽然目前建议直接通过 Home Assistant 使用 ESPHome，但如果您想将 ESPHome 与外部或自建应用程序集成，可以使用两个可用的 API：实时事件源 API 和 REST API。

事件源 API

如果您想接收传感器状态更新的实时更新，建议使用事件源 Web API。使用 URL /events，您可以创建一个 Event Source，通过服务器发送事件接收状态和调试日志的实时更新。事件源在许多语言中易于实现，并且已经有许多可用的库。例如 eventsource for node.js 和 eventsource for python。

目前发送三种类型的事件：ping、state 和 log。第一个事件重复发送以保持连接活跃。每次触发日志消息时都会发送 log 事件，用于在索引页面上显示调试日志。state 是真正发挥作用的地方。此类型的所有事件都有一个描述组件状态的 JSON 负载。每个 JSON 负载都有以下标识字段：

• name_id：临时字段（将在 2026.8.0 中移除），提供新的标识符格式 domain/entity_name（例如 sensor/Temperature），或 domain/device_name/entity_name 用于子设备实体。
• id：使用格式 domain-object_id（例如 sensor-temperature）的旧标识符。为向后兼容而提供。在 2026.8.0 中，此字段将切换到新格式（与 name_id 匹配），name_id 将被移除。

第三方集成必须优先使用 name_id 而非 id 以获取新的 ID 格式，对于较旧固件的兼容性则回退到 id，以及当 name_id 被移除时。在 ESPHome 2026.8.0 中，id 字段将切换到新格式（与 name_id 匹配），届时 name_id 将被移除。需要在 2026.8.0 之后使用旧格式的第三方集成必须实现自己的转换逻辑（类似于 aioesphomeapi）。

state 字段包含底层组件状态的简单文本表示，例如 ON/OFF 或 21.4 °C。某些组件在此负载中还有其他字段，例如灯具有 brightness 属性。

事件源 API 负载示例。

此外，每次客户端连接到事件源时，服务器都会发送所有当前状态，以便客户端可以同步到最新状态。

这些状态事件的负载类似于 REST API GET 调用，不同之处在于 SSE 在弃用期内（直到 2026.8.0）同时包含 name_id 和 id 字段，而 REST 响应仅包含新格式的 id。我建议您直接打开 Web 浏览器的网络调试面板来查看发送的内容。

REST API

还有一个简单的 REST API 可用于获取和设置当前状态。对此 API 的所有调用都遵循 URL 模式 /<domain>/<entity_name>[/<action>?<param>=<value>]。domain 是组件的类型，例如 sensor 或 light。entity_name 是在 YAML 中配置的实体名称（包括空格和 UTF-8 字符）。

对于子设备上的实体，URL 模式为 /<domain>/<device_name>/<entity_name>[/<action>]。

URL 格式和 HTTP 方法

HTTP 方法（GET 或 POST）用于消除 URL 模式的歧义：

段数	GET	POST
2：/{domain}/{entity}	主设备状态	不适用
3：/{domain}/{X}/{Y}	子设备状态（X=设备，Y=实体）	主设备动作（X=实体，Y=动作）
4：/{domain}/{device}/{entity}/{action}	无效	子设备动作

NOTE

4 段 URL 仅支持 POST 请求，因为第四段始终是动作，而动作需要 POST。对 4 段 URL 的 GET 请求将返回错误。

示例：

• /sensor/Temperature - 名为 “Temperature” 的传感器（GET 返回状态）
• /sensor/温度 - 中文名称的传感器（支持 UTF-8）
• /switch/Living Room Light/turn_on - 打开开关（POST）
• /sensor/Garage/Temperature - 名为 “Garage” 的子设备上的传感器（GET 返回状态）
• /light/Garage/Main Light/turn_on - 打开子设备上的灯（POST）

NOTE

向后兼容性

为向后兼容，使用 object_id（带下划线的小写字母）的旧 URL 格式仍受支持但已弃用，将在 ESPHome 2026.7.0 中移除。例如，/sensor/temperature_sensor 仍然可以工作，但会记录弃用警告。建议使用直接使用实体名称的新格式。

通过对 /<domain>/<entity_name> 形式的 URL 创建简单的 GET 请求，您将获得一个描述组件当前状态的 JSON 负载。此负载等同于事件源 API 发送的负载。 您可以通过添加参数 detail=all 来获取有关组件的详细信息。例如 /select/My Select?detail=all。

要实际控制组件的状态，您需要发送带有 turn_on 等 method 的 POST 请求。例如，要打开灯，您需要向 /light/Living Room Lights/turn_on 发送 POST 请求。某些组件还可以选择接受 URL 参数来控制组件的其他方面，例如灯的亮度。

传感器

传感器仅支持 GET 请求，通过向 /sensor/<entity_name> 发送请求。例如，向 /sensor/Outside Temperature 发送 GET 请求可能产生以下负载：

{
  "id": "sensor/Outside Temperature",
  "state": "19.8 °C",
  "value": 19.76666
}

• id：传感器的 ID。格式：sensor/entity_name 或 sensor/device_name/entity_name 用于子设备实体。
• state：传感器的文本状态，以字符串形式表示。
• value：传感器的浮点（过滤后）值。

对于名为 “Garage” 的子设备上的传感器，向 /sensor/Garage/Temperature 发送 GET 请求可能产生：

{
  "id": "sensor/Garage/Temperature",
  "state": "15.2 °C",
  "value": 15.23
}

使用 detail=all 时，响应包含包括设备名称在内的其他字段：

{
  "id": "sensor/Garage/Temperature",
  "name": "Temperature",
  "device": "Garage",
  "state": "15.2 °C",
  "value": 15.23
}

二进制传感器

二进制传感器有类似的负载，也仅支持 GET 请求。例如，使用 URL /binary_sensor/Living Room Status 请求二进制传感器的当前状态可能产生以下负载：

{
  "id": "binary_sensor/Living Room Status",
  "state": "ON",
  "value": true
}

• id：二进制传感器的 ID。格式：binary_sensor/entity_name 或 binary_sensor/device_name/entity_name 用于子设备实体。
• state：二进制传感器的文本状态，以字符串形式表示。
• value：二进制传感器的二进制（true/false）状态。

开关

开关在状态报告方面与二进制传感器具有完全相同的属性，但它们还支持使用 turn_on、turn_off 和 toggle 方法设置状态。

每个方法都很直观。例如，向 /switch/Dehumidifier/turn_on 创建 POST 请求将导致名为 “Dehumidifier” 的组件被打开。如果调用成功，服务器将返回 200 OK HTTP 返回代码。

灯

灯支持更多复杂的选项，如亮度或颜色。但首先，要获取灯的状态，向 /light/<entity_name> 发送 GET 请求，例如 /light/Living Room Lights。

{
  "id": "light/Living Room Lights",
  "state": "ON",
  "brightness": 255,
  "color": {
    "r": 255,
    "g": 255,
    "b": 255
  },
  "effect": "None",
  "white_value": 255
}

• id：灯的 ID。格式：light/entity_name 或 light/device_name/entity_name 用于子设备实体。

• state：灯的文本状态，以字符串形式表示。

• brightness：灯的亮度，从 0 到 255。仅当灯支持亮度时。如果 state 为 OFF，此字段仍可能报告 255 等值以发送完整状态。

• color：此灯的颜色，仅当支持颜色时。

  • r：此灯的红色通道。从 0 到 255。
  • g：此灯的绿色通道。从 0 到 255。
  • b：此灯的蓝色通道。从 0 到 255。

• effect：当前活动的效果，仅当灯支持效果时。

• white_value：RGBW 灯的白值。从 0 到 255。仅当灯支持白值时。

• color_temp：RGBWW 灯的色温。在灯的最小和最大 mireds 之间。仅当灯支持色温时。

可以通过三种 POST 方法调用来设置灯状态：turn_on、turn_off 和 toggle。打开和关闭还有其他可用于设置属性的 URL 编码参数。例如，在 /light/Living Room Lights/turn_on?brightness=128&transition=2 创建 POST 请求将创建一个持续 2 秒的过渡到亮度 128，同时保留灯的颜色。

turn_on 可选 URL 参数：

• brightness：灯的亮度，从 0 到 255。
• r：灯的红色通道，从 0 到 255。
• g：灯的绿色通道，从 0 到 255。
• b：灯的蓝色通道，从 0 到 255。
• white_value：RGBW 灯的白色通道，从 0 到 255。
• flash：以秒为单位的持续时间闪烁由其他属性提供的颜色。
• transition：在以秒为单位的持续时间内过渡到指定的颜色值。
• effect：为灯设置效果。
• color_temp：设置灯的色温，单位为 mireds。

turn_off 可选 URL 参数：

• transition：在以秒为单位的持续时间内过渡到关闭。

风扇

风扇类似于开关，因为它们可以打开/关闭和切换。此外，如果底层风扇支持，Web Server 中的风扇还支持速度设置 “low”、“medium” 和 “high” 以及摆动设置。要获取风扇的当前状态，向 /fan/<entity_name> 创建 GET 请求。

{
  "id": "fan/Living Room Fan",
  "state": "ON",
  "value": true,
  "speed_level": 2,
  "oscillation": false
}

• id：风扇的 ID。格式：fan/entity_name 或 fan/device_name/entity_name 用于子设备实体。
• state：风扇的文本状态，以字符串形式表示。
• value：风扇的二进制（true/false）状态。
• speed_level：风扇的速度级别（如果支持）。值在 1 和风扇支持的最大值之间。
• oscillation：风扇的摆动设置是否开启。仅在风扇支持时发送。

要控制风扇的状态，向 /fan/<entity_name>/turn_on、/fan/<entity_name>/turn_off 和 /fan/<entity_name>/toggle 发送 POST 请求。打开还支持以下可选参数：

• speed_level：风扇的新速度级别。值同上。
• oscillation：风扇的新摆动设置。值同上。

遮盖

遮盖再次类似于开关，其两种可能的状态是 OPEN 和 CLOSED。然而，它们可以处于中间位置，在 0.0（完全关闭）到 1.0（完全打开）之间的任何位置。它们通常需要一些时间从一个位置移动到另一个位置，也可以在中途停止。例如，对 /cover/Front Window Blinds 的 GET 请求可能返回：

{
  "id": "cover/Front Window Blinds",
  "state": "OPEN",
  "value": 0.8,
  "current_operation": "IDLE",
  "tilt": 0.5
}

• id：遮盖的 ID。格式：cover/entity_name 或 cover/device_name/entity_name 用于子设备实体。

• state：OPEN 或 CLOSED。除 0.0 以外的任何位置都被视为打开。

• value：当前遮盖位置，以浮点数表示。如果遮盖组件不支持遮盖位置报告，则打开时为 1.0，关闭时为 0.0。

• current_operation：OPENING、CLOSING 或 IDLE。

• tilt：（仅当此遮盖组件支持时）倾斜角度，从 0.0 到 1.0。

• position：（仅当此遮盖组件支持时）当前遮盖位置，以浮点数表示。

另一方面，POST 请求允许对遮盖执行操作，可用的方法有 open、close、stop、toggle 和 set。可以使用以下参数：

• position：set 调用的目标位置。open 方法意味着目标位置为 1.0，close 意味着目标位置为 0.0。

• tilt：要设置的倾斜角度（如果支持）。

向 /cover/Front Window Blinds/set?position=0.1&tilt=0.3 创建 POST 请求将开始将百叶窗移动到几乎完全关闭的位置和新的倾斜角度。

选择器

选择器可以设置为某个选项，并将返回其当前选项。例如，向 /select/House Mode 发送 GET 请求可能产生以下负载：

{
  "id": "select/House Mode",
  "state": "party",
  "value": "party"
}

可以使用 detail 参数在响应中包含可用选项：

• detail：设置为 all 以包含可用选项列表。

例如 GET /select/House Mode?detail=all 可能产生以下负载：

{
  "id": "select/House Mode",
  "name": "House Mode",
  "state": "party",
  "value": "party",
  "option": ["party","sleep","relax","home","away"]
}

另一方面，POST 请求允许设置选择器，可用的方法是 set。可以使用以下参数：

• option：要设置的字符串选项。必须是有效选项。

例如 POST /select/House Mode/set?option=guest 将把选择器设置为 guest。

按钮

可以通过向 /button/Do Something/press 发送 POST 请求从 REST API 按下 按钮。

数值

数值可以设置为其最小和最大范围内的某个值，并将返回其当前值。例如，向 /number/Desired Delay 发送 GET 请求可能产生以下负载：

{
  "id": "number/Desired Delay",
  "state": "20.0000",
  "value": 20
}

另一方面，POST 请求允许设置数值，可用的方法是 set。可以使用以下参数：

• value：您想要设置的数值。该值必须在数值的最小和最大范围内，否则将被忽略。

例如 POST /number/Desired Delay/set?value=24 将把数值设置为 24。

报警控制面板

可以通过向 /alarm_control_panel/My Alarm 发送 GET 请求来检索报警控制面板的当前状态，可能产生：

{
  "id": "alarm_control_panel/My Alarm",
  "state": "ARMED_AWAY",
  "value": 2
}

• id：报警控制面板的 ID。格式：alarm_control_panel/entity_name 或 alarm_control_panel/device_name/entity_name 用于子设备实体。

• state：DISARMED、ARMED_HOME、ARMED_AWAY、ARMED_NIGHT、ARMED_VACATION、ARMED_CUSTOM_BYPASS、PENDING、ARMING、DISARMING 或 TRIGGERED。

• value：当前状态，以数字表示。参见 AlarmControlPanelState 枚举。

POST 请求允许布防和撤防报警控制面板。可用的方法有 arm_away、arm_home、arm_night、arm_vacation 和 disarm。如果报警控制面板需要代码才能撤防或布防，可以提供 code 参数。在构建请求时，请将此 code 作为 POST 数据的一部分（或客户端支持的其他非 URL 通道）包含在内，避免将其直接放在 URL 查询字符串中，因为 URL 可能会被记录或存储在浏览器历史记录中。

有效的 POST 请求将始终返回 200 OK 状态响应。这并不表示报警已成功布防或撤防。它仅表示命令已被 Web Server 接收和处理。

另请参阅

• Web Server 组件
• Prometheus 组件
• HTTP 请求