jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-14 21:06:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

service-calls-page: rename to 'perform action' (#33775)

Browse Source 
Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
c0ffeeca7 2024-07-16 11:44:47 +02:00 committed by GitHub
parent 21587ae087
commit 2baefc2cfb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 21 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
source/_docs/scripts/service-calls.markdown
View File

@ -1,21 +1,21 @@
---
title: "Service calls"
description: "Instructions on how to call services in Home Assistant."
title: "Performing actions"
description: "Instructions on how to perform actions in Home Assistant."
---
Various integrations allow calling {% term services %} when a certain event occurs. The most common one is calling a service when an automation {% term trigger %} happens. But a service can also be called from a {% term script %}, a dashboard or via voice command devices such as Amazon Echo.
Various integrations allow performing {% term actions %} when a certain event occurs. The most common one is performing an action when an automation {% term trigger %} happens. But an action can also be called from a {% term script %}, a dashboard, or via voice command devices such as Amazon Echo.
The configuration options to call a configuration are the same between all integrations and are described on this page.
Examples on this page will be given as part of an automation integration configuration but different approaches can be used for other integrations too.
{% tip %}
Use the "Services" tab under Developer Tools to discover available services.
Use the "Actions" tab under **Developer tools** to discover available actions.
{% endtip %}
### The basics
Call the service `homeassistant.turn_on` on the {% term entity %} `group.living_room`. This will turn all members of `group.living_room` on. You can also use `entity_id: all` and it will turn on all possible entities.
Perform the action `homeassistant.turn_on` on the {% term entity %} `group.living_room`. This will turn all members of `group.living_room` on. You can also use `entity_id: all` and it will turn on all possible entities.
```yaml
service: homeassistant.turn_on
@ -30,7 +30,7 @@ This is done with the `target` key.
A `target` is a map that contains at least one of the following: `area_id`, `device_id`, `entity_id`.
Each of these can be a list. The values should be lower-cased.
The following example uses a single service call to turn on the lights in the
The following example uses a single action to turn on the lights in the
living room area, 2 additional light devices and 2 additional light entities:
```yaml
@ -45,9 +45,9 @@ target:
- light.landing
```
### Passing data to the service call
### Passing data to the action
You can also specify other parameters beside the entity to target. For example, the `light.turn_on` service allows specifying the brightness.
You can also specify other parameters beside the entity to target. For example, the `light.turn_on` action allows specifying the brightness.
```yaml
service: light.turn_on
@ -57,11 +57,11 @@ data:
rgb_color: [255, 0, 0]
```
A full list of the parameters for a service can be found on the documentation page of each integration, in the same way as it's done for the `light.turn_on` [service](/integrations/light/#service-lightturn_on).
A full list of the parameters for an action can be found on the documentation page of each integration, in the same way as it's done for the `light.turn_on` [action](/integrations/light/#service-lightturn_on).
### Use templates to decide which service to call
### Use templates to decide which action to perform
You can use [templating] support to dynamically choose which service to call. For example, you can call a certain service based on if a light is on.
You can use [templating] support to dynamically choose which action to perform. For example, you can perform a certain action based on if a light is on.
{% raw %}
@ -77,9 +77,9 @@ entity_id: switch.ac
{% endraw %}
### Using the Services Developer Tool
### Using the Actions developer tool
You can use the Services Developer Tool to test data to pass in a service call.
You can use the **Actions** developer tool to test data to pass in an action.
For example, you may test turning on or off a 'group' (See [groups](/integrations/group/) for more info)
To turn a group on or off, pass the following info:
@ -90,7 +90,7 @@ To turn a group on or off, pass the following info:
### Use templates to determine the attributes
Templates can also be used for the data that you pass to the service call.
Templates can also be used for the data that you pass to the action.
{% raw %}
@ -127,13 +127,13 @@ data: >
### Use templates to handle response data
Some services may respond with data that can be used in automation. This data is called _service response data_. Service response data
Some actions may respond with data that can be used in automation. This data is called _action response data_. Action response data
is typically used for data that is dynamic or large and which may not be suited for use in entity state.
Examples of service response data are upcoming calendar events for the next week or detailed driving directions.
Templates can also be used for handling response data. The service call can specify
Templates can also be used for handling response data. The action can specify
a `response_variable`. This is the [variable](/docs/scripts/#variables)
that contains the response data. You can define any name for your `response_variable`. This example calls a service and stores the response in the variable called `agenda`.
that contains the response data. You can define any name for your `response_variable`. This example performs an action and stores the response in the variable called `agenda`.
{% raw %}
@ -154,7 +154,7 @@ in the same script. The example below sends a notification using the response
data.
{% important %}
Which data fields can be used in a service call depends on the type of notification service that is used.
Which data fields can be used in an action depends on the type of notification that is used.
{% endimportant %}
{% raw %}
@ -175,16 +175,16 @@ data:
{% endraw %}
### `homeassistant` services
### `homeassistant` actions
There are four `homeassistant` services that aren't tied to any single domain, these are:
There are four `homeassistant` actions that aren't tied to any single domain, these are:
- `homeassistant.turn_on` - Turns on an entity (that supports being turned on), for example an `automation`, `switch`, etc.
- `homeassistant.turn_off` - Turns off an entity (that supports being turned off), for example an `automation`, `switch`, etc.
- `homeassistant.toggle` - Turns off an entity that is on, or turns on an entity that is off (that supports being turned on and off)
- `homeassistant.update_entity` - Request the update of an entity, rather than waiting for the next scheduled update, for example [Google travel time] sensor, a [template sensor], or a [light]
Complete service details and examples can be found on the [Home Assistant integration][homeassistant-integration-services] page.
Complete action details and examples can be found on the [Home Assistant integration][homeassistant-integration-services] page.
[templating]: /docs/configuration/templating/
[google travel time]: /integrations/google_travel_time/