2025.3.4
首页 ▸ Integrations ▸

RESTful

The rest sensor platform is consuming a given endpoint which is exposed by a RESTful API of a device, an application, or a web service. The sensor has support for GET and POST requests.

RESTful Sensor and RESTful Binary Sensor can also be set up as platforms if there is only a single sensor per endpoint.

# Example configuration.yaml entry
rest:
  - authentication: basic
    username: "admin"
    password: "password"
    scan_interval: 60
    resource: http://192.168.1.12/status.xml
    sensor:
      - name: "Adult Pool Data System"
        json_attributes_path: "$.response.system"
        value_template: "OK"
        json_attributes:
          - "runstate"
          - "model"
          - "opmode"
          - "freeze"
          - "time"
          - "sensor1"
          - "sensor2"
          - "sensor3"
          - "sensor4"
          - "sensor5"
          - "version"
      - name: "Adult Pool Data Equipment"
        json_attributes_path: "$.response.equipment"
        value_template: "OK"
        json_attributes:
          - "circuit1"
          - "circuit2"
          - "circuit3"
          - "circuit4"
          - "circuit5"
          - "circuit6"
          - "circuit7"
          - "circuit8"
      - name: "Adult Pool Data Temp"
        json_attributes_path: "$.response.temp"
        value_template: "OK"
        json_attributes:
          - "htstatus"
          - "poolsp"
          - "spasp"
          - "pooltemp"
          - "spatemp"
          - "airtemp"
  - authentication: basic
    username: "admin"
    password: "password"
    scan_interval: 60
    resource: "http://192.168.1.13/status.xml"
    sensor:
      - name: "Kiddie Pool Data System"
        json_attributes_path: "$.response.system"
        value_template: "OK"
        json_attributes:
          - "runstate"
          - "model"
          - "opmode"
          - "freeze"
          - "time"
          - "sensor1"
          - "sensor2"
          - "sensor3"
          - "sensor4"
          - "version"
      - name: "Kiddie Pool Data Equipment"
        json_attributes_path: "$.response.equipment"
        value_template: "OK"
        json_attributes:
          - "circuit1"
          - "circuit2"
          - "circuit3"
          - "circuit4"
          - "circuit5"
          - "circuit6"
          - "circuit7"
          - "circuit8"
      - name: "Kiddie Pool Data Temp"
        json_attributes_path: "$.response.temp"
        value_template: "OK"
        json_attributes:
          - "htstatus"
          - "poolsp"
          - "spasp"
          - "pooltemp"
          - "spatemp"
          - "airtemp"

Configuration Variables

Looking for your configuration file?
resource string Required

The resource or endpoint that contains the value.

resource_template template Required

The resource or endpoint that contains the value with template support.

method string (Optional, default: GET)

The method of the request. Either POST or GET.

payload string (Optional)

The payload to send with a POST request. Depends on the service, but usually formed as JSON.

payload_template template (Optional)

The payload to send with a POST request, with template support. Depends on the service, but usually formed as JSON.

verify_ssl boolean (Optional, default: true)

Whether to verify the SSL certificate of the endpoint.

ssl_cipher_list string (Optional, default: default)

The list of SSL ciphers to be accepted from this endpoint. python_default (default), modern or intermediate (inspired by Mozilla Security/Server Side TLS).

timeout integer (Optional, default: 10)

The maximum time in seconds to wait for data from the endpoint. If the timeout is reached, the sensor will become unavailable.

authentication string (Optional)

Type of the HTTP authentication. basic or digest.

username string (Optional)

The username for accessing the REST endpoint.

password string (Optional)

The password for accessing the REST endpoint.

headers list | template (Optional)

The headers for the requests.

params list | template (Optional)

The query params for the requests.

scan_interval integer (Optional, default: 30)

The frequency in seconds to call the REST endpoint.

encoding string (Optional, default: UTF-8)

The character encoding to use if none provided in the header of the shared data.

sensor list (Optional)

A list of sensors to create from the shared data. All configuration settings that are supported by RESTful Sensor not listed above can be used here.

binary_sensor list (Optional)

A list of binary sensors to create from the shared data. All configuration settings that are supported by RESTful Binary Sensor not listed above can be used here.

Important

Use either resource or resource_template.

使用模板

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

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

Note

带 json 的示例值模板:

给定有效负载：

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

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