Home Assistant camera.snapshot 动作完全指南：自动化抓拍、文件名模板与写入目录权限
Home Assistant camera.snapshot 动作完全指南自动化抓拍、文件名模板与写入目录权限【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读本文是围绕 Home Assistant 官方文档库中camera.snapshot动作文档 撰写的实战指南。camera.snapshot用于从摄像头抓取一帧静态图片并保存为文件典型场景如检测到门口有动静时抓拍一张访客照片。读完本文你将掌握在 UI 与 YAML 两种方式下调用该动作的完整方法、filename参数的写入路径约束与目录白名单配置以及结合时间戳模板实现每次抓拍独立留档的自动化写法。动作概览从摄像头保存一帧静态图片camera.snapshot属于 Home Assistant 的 camera 域动作其官方定义为从摄像头抓取一张静态图片still image并保存到文件。它并不是播放视频流或录制片段而是对当前画面做一次瞬时抓拍因此非常适合用于取证类场景例如运动传感器触发时抓拍门口画面快递送达提醒时抓拍门口照片留档定时巡检家中宠物活动区域。在动作文档的 front matter 中该动作明确列出六个配套动作related actions它们常与camera.snapshot组合使用camera.record录制视频camera.play_stream播放视频流camera.turn_on/camera.turn_off开关摄像头camera.enable_motion_detection/camera.disable_motion_detection启用/禁用摄像头自带运动检测这意味着你可以在一条自动化里先开启摄像头、等待稳定后再抓拍或先抓拍再调用camera.record保留完整录像。方式一通过 UI 可视化配置无需 YAML如果你习惯用界面搭建自动化与脚本Home Assistant 会以分步向导的方式引导你完成配置见 actions/ui_header.md 对 UI 用法的说明进入设置 自动化与场景Settings Automations scenes。打开现有自动化或脚本或选择创建自动化创建新自动化。若在新建自动化需先在当…时When区域添加触发器脚本不需要触发器脚本在被其他流程调用时才运行。在然后执行Then do区域选择添加动作Add action。选择要控制的对象在按目标By target目标机制详见下文目标Targets一节下选择你要抓拍的摄像头。从该目标对应的动作列表中选择抓拍摄像头快照Take camera snapshot。设置文件名Filename即快照保存的位置。点击保存。UI 中的选项选项说明是否必填文件名Filename快照保存文件的完整路径是required: true方式二通过 YAML 调用技术参考如果你直接在configuration.yaml或自动化文件中编写 YAML或在 UI 的 YAML 编辑模式下工作可以参考 actions/yaml_header.md 中所述YAML 参考节会列出字段名、字段类型以及哪些字段是必填的。在 YAML 中该动作的名称固定为camera.snapshot。最基础的示例如下action: camera.snapshot target: entity_id: camera.living_room_camera data: filename: /config/www/snapshot.jpg这段配置的作用是将camera.living_room_camera当前画面的一帧保存到/config/www/snapshot.jpg。YAML 选项字段字段说明必填类型filename快照保存文件的完整路径是required: truestring目标Targets动作的作用对象camera.snapshot必须指定目标target。目标就是动作的作用对象你可以将动作指向单个实体、设备、区域、楼层或标签Home Assistant 会对该目标背后的每一个 camera 实体执行此动作见 actions/targets.md实体Entity某一个具体的 camera 实体例如camera.living_room设备Device属于某台设备的所有 camera 实体区域Area某个房间/区域内的所有 camera 实体楼层Floor某一层楼的所有 camera 实体标签Label共享某个标签的所有 camera 实体。你还可以在同一个动作中混合不同类型的多个目标例如同时指定一个具体实体和一个区域让动作对两者一起执行。这在需要一个动作同时抓拍多个摄像头时非常实用——只需把目标指向一个包含多台摄像头的区域或标签即可。写入路径约束快照能保存到哪里目标的实体必须是 camera 实体这是该动作的基本前提。除此之外filename路径还有一个关键约束文件名中的路径必须位于 Home Assistant 允许写入的目录之内。默认情况下以下位置是允许写入的无需任何额外配置配置目录下的www文件夹因此/config/www/snapshot.jpg这类路径开箱即用你在homeassistant:配置段中通过media_dirs配置的每一个媒体目录例如/media/snapshot.jpg。扩展到其他目录allowlist_external_dirs如果需要保存到默认白名单之外的位置例如/tmp就必须在configuration.yaml的homeassistant:段中将该目录加入allowlist_external_dirs。根据 Home Assistant Core 集成文档 对allowlist_external_dirs的说明它用于在默认允许的目录之外追加允许集成读取或写入的文件夹www目录和media_dirs中列出的目录默认已允许无需也不应重复列入只需添加默认之外的目录即可。示例homeassistant: name: Home # ... 其他常规设置 allowlist_external_dirs: - /usr/var/dumping-ground - /tmp配置完成后filename: /tmp/snapshot.jpg这类路径才能正常工作。allowlist_external_dirs的类型为 list可以一次追加多个目录。实战自动化运动检测触发带时间戳的抓拍官方文档给出的完整实战案例是检测到运动时抓拍并生成带时间戳的文件名——通过在文件名中嵌入当前日期与时间让每次抓拍都保存为独立文件避免覆盖触发器检测到运动front door motion 传感器状态变为on动作抓拍摄像头快照目标前门摄像头文件名包含当前日期和时间的路径。对应完整 YAML 自动化如下官方文档原例见 camera.snapshot 动作文档automation: - alias: Save a snapshot when motion is detected triggers: - trigger: state entity_id: binary_sensor.front_door_motion to: on actions: - action: camera.snapshot target: entity_id: camera.front_door data: filename: /config/www/front_door_{{ now().strftime(%Y%m%d-%H%M%S) }}.jpg这段自动化的要点触发器使用trigger: state监听binary_sensor.front_door_motion变为on动作调用camera.snapshot目标为camera.front_door文件名模板{{ now().strftime(%Y%m%d-%H%M%S) }}是 Jinja2 模板表达式会在执行时渲染为类似20260915-044835的时间戳从而生成形如/config/www/front_door_20260915-044835.jpg的唯一文件每次抓拍互不覆盖。由于该路径位于默认白名单的www目录内无需额外修改allowlist_external_dirs即可直接使用。抓拍结果可通过/local/front_door_20260915-044835.jpg这样的 URL 在 Lovelace 或浏览器中直接访问/local/映射到配置目录下的www文件夹。立即试跑开发者工具中的 Actions在编写任何 YAML 之前你可以先用开发者工具验证动作效果打开设置 工具 动作Settings Tools Actions即原来的 Developer Tools Services搜索camera.snapshot填入目标实体与文件名点击执行动作Perform action。这会在不写一行 YAML 的情况下在真实实体上执行抓拍并立即看到结果见 actions/try_it.md。这非常适合用来确认filename路径是否可写、目标摄像头是否在线。常见问题与排查建议动作报错路径不允许写入检查filename是否位于www目录、已配置的media_dirs内或已加入allowlist_external_dirs特别注意allowlist_external_dirs必须写在homeassistant:段下才会生效。目标是多个摄像头确认目标类型实体/设备/区域/楼层/标签是否符合预期动作会对目标背后的所有 camera 实体执行抓拍。文件被反复覆盖使用带时间戳的 Jinja2 模板如now().strftime(%Y%m%d-%H%M%S)为每次抓拍生成独立文件名。想保留更长时间的画面camera.snapshot只保存单帧图片如需完整录像请结合配套动作camera.record它们在同一文档的 related actions 中被明确列为常用组合。小结camera.snapshot是 Home Assistant camera 域中实现瞬时抓拍留档的标准动作它要求目标必须是 camera 实体、filename为必填字符串且只能写入白名单目录并支持实体/设备/区域/楼层/标签五种目标粒度。结合运动检测触发器与 Jinja2 时间戳模板即可快速搭建有人到门口自动留影的实用自动化若需写入/tmp等自定义目录只需在configuration.yaml的homeassistant:段通过allowlist_external_dirs追加白名单即可。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考