企业官网建设流程全解析

Home Assistant Ombi 集成教程：使用ombi.submit_tv_request动作自动提交剧集点播请求

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

ombi.submit_tv_request是 Home Assistant 中 Ombi 集成的核心动作之一，用于按剧名在 Ombi 实例中搜索电视剧，并自动提交第一个匹配结果的点播请求，同时允许你选择请求的季数范围。本文基于 source/_actions/ombi.submit_tv_request.markdown 与 Ombi 集成配置文档，完整讲解该动作的 UI 与 YAML 两种配置方式、全部参数语义、完整的自动化实战示例，并结合仓库中的关联动作（电影、音乐请求）梳理 Ombi 集成动作家族的适用场景。读完本文，你将能够在无需打开 Ombi 界面的情况下，通过语音助手、仪表盘按钮或自动化流程一键完成剧集点播。

动作概览：Ombi 集成的三种点播请求动作

在 Home Assistant 中，Ombi 集成提供了一组“搜索并提交请求”的动作，它们共用相同的交互模式：输入名称 → 调用 Ombi 搜索接口 → 自动提交第一个匹配结果。根据内容类型分为三类：

在 submit_tv_request 文档 的 Front Matter 中，通过related_actions声明了这三个动作互为关联关系，意味着在 Home Assistant 的“相关动作”区域，它们会互相引导跳转，方便你在搭建点播自动化时按需切换。

典型使用场景：不打开 Ombi 界面即可完成点播，例如通过语音助手说“帮我把《绝命毒师》加入点播列表”，或者点击仪表盘上的一个按钮触发请求。这正是ombi.submit_tv_request被设计出来的目的。

前置条件：Ombi 集成的基础配置

使用本动作之前，必须先完成 Ombi 集成的基础配置。集成通过host指向 Ombi 实例，并以两种互斥的认证方式之一接入：用户password或api_key。从 Ombi 集成文档 可以看到完整的配置方法。

获取 API Key 或准备账号

• API Key 方式：打开 Ombi 的 Web 界面，进入Settings，再进入Ombi子页面，即可看到你的api_key。
• 密码方式：直接使用日常登录 Ombi 的用户名和密码；更推荐在 Ombi 的User Management中点击Add User To Ombi为 Home Assistant 单独创建一个本地账号，并将该账号凭据用于集成配置，避免主账号凭据暴露在 Home Assistant 配置中。

configuration.yaml 示例

最简配置（用户名 + 密码）：

# Example configuration.yaml entry ombi: host: OMBI_HOST username: OMBI_USERNAME password: OMBI_PASSWORD

完整配置（API Key + 端口 + Base URL + SSL）：

# Example configuration.yaml entry ombi: host: OMBI_HOST username: OMBI_USERNAME api_key: OMBI_API_KEY port: OMBI_PORT urlbase: ombi/ ssl: true

配置参数说明

注意password与api_key是互斥的，二者只能择一填写。修改configuration.yaml后需要重启 Home Assistant 使配置生效（仓库文档通过restart_ha_after_config_inclusion引入了该提示）。

从用户界面使用该动作

如果你偏好可视化地构建自动化和脚本，Home Assistant 会引导你逐步完成该动作的配置：选择目标、调整选项、保存即可，无需掌握 YAML 语法（见 actions/ui_header.md）。

在 UI 中提交电视点播请求的完整步骤如下：

1. 进入设置>自动化与场景（Settings > Automations & scenes）。
2. 打开现有自动化或脚本；若新建，则选择创建自动化>创建新自动化。
3. 新建自动化时，在When（触发条件）部分添加触发器；脚本无需触发器，脚本在被其他内容调用时才会运行。
4. 在Then do（执行动作）部分选择添加动作（Add action）。
5. 在搜索框中搜索并选择Ombi: Submit TV request。
6. 输入要搜索的剧集名称，并选择要请求的季。
7. 点击保存。

UI 中的选项

关于目标（targets）：该动作不支持 targets。在 UI 中，你不会被提示选择区域、设备、实体或标签（仓库 actions/targets.md 中描述了这一约束的一般规则）。因此该动作是“无目标”的全局动作，直接作用于配置好的 Ombi 实例。

在 YAML 中使用该动作

如果你直接编写 YAML，或希望精确掌握 Home Assistant 在底层执行的操作，则使用技术参考字段（见 actions/yaml_header.md）。YAML 中该动作的名称是ombi.submit_tv_request。

基础示例：请求全部季

action: ombi.submit_tv_request data: name: "Breaking Bad" season: all

该示例在 Ombi 中搜索《Breaking Bad》，并请求其所有季。

YAML 参数说明

参数取值细节

• name：直接传给 Ombi 的搜索接口的剧名关键词。该动作会返回第一个匹配结果并自动提交，因此命名越准确，命中目标的可能性越高。
• season：控制请求范围的三档取值——
  • first：只请求第一季；
  • latest：只请求最新一季（默认值）；
  • all：请求全部季。

实战自动化：点击按钮请求指定剧集

场景一：按钮触发，请求最新一季

当按下仪表盘上的按钮时，在 Ombi 中请求特定剧集的最新一季。完整 YAML 自动化如下（源自原文档的折叠示例）：

automation: alias: "Request show of the week" triggers: - trigger: state entity_id: input_button.tv_request actions: - action: ombi.submit_tv_request data: name: "Breaking Bad"

配置要点：

• 触发器：input_button.tv_request是input_button辅助实体（可在设置 > 设备与服务 > 辅助元素中创建），按下按钮后其状态变化即触发本自动化。
• 动作：调用ombi.submit_tv_request，data.name指定剧名；未显式设置season，因此按默认值请求最新一季。
• 该自动化没有使用target，符合动作不支持目标的约束。

场景二：扩展到电影与专辑请求

同样的模式可直接迁移到同家族的另外两个动作：

automation: alias: "Request movie of the week" triggers: - trigger: state entity_id: input_button.movie_request actions: - action: ombi.submit_movie_request data: name: "Beverly Hills Cop"

automation: alias: "Request album of the week" triggers: - trigger: state entity_id: input_button.music_request actions: - action: ombi.submit_music_request data: name: "Nevermind"

电影与专辑请求动作同样不支持 targets，且只需要name一个必填参数（见 submit_movie_request 与 submit_music_request）。

动作工作流程与使用建议

底层行为推断

从 Ombi 集成文档 的技术属性可以推断其工作机制：

• ha_iot_class: Local Polling：集成采用本地轮询方式与 Ombi 通信，即 Home Assistant 周期性向 Ombi 实例拉取数据，动作执行时则主动向 Ombi 的 API 发起搜索与提交请求。
• ha_platforms: sensor：集成目前主要暴露传感器实体；ombi.submit_tv_request等动作属于集成级的服务动作，直接调用 Ombi 的接口完成请求提交，不依赖传感器实体。
• 动作的典型调用链为：动作触发 → 携带name调用 Ombi 搜索 → 取第一个匹配结果 → 依据season参数组装季请求 → 提交到 Ombi。因此搜索结果的质量直接决定请求的目标，输入准确剧名是获得正确结果的关键。

实操建议

1. 优先使用 API Key 认证：避免在配置文件中保存明文密码，并可在 Ombi 中为 Home Assistant 创建专用账号，进一步隔离权限。
2. 合理设置season：默认latest适合追更场景；all适合补全老剧；first适合只对第一季感兴趣的新观众。
3. 结合语音助手：由于该动作不需要 targets，可以直接由语音助手（如 Assist）调用，实现“一句话点播”。
4. 命名要精确：动作只提交第一个搜索结果，尽量使用完整的官方剧名（含年份等区分信息），避免歧义命中错误条目。
5. 脚本与自动化配合：脚本无触发器、被调用才运行，可将点播逻辑封装为可复用脚本，再由按钮、语音或日程自动化调用。

故障排查参考

仓库文档通过actions/stuck.md引入了针对动作卡住/不生效的通用排查指引，结合本动作的实际情况，可优先检查以下环节：

• 集成是否已正确配置：host、port、urlbase、ssl是否与实际 Ombi 部署一致；password与api_key是否重复填写（二者互斥）。
• 认证凭据是否有效：使用专用账号时，确认该账号在 Ombi 中具有提交点播请求的权限。
• 剧名是否准确：搜索不到结果或请求到错误条目时，先尝试在 Ombi 界面手动搜索确认名称。
• 网络连通性：Ombi 采用本地轮询与本地请求，确认 Home Assistant 与 Ombi 实例之间网络可达、端口开放。

小结

ombi.submit_tv_request将“打开 Ombi → 搜索 → 选择季 → 提交请求”这一系列人工操作压缩为一个动作调用。通过 UI 配置 或 YAML 编写，配合season参数的first/latest/all三档控制，你可以把剧集点播无缝接入按钮、语音和自动化流程；再结合同家族的ombi.submit_movie_request与ombi.submit_music_request，即可在 Home Assistant 中构建完整的媒体点播自动化体系，全程无需离开 Home Assistant 界面。

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