Home Assistant Radarr 集成：radarr.get_queue 下载队列获取动作完整指南

Home Assistant Radarr 集成：radarr.get_queue 下载队列获取动作完整指南

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

导读

radarr.get_queue是 Home Assistant Radarr 集成提供的一个动作（action），用于一次性获取 Radarr 下载队列中全部影片的进度与详细信息，并通过响应变量（response variable）把结果传递给自动化或脚本的后续步骤，从而实现"下载完成时通知我""队列卡住时报警"等实用场景。本文以 radarr.get_queue.markdown 为骨架，结合 Radarr 集成文档 与同域的 radarr.get_movies 动作，完整讲解 UI 可视化配置与 YAML 两种用法、全部参数与响应字段，并给出可直接落地的自动化示例。

动作概览：它能做什么

radarr.get_queue的定义如下（摘自文档 Front matter）：

• 动作名称：radarr.get_queue
• 所属域：radarr
• 功能描述：获取当前 Radarr 下载队列中的所有影片及其进度和详细信息
• 关联动作：radarr.get_movies（获取 Radarr 影片库）

该动作的核心特点有两个：

1. 只读查询：它只读取数据，不会修改 Radarr 的任何状态，因此可以安全地放在自动化、脚本或模板中反复调用。
2. 返回响应数据：动作结果存放在你指定的响应变量中，可在同一自动化或脚本的后续步骤中使用，例如判断某部影片是否下载完成、汇总队列剩余数据量并推送到手机。

注意：响应变量的作用域仅限"当前自动化或脚本的后续步骤"，跨自动化持久化数据需要配合input_text、input_datetime等辅助元素或其他存储方式。

从 UI 使用该动作（可视化配置）

如果你更喜欢用可视化方式构建自动化，Home Assistant 会在界面上逐步引导你完成配置，无需编写 YAML（对应文档的 UI 使用说明 部分）。操作步骤如下：

1. 打开设置 > 自动化与场景（Automations & scenes）。
2. 打开一个已有的自动化或脚本；新建则选择创建自动化>创建新自动化。
3. 如果是新建自动化，先在当…时（When）部分添加触发器。脚本不需要触发器，它由其他自动化或流程调用时直接运行。
4. 在然后执行（Then do）部分选择添加动作（Add action）。
5. 在搜索框中搜索并选择Radarr: Get queue。
6. 选择要获取队列的Radarr 条目（即你在 Home Assistant 中配置的 Radarr 连接）。如果添加了多台 Radarr 服务器，请选择要查询下载队列的那一台。可选：设置最大项目数（Max items）来限制返回的队列项数量。
7. 在响应变量（Response variable）字段中输入一个名称来存储队列数据，例如queue，后续步骤就用这个名称读取队列。
8. 点击保存。

该动作不支持目标（targets）：在 UI 中不会提示你选择区域、设备、实体或标签。这也是大多数"纯数据查询"类动作的共同特征。

UI 中的选项

在 YAML 中使用该动作

如果你直接编写 YAML，或想确切知道 Home Assistant 底层做了什么，请使用 YAML 参考说明 中的字段名、类型与必填信息。在 YAML 中，该动作被称为radarr.get_queue，并将结果存入响应变量，以便在后续步骤中使用：

action: | action: radarr.get_queue data: entry_id: 01234567890abcdef1234567890abcde response_variable: queue

执行后，queue变量中就保存了 Radarr 下载队列的完整数据（具体字段见下文"响应数据"章节）。

YAML 选项详解

如何获取entry_id：entry_id是 Radarr 配置条目（config entry）的 ID，可在设置 > 设备与服务中查看对应条目的详细信息，或通过开发者工具中"列出配置条目"相关接口获得。它是 32 位十六进制字符串，如示例中的01234567890abcdef1234567890abcde。

响应数据：每个队列项的完整字段

动作响应中包含一个movies映射（mapping），以下载标题（download title）为键。每个队列项包含以下字段（来自文档的 Response data 章节）：

响应示例

文档给出的缩略响应示例如下：

movies: The.Matrix.1999.1080p.BluRay.x264: id: 123456789 movie_id: 1 title: The Matrix download_title: The.Matrix.1999.1080p.BluRay.x264 progress: "45.32%" size: 8589934592 size_left: 4697620070 status: downloading tracked_download_status: ok tracked_download_state: downloading quality: Bluray-1080p languages: - English download_client: qBittorrent indexer: My Indexer protocol: torrent estimated_completion_time: "2024-01-15T18:30:00Z" time_left: "01:23:45"

解读要点：

• movies的键是发布名（release name），与download_title一致；当同一个电影有多个下载（如多版本）时，会各自成为独立的键。
• progress、estimated_completion_time、time_left都是字符串；size与size_left是字节数，做人类可读换算（如size / 1024 / 1024 / 1024得到 GB）后更适合展示。
• status常见取值包括downloading（下载中）与queued（排队中）；结合tracked_download_state可以判断"是否正在实际下载"。

实战示例：下载完成时通知我

文档指出，该动作的典型用途是"在下载完成时通知自己"。结合上述响应结构，可以构建如下自动化：定时（或由 Radarr 队列变化触发）调用radarr.get_queue，遍历movies映射，找出status为downloading、且size_left接近0的项目，然后通过notify服务发送通知。

alias: Radarr 下载进度通知 triggers: - trigger: time_pattern hours: "/1" # 每小时检查一次 actions: - action: radarr.get_queue data: entry_id: 01234567890abcdef1234567890abcde response_variable: queue - action: notify.mobile_app_phone data: title: "Radarr 下载队列" message: > {% for item in queue["movies"].values() %} - {{ item.title }}：{{ item.progress }}，剩余 {{ (item.size_left / 1024 / 1024 / 1024) | round(2) }} GB，约 {{ item.time_left }} {% endfor %}

配合 radarr.get_movies（获取整个影片库及其状态），还可以实现"每周汇总监控中的影片数量"这类通知：前者取队列实时进度，后者取影片库的monitored、has_file等元数据，两者互补，分别对应文档中列出的关联动作关系。

结合 Radarr 集成：动作之外的实体能力

radarr.get_queue属于 Radarr 集成 的动作能力面。该集成（ha_domain: radarr，自 Home Assistant 0.47 起提供，ha_iot_class: Local Polling，即本地轮询）还提供以下实体，与队列动作配合可以构成完整的"下载管理"闭环：

• Binary sensor：Health健康检查——当 Radarr 无法与任何已启用的下载客户端通信，或 RSS 订阅/搜索没有可用索引器时判定为异常。
• Calendar：影片上映日历实体，标明上映日与发行类型（电影院 Cinemas、数字版 Digital、实体版 Physical）。
• Sensor：
  • Disk space（磁盘空间）：Radarr 可用磁盘空间（GB），每个 Radarr 中配置的存储路径对应一个传感器（如sensor.radarr_disk_space_movies）；
  • Movies（影片数）：Radarr 数据库中的影片数量（默认禁用）；
  • Queue（队列数）：下载队列中的影片数量（默认禁用）；
  • Start time（启动时间）：Radarr 最近一次重启的时间（默认禁用）。

其中sensor.radarr_queue这样的队列计数传感器适合做"队列非空即亮灯/通知"的简单触发，而radarr.get_queue则用于需要逐项明细（进度、剩余大小、预计完成时间）的场景——两者一个轻量、一个详尽，可按需选用。

配置集成时，API Key 可在 Radarr Web UI 的设置 > 常规（Settings > General）中找到（见 radarr.markdown）。

手动测试与排错

文档建议，想快速验证动作效果时，可以打开设置 > 工具 > 动作（Actions），搜索该动作、填写字段并点击执行动作（Perform action），无需编写一行 YAML 就能在真实实体上看到返回结果（对应 try_it.md）。

常见排错方向：

• 响应变量为空：确认entry_id填写的确实是 Radarr 配置条目 ID，而非其他集成条目；多台服务器时尤其容易填错。
• 返回结果不完整：检查是否设置了max_items且值过小；文档明确0表示返回全部项目。
• 队列为空：当 Radarr 没有任何正在下载/排队的项目时，movies映射可能为空，后续模板应做空值处理（例如用{% if queue.movies %}包裹）。

如果问题仍未解决，可携带具体动作调用与预期结果，前往 Home Assistant 社区论坛发帖求助（对应 stuck.md 的建议）。

总结

radarr.get_queue是 Home Assistant 中读取 Radarr 下载队列的标准动作：通过 UI 或 YAML 均可配置，核心参数只有entry_id（必填）与max_items（可选，0为全部），返回的movies映射按发布名组织每个队列项的进度、大小、状态、客户端、协议与预计完成时间等 20 余个字段。将其与响应变量、notify服务、radarr.get_movies 及集成的传感器/日历实体组合，即可实现下载进度通知、完成提醒与影片库状态汇总等完整的自动化方案。

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