Home Assistant Apple iCloud 集成play_sound 动作让 Apple 设备响铃查找的完整配置指南【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.ioicloud.play_sound是 Home Assistant Apple iCloud 集成提供的服务动作它可以在你指定的 Apple 设备上播放查找设备Find My的丢失设备铃声即使设备处于静音Mute或勿扰Do not disturb模式也会响铃。本篇指南基于官方文档 play_sound 动作页 展开完整覆盖该动作的 UI 配置步骤、YAML 字段定义、可复用的自动化示例并结合 Apple iCloud 集成文档 说明其前置条件与底层轮询机制读完即可在自动化或脚本中准确调用该动作实现摇铃找设备。动作功能与适用场景Play sound动作会在某台 Apple 设备上播放 Lost device丢失设备声音文档明确说明其典型用途是寻找放在家里不知被塞到哪个角落的设备——比如沙发垫下的手机、抽屉里的 iPad。关键行为特性来自文档原文声音通过 iCloud/Find My 服务下发到设备设备即使设置为 Mute 或 Do not disturb 也会响铃这是它区别于普通通知的核心价值该动作不支持 targetsUI 中不会提示你选择 area、device、entity 或 label。它不依赖实体 ID而是通过accountdevice_name两个参数直接定位到 Find My 服务中的一台设备这一点在编写 YAML 时尤其需要注意不要在target字段里写实体参数全部放在data中。前置条件Apple iCloud 集成icloud.play_sound依赖 Apple iCloud 集成正常工作以下前提来自 集成文档设备必须注册 Find My 服务目标 Apple 设备需要加入 iCloud 的 Find My且账号已配置到 Home Assistant该集成为 hub 类型ha_config_flow: true通过配置流添加 Apple 账号必须使用应用专用密码文档以 important 级别强调设置该集成时必须使用 Apple 的 app-specific password应用专用密码而不是 Apple 账号本身的密码认证告警的处理如果集成配置不当你可能会持续收到 Apple 发来的有人登录了你的账号邮件与通知此时应在 iOS 设备上选择Dont Allow并在被提示时重新配置 Integration Credentials故障排查官方建议删除集成的配置存储通常在/config/.storage/icloud后重试。集成本身还带有与查找设备强相关的运行机制为避免过度消耗设备电池每个设备使用独立的动态轮询间隔而非整个账号统一间隔该间隔由设备当前所在区域zone、与家的距离以及设备电量共同决定。也就是说设备越接近已在家/电量高的状态位置查询越频繁。理解这一点有助于解释为什么响铃、显示消息这类主动动作是立即触达的手段而 presence 更新则是被动的后台机制。此外该集成的 frontmatter 声明了ha_iot_class: Cloud Polling、ha_release: 0.10并提供device_tracker与sensor两个平台每台 iCloud 设备对应一个位置追踪器和一个电池电量传感器。文档同时列出了icloud域的全部动作play_sound与 display_message、lost_device、update 互为关联动作。在 UI 中使用 play_sound若偏好可视化搭建自动化和脚本Home Assistant 会逐步引导你完成配置进入SettingsAutomations scenes自动化与场景页面打开一个已有的自动化或脚本或选择Create automationCreate new automation如果是新建自动化在When触发条件区域添加一个触发器。脚本不需要触发器——它们由其他实体调用时执行在Then do执行动作区域选择Add action在搜索框中搜索并选择Apple iCloud: Play sound填写Account账号和Device name要响铃的设备名选择Save。UI 可配置选项选项说明必填Account该设备所属的 Apple 账号用户名邮箱是Device name要响铃的 Apple 设备名必须与 Find My 中显示的名称一致是两个选项均为字符串且必填。文档特别指出device_name的取值as it appears in Find My与 Find My 应用中的显示名称一致这是实际使用中最高频的失败原因Find My 里的设备名如果改过自动化里的旧名称会立即失效需要与 Find My 界面严格对齐包括大小写与空格。在 YAML 中使用 play_sound在 YAML 中该动作引用名为icloud.play_sound基础示例如下action: action: icloud.play_sound data: account: steveapple.com device_name: Bobs iPhone执行后指定设备例中为 Bobs iPhone即会响铃。YAML 字段参考字段类型必填说明accountstring是该设备所属的 Apple 账号用户名邮箱device_namestring是要响铃的 Apple 设备名必须与 Find My 中的显示名称一致该动作没有其他可选参数。与同域的 display_message可附加sound: true布尔参数不同play_sound只有响铃这一种行为。实战自动化按下按钮就摇铃找手机文档给出了一个典型场景用按钮辅助button helper在家各房间找手机——按下按钮即触发目标手机响铃。触发器按钮辅助button helper被按下动作Apple iCloud: Play soundautomation: alias: Find my phone triggers: - trigger: state entity_id: input_button.find_my_phone actions: - action: icloud.play_sound data: account: steveapple.com device_name: Bobs iPhone从源码结构看该文档为 Jekyll 站点内容示例以 Liquid 模板{% example %}/{% details %}标签包裹这段示例直接对应状态触发器 单动作的最小闭环input_button.find_my_phone状态变化触发自动化icloud.play_sound携带account/device_name两个必填参数被调用。由于动作不依赖 target示例中不需要任何target或device_id字段。与其他 icloud 动作组合文档 frontmatter 中的related_actions声明了三个关联动作它们与play_sound共同构成定位—提醒—锁定的完整设备找回链路动作YAML 名称作用Display messageicloud.display_message在设备上显示一条消息可同时播放声音sound参数可选默认falseLost deviceicloud.lost_device将设备置入 Lost Mode屏幕显示联系人与留言Updateicloud.update请求立即刷新该账号下设备的位置与状态account可选留空则刷新所有已配置账号例如lost_device 的官方示例用device_tracker实体如device_tracker.family_ipad配合to: not_homefor: hours: 1判断设备离家一小时后置为丢失update 的官方示例则在前门binary_sensor.front_door变为on时立即请求位置刷新弥补动态轮询间隔带来的延迟。这些例子与play_sound可自由组合先用update刷新位置确认设备是否在家不在家则play_sound响铃仍无果再lost_device锁机留联络方式。测试与验证不写一行 YAML 即可验证动作行为打开SettingsToolsActions开发者工具 动作搜索icloud.play_sound填入account与device_name后选择Perform action。执行结果会直接作用在你的真实设备上设备响铃无需等待自动化生效适合在首次配置时做端到端验证。注意事项与排错要点名称必须与 Find My 完全一致device_name以 Find My 中的显示名为准改名后需同步更新 YAML必填字段缺一不可account与device_name均为必填字符串缺失会导致动作调用失败认证异常持续收到 Apple 登录告警时按集成文档指引在 iOS 端拒绝登录并重新配置集成凭据彻底重置排错时可删除集成的配置存储通常为/config/.storage/icloud后重新添加 Apple 账号参数放data而非target该动作不支持 targets任何试图用实体 ID 指定设备的方式都不适用定位完全由账号邮箱 设备名完成。参考文档路径play_sound 动作、Apple iCloud 集成、display_message、lost_device、update。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考