2025.3.4
首页 ▸ Integrations ▸

RESTful 二进制传感器

rest 二进制传感器平台使用由设备、应用程序或网络服务的 RESTful API 公开的特定端点。该二进制传感器支持 GET 和 POST 请求。

提示： 如果您想使用相同的端点创建多个 sensors，请使用 RESTful 配置说明。

如果端点返回以下值之一的配对：0/1、"0"/"1"、FALSE/TRUE、false/true、off/on 或 closed/open，可以按原样使用。 如果返回值不同，请使用 模板。 如果端点返回带有 text/xml、application/xml 或 application/xhtml+xml 内容类型的 XML，它将根据此 规范 自动转换为 JSON。

{
    "name": "Binary sensor",
    "state": {
        "open": "true",
        "timestamp": "2016-06-20 15:42:52.926733"
    }
}

配置

要启用此传感器，请为 GET 请求将以下行添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中：

# 示例 configuration.yaml 条目
binary_sensor:
  - platform: rest
    resource: http://IP_ADDRESS/ENDPOINT

或进行 POST 请求：

# 示例 configuration.yaml 条目
binary_sensor:
  - platform: rest
    resource: http://IP_ADDRESS/ENDPOINT
    method: POST

或基于模板的请求：

# 示例 configuration.yaml 条目
binary_sensor:
  - platform: rest
    resource_template: "http://IP_ADDRESS/{{ now().strftime('%Y-%m-%d') }}"

Configuration Variables

Looking for your configuration file?
resource string Required, default: string

包含值的资源或端点。

resource_template template (Optional)

包含值的资源或端点，支持模板。

method string (Optional, default: GET)

请求的方法。

name template (Optional, default: REST Binary Sensor)

REST 二进制传感器的名称。

icon template (Optional)

定义实体图标的模板。

picture template (Optional)

定义实体图片的模板。

availability template (Optional)

定义实体状态是否可用的模板。

device_class string (Optional)

设置设备的 类别，更改在前端显示的设备状态和图标。

value_template template (Optional)

定义一个 模板 以提取值。

payload string (Optional)

发送 POST 请求的有效载荷。通常作为字典形式。

unique_id string (Optional)

唯一标识该实体的 ID。这允许从 Web 界面更改 name、icon 和 entity_id。

verify_ssl boolean (Optional, default: true)

验证端点的认证。

timeout integer (Optional, default: 10)

定义等待端点数据的最大时间。

authentication string (Optional)

HTTP 认证的类型。basic 或 digest。

username string (Optional)

访问 REST 端点的用户名。

password string (Optional)

访问 REST 端点的密码。

headers list | template (Optional)

请求的头部。

params list | template (Optional)

请求的查询参数。

使用模板

对于传入数据，值模板将传入的 JSON 或原始数据转换为有效的有效负载。 传入的有效负载使用可能的 JSON 值进行渲染，因此在渲染时，可以使用 value_json 访问基于 JSON 的有效负载中的属性，否则可以使用 value 变量来处理非 JSON 基础的数据。

此外，this 可以作为模板中的变量使用。this 属性指的是实体的当前 实体状态。 关于 this 变量的更多信息可以在 模板文档 中找到。

Note

带 json 的示例值模板:

给定有效负载：

{ "state": "ON", "temperature": 21.902 }

模板 {{ value_json.temperature | round(1) }} 渲染为 21.9。

示例

在本节中，您将找到一些关于如何使用此传感器的真实示例。

aREST 传感器

您可以直接使用 REST 二进制传感器检索支持 aREST 的设备值，而不是使用 aREST 二进制传感器。

binary_sensor:
  - platform: rest
    resource: http://192.168.0.5/digital/9
    method: GET
    name: Light
    device_class: light
    value_template: '{{ value_json.return_value }}'

访问受 HTTP 认证保护的端点

REST 传感器支持 HTTP 认证和启用模板的自定义头部。

binary_sensor:
  - platform: rest
    resource: http://IP_ADDRESS:5000/binary_sensor
    username: ha1
    password: test1
    authentication: basic
    headers:
      User-Agent: Home Assistant
      Content-Type: application/json
      X-Custom-Header: '{{ states("input_text.the_custom_header") }}'

头部将包含所有相关细节。这也将使您能够访问受令牌保护的端点。

Content-Length: 1024
Host: IP_ADDRESS1:5000
Authorization: Basic aGExOnRlc3Qx
Accept-Encoding: identity
Content-Type: application/json
User-Agent: Home Assistant