首页 ▸ Integrations ▸

RESTful 传感器

rest 传感器平台用于消费设备、应用程序或 Web 服务所暴露的 RESTful API 的指定端点。该传感器支持 GET 和 POST 请求。

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

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

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

或进行 POST 请求：

# 示例 configuration.yaml 条目
sensor:
  - platform: rest
    resource: http://IP_ADDRESS/ENDPOINT
    method: POST
    payload: '{ "device" : "heater" }'

或者基于模板的请求：

# 示例 configuration.yaml 条目
sensor:
  - platform: rest
    resource_template: http://IP_ADDRESS/{{ now().strftime('%Y-%m-%d') }}
    headers:
      Authorization: >
        Bearer {{ states("input_text.my_access_token") }}
    params:
      start_date: >
        {{ (now() - timedelta(days = 1)).strftime('%Y-%m-%d') }}

Configuration Variables

Looking for your configuration file?

authentication string (Optional)

HTTP 身份验证的类型。基本或摘要。

availability template (Optional)

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

device_class string (Optional)

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

force_update boolean (Optional, default: false)

即使值未更改也发送更新事件。如果您希望在历史记录中有有意义的值图形，这很有用。

headers template | list (Optional)

请求的头部。

icon template (Optional)

为 REST 传感器的图标定义模板。

json_attributes string | list (Optional)

从 JSON 字典结果中提取值的键的列表，然后设置为传感器属性。如果端点返回类型为 text/xml、application/xml 或 application/xhtml+xml 的 XML，则会根据此规范自动转换为 JSON

json_attributes_path string (Optional)

一个 JSONPath ，引用 JSON 内容中 json_attributes 的位置。

method string (Optional, default: GET)

请求的方法。可以是 POST 或 GET。

name template (Optional, default: REST 传感器)

为 REST 传感器的名称定义模板。

params template | list (Optional)

请求的查询参数。

password string (Optional)

访问 REST 端点的密码。

payload string (Optional)

与 POST 请求一起发送的有效载荷。取决于服务，但通常以 JSON 形式构成。

picture template (Optional)

为 REST 传感器的实体图片定义模板。

resource string Required

包含值的资源或端点。

resource_template template Required

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

state_class string (Optional)

传感器的 state_class。

timeout integer (Optional, default: 10)

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

unique_id string (Optional)

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

unit_of_measurement string (Optional)

定义传感器的测量单位（如果有）。

username string (Optional)

访问 REST 端点的用户名。

value_template template (Optional)

定义一个模板来提取值。

verify_ssl boolean (Optional, default: true)

验证端点的 SSL 证书。

Important

使用 resource 或 resource_template 之一。

curl 可以帮助您识别要在 Home Assistant 前端显示的变量。下面的示例显示运行 aREST 的设备的 JSON 响应。

$ curl -X GET http://192.168.1.31/temperature/
{"temperature": 77, "id": "sensor02", "name": "livingroom", "connected": true}

预期的响应是一个字典或以字典作为第 0 个元素的列表。

使用模板

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

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

Note

带 json 的示例值模板:

给定有效负载：

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

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

示例

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

外部 IP 地址

您可以使用 ipify 服务为 IPv4 和 IPv6 查找您的外部 IP 地址。

sensor:
  - platform: rest
    name: "外部 IP"
    resource: "https://api.ipify.org/?format=json"
    value_template: "{{ value_json.ip }}"

  - platform: rest
    name: "外部 IPv6"
    resource: "https://api6.ipify.org/?format=json"
    value_template: "{{ value_json.ip }}"

从本地 Glances 实例获取单一值

glances 传感器对所有暴露的值执行完全相同的操作。

sensor:
  - platform: rest
    resource: http://IP_ADRRESS:61208/api/2/mem/used
    name: 使用的内存
    value_template: "{{ value_json.used| multiply(0.000000954) | round(0) }}"
    unit_of_measurement: MB

从另一个 Home Assistant 实例获取值

Home Assistant API 暴露您附加传感器的数据。如果您运行多个未连接的 Home Assistant 实例，您仍然可以从中获取信息。

如果资源变量中的 Home Assistant 实例受到 API 密码保护，您可以将 ?api_password=YOUR_PASSWORD 附加到资源 URL 以进行身份验证，或使用 headers:。

sensor:
  - platform: rest
    resource: http://IP_ADDRESS:8123/api/states/sensor.weather_temperature
    name: 温度
    value_template: "{{ value_json.state }}"
    unit_of_measurement: "°C"

访问受 HTTP 身份验证保护的端点

REST 传感器支持 HTTP 身份验证和自定义头部。

sensor:
  - platform: rest
    resource: http://IP_ADDRESS:5000/sensor
    username: ha1
    password: test1
    authentication: basic
    headers:
      User-Agent: Home Assistant
      Content-Type: application/json

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

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

如果您正在访问受到 Bearer 令牌保护的资源并在 Authorization 头中，您可以将令牌放在传感器配置的头字段中（不推荐）或将令牌存储在您的 secrets.yaml 文件中。在这种情况下，请确保在 secrets 文件中包括单词 Bearer。

sensor:
  - platform: rest
    resource: http://IP_ADDRESS:5000/sensor
    headers:
      Authorization: !secret my_sensor_secret_token

secrets.yaml 文件的示例条目：

my_sensor_secret_token: Bearer gh_DHQIXKVf6Pr4H8Yqz8uhApk_mnV6Zje6Pr4H8Yqz8A8nCxz6SBghQdS51

使用 GitHub 获取 Home Assistant 的最新版本

此示例与 updater 集成非常相似，但信息是从 GitHub 获取的。

sensor:
  - platform: rest
    resource: https://api.github.com/repos/home-assistant/home-assistant/releases/latest
    username: YOUR_GITHUB_USERNAME
    password: YOUR_GITHUB_ACCESS_TOKEN
    authentication: basic
    value_template: "{{ value_json.tag_name }}"
    headers:
      Accept: application/vnd.github.v3+json
      Content-Type: application/json
      User-Agent: Home Assistant REST sensor

获取多个 JSON 属性并将其呈现为值

JSON Test 返回当前时间、日期和自 UNIX 纪元以来的毫秒数，来自 http://date.jsontest.com/ 。

rest:
  - resource: "http://date.jsontest.com/"
    sensor:
      - name: "时间"
        value_template: "{{ value_json.time }}"

      - name: "日期"
        value_template: "{{ value_json.date }}"

      - name: "毫秒"
        value_template: "{{ value_json.milliseconds_since_epoch }}"

JSONPlaceholder 提供用于测试的示例 JSON 数据。在下面的示例中，JSONPath 定位 JSON 文档中的属性。 JSONPath Online Evaluator 提供一个工具来测试您的 JSONPath。如果端点返回 XML，则在搜索属性之前，它将使用 xmltodict 转换为 JSON。您可能会发现 XMLtoDict 调试工具对测试 XML 如何转换为 JSON 有帮助。

sensor:
  - platform: rest
    name: JSON 用户
    json_attributes_path: "$.[0].address"
    json_attributes:
      - street
      - suite
      - city
      - zipcode
    resource: https://jsonplaceholder.typicode.com/users
    value_template: "{{ value_json[0].name }}"

此示例从 OpenWeatherMap 获取天气报告，将结果数据映射到 RESTful 传感器的属性，然后创建一组监控这些属性并以可用形式呈现值的模板传感器。

rest:
  - resource: "https://api.openweathermap.org/data/2.5/weather?zip=80302,us&APPID=VERYSECRETAPIKEY"
    sensor:
      - name: "报告"
        value_template: "{{ value_json['weather'][0]['description'].title() }}"
        picture: "{{ 'https://openweathermap.org/img/w/' + value_json['weather'][0]['icon'].lower() + '.png' }}"

      - name: "外部温度"
        value_template: "{{ value_json['main']['temp'] - 273.15 }}"
        unit_of_measurement: "°C"

      - name: "外部压力"
        value_template: "{{ value_json['main']['pressure'] }}"
        unit_of_measurement: "hP"

      - name: "外部湿度"
        value_template: "{{ value_json['main']['humidity'] }}"
        unit_of_measurement: "%"

此配置展示了如何从字典中提取多个值。该方法避免了对 REST 服务的频繁请求，因为结果只请求一次。通过使用模板传感器，可以从该单个请求中创建多个传感器。

{
    "bedroom1": {
        "temperature": 15.79,
        "humidity": 55.78,
        "battery": 5.26,
        "timestamp": "2019-02-27T22:21:37Z"
    },
    "bedroom2": {
        "temperature": 18.99,
        "humidity": 49.81,
        "battery": 5.08,
        "timestamp": "2019-02-27T22:23:44Z"
    },
    "bedroom3": {
        "temperature": 18.58,
        "humidity": 47.95,
        "battery": 5.15,
        "timestamp": "2019-02-27T22:21:22Z"
    }
}

rest:
    resource: "http://<address_to_rest_service>"
    sensor:
      - name: "卧室1 温度"
        value_template: "{{ value_json['bedroom1']['temperature'] }}"
        device_class: temperature
        unit_of_measurement: "°C"
      - name: "卧室1 湿度"
        value_template: "{{ value_json['bedroom1']['humidity'] }}"
        device_class: humidity
        unit_of_measurement: "%"
      - name: "卧室1 电池"
        value_template: "{{ value_json['bedroom1']['battery'] }}"
        device_class: battery
        unit_of_measurement: "V"
      - name: "卧室2 温度"
        value_template: "{{ value_json['bedroom2']['temperature'] }}"
        device_class: temperature
        unit_of_measurement: "°C"

下面的示例展示了如何从 Steamist Steam 浴室 Wi-Fi 接口的 XML 文件中提取多个值。该值用于创建多个传感器，而不必多次轮询端点。

rest:
  # Steam 控制器
  - resource: "http://192.168.1.105/status.xml"
    scan_interval: 15
  
    sensor:
      - name: "蒸汽温度"
        value_template: "{{ value_json['response']['temp0'] | regex_findall_index('([0-9]+)XF') }}"
        unit_of_measurement: "°F"

      - name: "蒸汽剩余时间"
        value_template: "{{ value_json['response']['time0'] }}"
        unit_of_measurement: "分钟"

rest_command:  
  set_steam_led:
    url: http://192.168.1.105/leds.cgi?led={{ led }}

供参考，上述示例的端点的 XML 内容如下：

<?xml version="1.0" encoding="utf-8"?>

 <response>
 	<scan>0</scan>
	<ver>12556</ver>
	<count>48</count>
	<ssid>alexander</ssid>
	<bss>
		<valid>0</valid>
		<name>0</name>
		<privacy>0</privacy>
		<wlan>0</wlan>
		<strength>0</strength>
	</bss>
	<led0>0</led0>
	<led1>0</led1>
	<led2>0</led2>
	<led3>0</led3>
	<led4>0</led4>
	<led5>0</led5>
	<led6>0</led6>
	<led7>0</led7>
	<btn0>up</btn0>
	<btn1>up</btn1>
	<btn2>up</btn2>
	<btn3>up</btn3>
	<pot0>0</pot0>
	<usr0>0</usr0>
	<temp0>0x73XF0x73XF</temp0>
	<time0> 0</time0>
 </response>

帮助我们改进翻译

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

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