首页 ▸ Integrations ▸

HTTP

http 集成提供了 Home Assistant 前端所需的所有文件和数据。只有当您想更改任何默认设置时，才需要将其添加到您的配置文件中。

目前，Home Assistant 支持以下设备类型：

二进制传感器
传感器

Warning

选项 server_host 仅应在 Home Assistant Core 安装中使用！

# 示例 configuration.yaml 条目
http:

Configuration Variables

Looking for your configuration file?

server_host list | string (Optional, default: 0.0.0.0, ::)

仅监听特定 IP/主机上的传入请求。默认情况下，http 集成会自动检测 IPv4/IPv6 并监听所有连接。如果您只想监听 IPv4 地址，请使用 server_host: 0.0.0.0。默认值假定支持 IPv4 和 IPv6。

server_port integer (Optional, default: 8123)

设置要使用的端口。

ssl_certificate string (Optional)

提供您的 TLS/SSL 证书路径，以通过安全连接为 Home Assistant 提供服务。如果使用 Let’s Encrypt 插件，路径为 /ssl/fullchain.pem。我们建议使用 NGINX 插件而不是使用此选项。

ssl_peer_certificate string (Optional)

接受安全连接的客户端/对等 TLS/SSL 证书路径。

ssl_key string (Optional)

提供您的 TLS/SSL 密钥路径，以通过安全连接为 Home Assistant 提供服务。如果使用 Let’s Encrypt 插件，路径为 /ssl/privkey.pem。

cors_allowed_origins string | list (Optional)

允许 CORS 请求的来源域名列表。启用此选项将设置 Access-Control-Allow-Origin 头为 Origin 头（如果在列表中找到），并将 Access-Control-Allow-Headers 头设置为 Origin, Accept, X-Requested-With, Content-type, Authorization。您必须提供确切的 Origin，例如，https://www.home-assistant.io 将允许来自 https://www.home-assistant.io 的请求，但不允许 http://www.home-assistant.io。

use_x_forwarded_for boolean (Optional, default: false)

启用解析 X-Forwarded-For 头，在代理设置中传递客户端的正确 IP 地址。您必须使用 trusted_proxies 设置将受信任的代理列入白名单才能使其工作。未列入白名单的请求将被视为 IP 欺骗攻击，因此将忽略该头。

use_x_frame_options boolean (Optional, default: true)

控制 X-Frame-Options 头，以帮助防止点击劫持。

trusted_proxies string | list (Optional)

受信任代理的列表，包括 IP 地址或网络，允许设置 X-Forwarded-For 头。这在使用 use_x_forwarded_for 时是必需的，因为所有请求，无论来源如何，都将来自反向代理 IP 地址。因此，在反向代理场景中，应极其谨慎地设置此选项。如果直接上游代理不在列表中，请求将被拒绝。如果任何其他中间代理不在列表中，第一个不受信任的代理将被视为客户端。

ip_ban_enabled boolean (Optional, default: true)

指示是否启用额外的 IP 过滤的标志。

login_attempts_threshold integer (Optional, default: -1)

单个 IP 的失败登录尝试次数，超过此次数后将自动被禁止（如果 ip_ban_enabled 为 true）。设置为 -1 时，不会添加新的自动禁令。

ssl_profile string (Optional, default: modern)

要使用的 Mozilla SSL 配置文件。仅在遇到导致 SSL 握手错误的集成时降低此值。

以下示例显示了 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中的配置条目及可能的值：

# 示例 configuration.yaml 条目
http:
  server_port: 12345
  ssl_certificate: /etc/letsencrypt/live/hass.example.com/fullchain.pem
  ssl_key: /etc/letsencrypt/live/hass.example.com/privkey.pem
  cors_allowed_origins:
    - https://google.com
    - https://www.home-assistant.io
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.0.0.200
    - 172.30.33.0/24
  ip_ban_enabled: true
  login_attempts_threshold: 5

使用 Let’s Encrypt 设置加密博客文章为您提供了有关使用 Let’s Encrypt 免费证书加密流量的详细信息。

反向代理

使用反向代理时，您需要启用 use_x_forwarded_for 和 trusted_proxies 选项。如果未设置这些选项，来自反向代理的请求将被阻止。

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.0.0.200      # 添加代理服务器的 IP 地址
    - 172.30.33.0/24  # 您也可以提供子网掩码

APIs

在 http 集成之上，有一个 REST API、Python API 和 WebSocket API 可用。

http 平台在 Home Assistant 术语中并不是真正的平台。Home Assistant 的 REST API 通过 HTTP 发送和接收消息。

HTTP 传感器

在您的安装中使用这些类型的传感器或二进制传感器不需要在 Home Assistant 中进行配置。所有配置都在设备本身上完成。这意味着您必须能够编辑目标 URL 或端点和有效负载。实体将在收到第一条消息后创建。

如果您想使用 HTTP 传感器，请在 Home Assistant UI 的安全部分中创建一个长期访问令牌在您的 用户配置文件 页面。

所有请求需要发送到设备的端点，并且必须是 POST。

IP 过滤和禁止

如果您想应用额外的 IP 过滤，并自动禁止暴力破解尝试，请将 ip_ban_enabled 设置为 true 并设置最大尝试次数。在第一次禁止后，将在根配置文件夹中创建一个 ip_bans.yaml 文件。它将包含被禁止的 IP 地址和添加时的 UTC 时间：

127.0.0.1:
  banned_at: "2016-11-16T19:20:03"

添加禁止后，将向 Home Assistant 前端发送一个持久通知。

托管文件

如果您想使用 Home Assistant 托管或提供静态文件，请在配置路径 (/config) 下创建一个名为 www 的目录。www/ 中的静态文件可以通过以下 URL 访问 http://your.domain:8123/local/，例如 audio.mp3 可以通过 http://your.domain:8123/local/audio.mp3 访问。

Important

如果您是第一次创建 www/ 文件夹，则需要重新启动 Home Assistant。

Caution

从 www 文件夹（/local/ URL）提供的文件不受 Home Assistant 身份验证的保护。如果知道 URL，存储在此文件夹中的文件可以在没有身份验证的情况下被任何人访问。

二进制传感器

HTTP 二进制传感器在第一次请求其 URL 时动态创建。您不必先在配置中定义它。

传感器将在 Home Assistant 运行时存在。重新启动 Home Assistant 后，传感器将消失，直到再次触发。

二进制传感器的 URL 如下所示：

http://IP_ADDRESS:8123/api/states/binary_sensor.DEVICE_NAME

Important

您应选择一个唯一的设备名称（DEVICE_NAME），以避免与其他设备发生冲突。

JSON 有效负载必须包含新状态，并且可以包含友好名称。友好名称在前端用于命名传感器。

{"state": "on", "attributes": {"friendly_name": "Radio"}}

对于快速测试，curl 可以用来“模拟”设备。

$ curl -X POST -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"state": "off", "attributes": {"friendly_name": "Radio"}}' \
    http://localhost:8123/api/states/binary_sensor.radio

要检查传感器是否工作，请再次使用 curl 检索当前状态。

$ curl -X GET -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/states/binary_sensor.radio
{
    "attributes": {
        "friendly_name": "Radio"
    },
    "entity_id": "binary_sensor.radio",
    "last_changed": "16:45:51 05-02-2016",
    "last_updated": "16:45:51 05-02-2016",
    "state": "off"
}

要删除传感器，请使用 curl 发送 DELETE 请求

$ curl -X DELETE -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
       http://localhost:8123/api/states/binary_sensor.radio

示例

在本节中，您将找到一些如何使用此传感器的实际示例，除了前面显示的 curl。

使用 Python request 模块

如 API 页面所示，使用 Python 和 Requests 模块与 Home Assistant 进行交互非常简单。

response = requests.post(
    "http://localhost:8123/api/states/binary_sensor.radio",
    headers={
        "Authorization": "Bearer LONG_LIVED_ACCESS_TOKEN",
        "content-type": "application/json",
    },
    data=json.dumps({"state": "on", "attributes": {"friendly_name": "Radio"}}),
)
print(response.text)

使用 httpie

httpie 是一个用户友好的 CLI HTTP 客户端。

$ http -v POST http://localhost:8123/api/states/binary_sensor.radio \
      'Authorization:Bearer LONG_LIVED_ACCESS_TOKEN' content-type:application/json state=off \
      attributes:='{"friendly_name": "Radio"}'

传感器

HTTP 传感器在第一次请求其 URL 时动态创建。您不必先在配置中定义它。

传感器将在 Home Assistant 运行时存在。重新启动 Home Assistant 后，传感器将消失，直到再次触发。

传感器的 URL 如下所示：

http://IP_ADDRESS:8123/api/states/sensor.DEVICE_NAME

Important

您应选择一个唯一的设备名称（DEVICE_NAME），以避免与其他设备发生冲突。

JSON 有效负载必须包含新状态，并且应包括测量单位和友好名称。友好名称在前端用于命名传感器。

{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Bathroom Temperature"}}

对于快速测试，curl 可以用来“模拟”设备。

$ curl -X POST -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Bathroom Temp"}}' \
       http://localhost:8123/api/states/sensor.bathroom_temperature

然后，您可以再次使用 curl 检索当前传感器状态并验证传感器是否正常工作。

$ curl -X GET -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/states/sensor.bathroom_temperature
{
    "attributes": {
        "friendly_name": "Bathroom Temp",
        "unit_of_measurement": "\u00b0C"
    },
    "entity_id": "sensor.bathroom_temperature",
    "last_changed": "09:46:17 06-02-2016",
    "last_updated": "09:48:46 06-02-2016",
    "state": "20"
}

有关更多示例，请访问 HTTP 二进制传感器页面。

帮助我们改进翻译

建议编辑此页面，或提供/查看此页面的反馈。

编辑提供反馈查看待处理的反馈