Web 服务器 API

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

请注意，Web 服务器仅用于查看和编辑状态，而不会用于配置节点等操作，因为那样会迅速增加所需的闪存和内存大小。

首先，要使用 Web 服务器，可以通过代码直接调用 App.init_web_server()，或使用 ESPHome 中的 Web Server 章节 启用它。然后，使用节点的 IP 地址或通过 mDNS 使用 <name>.local/ 导航到前端界面。例如，要访问名为 livingroom 的节点的 Web 服务器，你可以在浏览器中输入 livingroom.local/。

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

事件源 API

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

目前，发送的事件有三种类型：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 格式，并在与旧版固件兼容以及 name_id 被移除时回退到 id。id 字段将在 ESPHome 2026.8.0 中切换为新格式（匹配 name_id），届时 name_id 将被移除。在 2026.8.0 之后需要旧版格式的第三方集成必须实现自己的转换逻辑（类似于 aioesphomeapi）。

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

Example payload of the event source API.

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

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

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）

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

要实际控制组件的状态，你需要发送一个带有 method（如 turn_on）的 POST 请求。例如，要打开灯，你可以发送 POST 请求到 /light/Living Room Lights/turn_on。某些组件还可以选择性地接受 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 状态码。

灯

灯支持更多复杂的选项，如亮度或颜色。但首先，要获取灯的状态，发送 GET 请求到 /light/<entity_name>，例如 /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 灯的色温。介于灯的最小和最大麦勒德值之间。仅在灯支持色温时存在。

设置灯的状态可以通过三个 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：设置灯的色温，以麦勒德为单位。

turn_off 可选 URL 参数：

• transition：以秒为单位，在此时间内过渡到关闭。

风扇

风扇类似于开关，可以打开/关闭和切换。此外，如果底层风扇支持，Web 服务器中的风扇还支持速度设置”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：风扇的摆动设置是否开启。仅在风扇支持时发送。

要控制风扇的状态，发送 POST 请求到 /fan/<entity_name>/turn_on、/fan/<entity_name>/turn_off 和 /fan/<entity_name>/toggle。Turn on 额外支持以下可选参数：

• 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 以包含可用选项列表。

For example GET /select/House Mode?detail=all could yield this payload:

{
  "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 服务器接收和处理。

参见

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