Home Assistant Seerr 集成实战：使用 overseerr.get_requests 动作查询媒体请求-创锋一号

Home Assistant Seerr 集成实战：使用 overseerr.get_requests 动作查询媒体请求

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本指南围绕 Home Assistant 的 Seerr（兼容 Overseerr）集成，深入讲解overseerr.get_requests动作的完整用法——从 UI 可视化配置到 YAML 底层字段，从状态过滤到响应数据消费。读完本文，你将能够在自动化与脚本中按状态、按用户、按排序方式灵活拉取 Plex / Jellyfin / Radarr / Sonarr 相关的媒体请求列表，并结合响应变量构建通知、审核等实战流程。

动作概览：它能做什么

overseerr.get_requests（Get requests）用于从 Seerr 实例检索媒体请求列表。Seerr 是一个媒体请求管理服务，负责将请求与 Plex、Jellyfin、Radarr、Sonarr 对接；Home Assistant 的 Seerr 集成（source/_integrations/overseerr.markdown）与之配合，提供了事件实体、请求/问题统计传感器以及三个动作：overseerr.get_requests、overseerr.request_media、overseerr.search_media。

该动作的核心能力有三点：

按状态过滤：只取approved（已批准）、pending（待处理）、available（已可用）等特定状态的请求；
按用户过滤：通过用户 ID 精确匹配发起请求的用户；
指定排序：按“添加时间”或“修改时间”排序返回结果。

与手动登录 Seerr 后台查看相比，这个动作的价值在于：它的结果会写入响应变量，可以在同一条自动化或脚本的后续步骤中被引用——例如把待处理的请求推送到手机、生成日报、或对接人工审核流程。

前置条件：配置 Seerr 集成

使用该动作前，需要先在 Home Assistant 中完成 Seerr 集成配置（配置流程见 source/_integrations/overseerr.markdown）：

URL：Seerr 实例的访问地址（必填）；
API key：Seerr 实例的 API 密钥，可在 Seerr 设置页面中找到（必填）。

集成加载时会尝试在 Seerr 中注册 webhook，将媒体请求更新推送到 Home Assistant（因此该集成属于Local Push类型的推送式集成）；此外，集成每 5 分钟还会主动检查一次更新，确保统计传感器数据及时刷新。

两个值得注意的限制：

Seerr 同时只能配置一个 webhook，因此一个 Seerr 实例同一时间只能连接一个 Home Assistant 实例；
集成无法在开启 CSRF 保护的情况下工作，需在 Seerr 的Settings中关闭CSRF Protection。

在 UI 中配置 Get requests 动作

对于偏好可视化配置的用户，Home Assistant 的动作编辑界面会分步引导（参考 source/_includes/actions/ui_header.md）：

进入Settings>Automations & scenes；
打开一个现有的自动化或脚本，或选择Create automation>Create new automation；
新建自动化时，在When部分添加触发器；脚本无需触发器，由其他流程调用时运行；
在Then do部分选择Add action；
在搜索框中搜索并选择Seerr: Get requests；
选择Seerr instance（实例），并按需设置Request status（请求状态）、Sort order（排序方式）和Requested by（请求者）过滤器；
在Response variable（响应变量）字段中输入一个名称用于存储数据，例如requests；
点击Save保存。

需要注意的是，该动作不支持目标（targets）——在 UI 中不会提示你选择区域、设备、实体或标签。

UI 选项说明

选项	说明	必填
Seerr instance	要从中获取请求的 Seerr 实例	是
Request status	按状态过滤请求，取值为`approved`、`pending`、`available`、`processing`、`unavailable`或`failed`	否
Sort order	按添加或修改日期对请求排序	否
Requested by	按发起请求的用户 ID 过滤请求	否

在 YAML 中使用：字段与示例

在 YAML 中（参考 source/_includes/actions/yaml_header.md），动作名称为overseerr.get_requests。典型用法是将结果存入响应变量，供后续步骤使用：

action: overseerr.get_requests data: config_entry_id: YOUR_CONFIG_ENTRY_ID status: pending sort_order: added response_variable: requests

上面的示例会获取待处理（pending）的媒体请求，并按添加时间排序。动作中的data为参数对象，response_variable为响应变量名——后续步骤可通过requests引用返回的数据。

YAML 参数详解

参数	类型	必填	说明
`config_entry_id`	string	是	要从中获取请求的 Seerr 实例（对应集成配置条目 ID）
`status`	string	否	按状态过滤请求，取值为`approved`、`pending`、`available`、`processing`、`unavailable`或`failed`
`sort_order`	string	否	按日期排序，取值为`added`或`modified`
`requested_by`	integer	否	按发起请求的用户 ID 过滤请求

从字段设计可以推断：config_entry_id是连接具体 Seerr 实例的钥匙——一个 Home Assistant 中可以配置多个 Seerr/Overseerr 实例（虽然受 webhook 数量限制，同一实例只能连接一个 HA），通过该字段指定数据来源；requested_by使用整数类型的用户 ID（而非用户名），对应 Seerr 内部的用户主键，可直接从 Seerr 后台或get_requests返回数据中取得。

响应数据：requests 列表的结构

overseerr.get_requests的响应中包含一个requests列表，每个列表项描述一条媒体请求，包含以下信息（详见 source/_actions/overseerr.get_requests.markdown）：

状态：该请求当前所处的状态；
所指向的媒体：请求的电影或剧集信息；
请求者与最后修改者：发起请求的用户以及最后修改该请求的用户。

这些字段恰好与集成提供的事件实体（event.overseerr_last_media_event）属性相互印证——集成支持pending、approved、available、failed、declined、auto_approved六种事件类型，请求相关的关键数据会存放在事件属性中，而get_requests动作则以可编程方式批量返回同样的请求数据，两者结合可以覆盖“实时监听”与“按需查询”两种场景。

实战：把查询结果变成自动化流程

要真正发挥overseerr.get_requests的价值，需要结合响应变量。下面给出两个可直接落地的 YAML 示例思路。

示例一：定时检查待处理请求并通知

alias: "Pending request digest" triggers: - trigger: time at: "09:00:00" actions: - action: overseerr.get_requests data: config_entry_id: YOUR_CONFIG_ENTRY_ID status: pending response_variable: requests - action: notify.send_message target: entity_id: notify.my_device data: title: "待处理媒体请求" message: >- 当前有 {{ requests['requests'] | length }} 条待处理请求

示例二：与 Search / Request 动作串联（多步工作流）

get_requests常常与同域名的另外两个动作配合：先用overseerr.search_media按名称搜索媒体并取得媒体 ID，再用overseerr.request_media创建请求（两个动作的文档分别为 source/_actions/overseerr.search_media.markdown 与 source/_actions/overseerr.request_media.markdown）。例如，收到“有人想看某部电影”的通知后，先查询现有pending请求确认未重复提交，再决定是否调用overseerr.request_media完成请求——一次自动化即可完成“查重 → 请求 → 通知”的闭环。

调试与验证

在写任何 YAML 之前，可以使用 Home Assistant 的动作测试界面快速验证参数与响应结构：进入Settings>Tools>Actions，搜索overseerr.get_requests，填入字段后点击Perform action，无需编写 YAML 即可在真实实例上观察返回数据（参考 source/_includes/actions/try_it.md）。这是熟悉requests列表字段结构、确认requested_by用户 ID 取值的最快途径。

若动作未返回预期数据，优先排查：

Seerr 实例是否可达、API key 是否有效（集成配置流程中的URL与API key两项）；
CSRF Protection 是否已关闭（开启时集成无法正常工作）；
webhook 注册是否成功——若 Seerr 无法访问 Home Assistant，集成将无法推送更新（参见 source/_integrations/overseerr.markdown 的 Troubleshooting 小节）。

企业官网建设流程全解析