motionEye 快照动作（motioneye.snapshot）完全指南：触发静态抓图、配置目标与自动化实战-平芜编程栈

motionEye 快照动作（motioneye.snapshot）完全指南：触发静态抓图、配置目标与自动化实战

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

motioneye.snapshot 是 Home Assistant 官方文档中 motionEye 集成提供的便捷动作（action），用于在单台或多台 motionEye 摄像头上触发静态快照（still snapshot），典型场景是在检测到运动时把当前画面保存为图片文件。本文以 motioneye.snapshot 动作文档为骨架，结合 motionEye 集成文档与相邻动作文档，完整讲解该动作的 UI 配置、YAML 写法、目标（target）机制、底层实现关系以及可直接落地的自动化示例。

动作概述：这个动作解决什么问题

motionEye 是一个基于 motion 守护进程的开源摄像头管理前端，而 Home Assistant 的 motionEye 集成（ha_domain: motioneye，自 2021.5 版本起提供）将其纳入智能家居体系。motioneye.snapshot就是该集成暴露给自动化与脚本的三个动作之一（另外两个是motioneye.action与motioneye.set_text_overlay）。

该动作的核心用途非常聚焦：

主动抓图：随时让指定摄像头输出一张静态快照。
事件联动抓图：例如结合 motionEye 上报的运动检测事件，在检测到运动时立即保存一帧画面到磁盘，作为事后取证的依据。
批量抓图：通过目标的多种粒度的选择，一次调用即可覆盖多个摄像头。

从动作语义上看，motioneye.snapshot本质上是motioneye.action动作在action: snapshot场景下的便捷快捷方式（convenient shortcut）——原文档对此有明确说明。这意味着如果你需要更精细的控制，可以直接改用motioneye.action并传入其他动作值。

前置条件：先完成 motionEye 集成配置

在使用本动作之前，需要先在 Home Assistant 中配置好 motionEye 集成。根据 motionEye 集成文档，集成通过配置流（config flow）完成，核心配置项如下：

配置项	说明
`url`	motionEye 服务器的 URL，注意不是摄像头视频流的 URL
`admin_username`	motionEye 管理员账号用户名，用于修改摄像头设置
`admin_password`	管理员账号密码
`surveillance_username`	motionEye 监控（surveillance）账号用户名，用于认证视频流
`surveillance_password`	监控账号密码

集成配置完成后会生成三类实体：

camera：展示 motionEye 视频流的 MJPEG 摄像头实体（如camera.office）。
switch：用于启用/禁用运动检测、文字叠加、视频流、静态抓图、录像及上传等功能的开关实体。
sensor：显示该设备已配置的 action 按钮数量的"动作传感器"，可用动作名称可在该传感器实体的actions属性中查看。

需要注意：如果视频流开关被关闭，摄像头实体以及作用于该摄像头的动作会变为不可用，集成其余功能不受影响。因此使用motioneye.snapshot前，请确认目标摄像头的视频流处于开启状态。

在 UI 中调用该动作

如果你更习惯可视化构建自动化与脚本，可以完全不用写 YAML。参照原文档，操作步骤如下：

进入设置 > 自动化与场景（Settings > Automations & scenes）。
打开一个现有的自动化或脚本；若从零开始，选择创建自动化>创建新自动化。
如果是新建自动化，在何时（When）部分添加一个触发器；脚本不需要触发器，它们在被其他元素调用时才会执行。
在然后执行（Then do）部分，选择添加动作（Add action）。
选择要控制的对象：在目标（By target）下（详见下文"目标机制"一节），选择你想要获取快照的 motionEye 摄像头。
在该目标展示的动作列表中，选择快照（Snapshot）。
点击保存（Save）。

关于 UI 中的选项：该动作除了目标之外没有额外的 UI 选项，界面非常精简——选中目标、选定动作、保存即可。

在 YAML 中调用该动作

在 YAML 中，该动作的标识符为motioneye.snapshot。原文档给出的基础示例如下：

action: motioneye.snapshot target: entity_id: camera.office

以上配置会在camera.office摄像头上触发一次快照。

如果是在自动化或脚本的actions列表中编写（与文档中的嵌套写法一致）：

actions: - action: motioneye.snapshot target: entity_id: camera.office

参数说明：

action：固定为motioneye.snapshot。
target：必填的目标字段，用于指定要抓图的摄像头实体。
数据字段（data）：该动作没有额外的 YAML 选项，所有能力都由目标选择承担，因此无需、也无法传入其他数据参数。

补充：直接调用与 action 简写的关系

如果你想确认底层真正发生了什么，可以对比 motioneye.action 动作文档中的等价写法：

action: motioneye.action target: entity_id: camera.office data: action: snapshot

这两段 YAML 的效果一致——后者显式指定了data.action: snapshot，前者则是它的封装。motioneye.action支持的全部动作值包括：snapshot、record_start、record_stop、lock、unlock、light_on、light_off、alarm_on、alarm_off、up、right、down、left、zoom_in、zoom_out，以及preset1至preset9。

已知限制：根据 motionEye 集成文档的 "Good to know" 说明，record_start与record_stop在 motionEye 本身中只实现了部分功能，因此行为不符合预期——这解释了为什么快照功能有专门的封装动作，而录像相关的动作没有。

目标机制（Targets）：一台还是多台摄像头

该动作必须有目标（target）。目标即动作的作用对象，你可以将动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对该目标背后的每一个匹配的camera实体执行动作。根据 actions/targets.md，可选的目标粒度包括：

实体（Entity）：某一个具体的摄像头实体，例如camera.living_room。
设备（Device）：属于某台设备的全部摄像头实体。
区域（Area）：某个房间/区域内的全部摄像头实体。
楼层（Floor）：某一楼层上的全部摄像头实体。
标签（Label）：共享某一标签的全部摄像头实体。

你还可以在同一动作中混合不同目标类型，例如同时指定一个具体实体和一个区域，让动作一次性对两者生效。这在多摄像头监控场景中非常实用：一条motioneye.snapshot动作即可让整层楼的摄像头同时抓图。

实战示例：检测到运动时自动抓图

motioneye.snapshot最常见的落地场景，正是原文档导读中提到的"检测到运动时保存图像"。motionEye 集成支持通过 webhook 把事件回调到 Home Assistant，并在收到回调后触发事件。集成文档中给出了两类事件：

motioneye.motion_detected：检测到运动。
motioneye.file_stored：媒体文件被存储。

事件数据中包含 Home Assistant 的device_id、设备name、以及尽量多的 Motion Conversion Specifiers（如changed_pixels、width、height、fps、motion_version等）。对于文件存储事件，还会自动附带media_content_id（可直接用于媒体播放器播放的标识）与file_url（媒体的原始 URL）。

下面的自动化示例，把"运动检测"与"快照抓取"直接串联起来：

- alias: "Save snapshot when motion detected" triggers: - trigger: event event_type: motioneye.motion_detected event_data: # 可选：只响应某个摄像头 # name: "Office" actions: - action: motioneye.snapshot target: entity_id: camera.office

当 motionEye 上报运动检测事件后，Home Assistant 立即对camera.office触发一次静态快照。由于 motionEye 的file_stored事件会携带file_type字段（图片小于 8，视频为其他值），你还可以进一步区分图片与视频文件，例如参考集成文档中的"自动播放存储影片"示例：

- alias: "Cast motionEye movie clips" triggers: - trigger: event event_type: motioneye.file_stored event_data: file_type: "8" # 仅处理视频 actions: - action: media_player.play_media target: entity_id: media_player.kitchen_tv data: media_content_id: "{{ trigger.event.data.media_content_id }}" media_content_type: video

需要说明的是：若要让motioneye.motion_detected与motioneye.file_stored事件正常产生，集成选项中"配置 motionEye webhooks 回调 Home Assistant"必须开启，或手动在 motionEye 中配置相应 webhook。若手动修改 webhook，注意不要删除src=hass-motioneye参数，否则该 webhook 会被集成覆盖。

注意事项与故障排查

视频流开关：如集成文档所述，视频流开关关闭后，摄像头实体及相关动作不可用，请检查switch.<name>_video_streaming状态。
MJPEG 流可达性：摄像头实体的 MJPEG 流需要 Home Assistant 能直接访问<motioneyehost>:<streaming port>。如果 motionEye 位于反向代理之后或流端口被防火墙隔离，可在集成选项中使用Stream URL template覆盖默认流地址（支持 Jinja2 模板，可使用 motionEye 摄像头字典中的name、id等变量，但模板中不可用 Home Assistant 状态）。
多摄像头共用根目录：如果多个摄像头在 motionEye 中配置了相同的文件存储根目录，媒体浏览器会把它们的媒体合并展示；如需正确归属，请为各摄像头使用独立的File Storage -> Root Directory。
排查手段：在configuration.yaml中开启如下日志可看到集成与底层客户端库的详细调用过程，便于确认快照请求是否真正发出：

logger: default: warning logs: motioneye_client: debug homeassistant.components.motioneye: debug

motionEye 快照动作（motioneye.snapshot）完全指南：触发静态抓图、配置目标与自动化实战