2025.3.4
首页 ▸ Integrations ▸

RESTful Switch

The rest switch platform allows you to control a given endpoint that supports a RESTful API. The switch can get the state via GET and set the state via POST on a given REST resource.

Configuration

To enable this switch, add the following lines to your configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] file:

# Example configuration.yaml entry
switch:
  - platform: rest
    resource: http://IP_ADDRESS/ENDPOINT

Configuration Variables

Looking for your configuration file?
resource string Required

The resource or endpoint used to control the REST switch.

state_resource string (Optional)

The resource or endpoint that reports the state if different from resource. Used by is_on_template. Defaults to resource.

method string (Optional, default: post)

The method of the request. Supported post, put or patch.

name template (Optional, default: REST Switch)

Name of the REST Switch.

icon template (Optional)

Defines a template for the icon of the entity.

picture template (Optional)

Defines a template for the entity picture of the entity.

availability template (Optional)

Defines a template if the entity state is available or not.

device_class string (Optional)

Sets the class of the device, changing the device state and icon that is displayed on the frontend.

timeout integer (Optional, default: 10)

Timeout for the request.

body_on string (Optional, default: ON)

The body of the POST request that commands the switch to become enabled. This value can be a template.

body_off string (Optional, default: OFF)

The body of the POST request that commands the switch to become disabled. This value can also be a template.

is_on_template string (Optional)

A template that determines the state of the switch from the value returned by the GET request on the resource URL. This template should compute to a boolean (True or False). If the value is valid JSON, it will be available in the template as the variable value_json. Default is equivalent to '{{ value_json == body_on }}'. This means that by default, the state of the switch is on if and only if the response to the GET request matches.

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 request.

params list | template (Optional)

The query params for the requests.

verify_ssl boolean (Optional, default: true)

Verify the SSL certificate of the endpoint.

Important

Make sure that the URL matches exactly your endpoint or resource.

使用模板

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

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

Note

带 json 的示例值模板:

给定有效负载：

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

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

Example

Switch with templated value

This example shows a switch that uses a template to allow Home Assistant to determine its state. In this example, the REST endpoint returns this JSON response with true indicating the switch is on.

{"is_active": "true"}

switch:
  - platform: rest
    resource: http://IP_ADDRESS/led_endpoint
    body_on: '{"active": "true"}'
    body_off: '{"active": "false"}'
    is_on_template: "{{ value_json.is_active }}"
    headers:
      Content-Type: application/json
      X-Custom-Header: '{{ states("input_text.the_custom_header") }}'
    verify_ssl: true

body_on and body_off can also depend on the state of the system. For example, to enable a remote temperature sensor tracking on a radio thermostat, one has to send the current value of the remote temperature sensor. This can be achieved by using the template '{"rem_temp":{{states('sensor.bedroom_temp')}}}'.