Remove deprecated service list_events in favor of get_events (#30196)

* Deprecate service list_events in favor of get_events

- The service `calendar.list_events` is deprecated in favor or `calendar.get_events`
- in 2023.12. Scheduled to be removed in 2024.6
- This PR adds a note that this service is deprecated
- The docs for `get_events` are a topic for a separate PR
- Unlike list_events, get_events supports multiple responses
- related parent PR in core: https://github.com/home-assistant/core/pull/102481

* remove newlines

* Remove dates to align with format of other deprecation notices

* WIP: add calendar.list_events

* Add example of get_event, remove list_event

* Fix exmaple in service-calls
This commit is contained in:
c0ffeeca7 2023-12-14 10:19:47 +01:00 committed by GitHub
parent 07b7c8c446
commit 1be6ac4854
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 18 additions and 18 deletions

View File

@ -133,13 +133,12 @@ Examples of service response data are upcoming calendar events for the next week
Templates can also be used for handling response data. The service call 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 calls a service and stores the response in the variable called `agenda`.
{% raw %}
```yaml
service: calendar.list_events
service: calendar.get_events
target:
entity_id: calendar.school
data:
@ -168,7 +167,7 @@ data:
message: >-
Your agenda for today:
<p>
{% for event in agenda.events %}
{% for event in agenda['calendar.school'].events %}
{{ event.start}}: {{ event.summary }}<br>
{% endfor %}
</p>

View File

@ -192,10 +192,10 @@ data:
{% endraw %}
### Service `calendar.list_events`
### Service `calendar.get_events`
This service populates [Response Data](/docs/scripts/service-calls#use-templates-to-handle-response-data)
with calendar events within a date range.
with calendar events within a date range. It can return events from multiple calendars.
| Service data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | --------|
@ -209,20 +209,20 @@ Use only one of `end_date_time` or `duration`.
</div>
{% raw %}
```yaml
service: calendar.list_events
service: calendar.get_events
target:
entity_id: calendar.school
entity_id:
- calendar.school
- calendar.work
data:
duration:
hours: 24
response_variable: agenda
```
{% endraw %}
The response data field `events` is a list of events with these fields:
The response data contains a field for every calendar entity (e.g. `calendar.school` and `calendar.work` in this case).
Every calendar entity has a field `events` containing a list of events with these fields:
| Response data | Description | Example |
| ---------------------- | ----------- | -------- |
@ -236,16 +236,17 @@ This example uses a template with response data in another service call:
{% raw %}
```yaml
service: notify.gmail_com
service: notify.nina
data:
target: gduser1@workspacesamples.dev
title: Daily agenda for {{ now().date() }}
message: >-
Your agenda for today:
<p>
{% for event in agenda.events %}
Your school calendar for today:
{% for event in agenda["calendar.school_calendar"]["events"] %}
{{ event.start}}: {{ event.summary }}<br>
{% endfor %}
Your work calendar for today:
{% for event in agenda["calendar.work_calendar"]["events"] %}
{{ event.start}}: {{ event.summary }}<br>
{% endfor %}
</p>
```
{% endraw %}