Home Assistant 中的 Immich Upload File 动作：将照片与视频自动上传到 Immich 的完整指南
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
导读
本文围绕 Home Assistant 的immich.upload_file动作展开，讲解如何将本地媒体文件（照片、视频）通过自动化或脚本上传到你的 Immich 实例，并支持直接将文件放入指定相册。读完本文，你将掌握在 UI 和 YAML 两种方式下调用该动作的完整方法、所有参数的含义与取值，并能结合camera.snapshot实现"抓拍即上传"的实战脚本。
动作概述
Upload file动作（immich.upload_file）用于将媒体文件（如照片、视频）发送到你的 Immich 实例。与简单的文件复制不同，该动作直接调用 Immich 的资产上传能力，上传后文件会成为 Immich 中的正式资产（asset），参与搜索、相册归类与统计。可选地，你还可以在上传时指定一个相册 ID（Album ID），让文件在上传完成后被自动归入该相册。
该动作的使用前提是 Immich 集成已正确配置。集成相关细节可参见 source/_integrations/immich.markdown，配置时创建的 API 密钥需具备以下权限，否则集成可能无法正常工作（admin-only权限仅当 API 密钥属于管理员用户时才可用）：
asset.downloadasset.uploadasset.readasset.viewalbum.readalbumAsset.createperson.readserver.aboutserver.statistics（仅管理员）server.storageserver.versionChecktag.readuser.read
注意：在 Immich 服务端版本1.138.0 之前，API 密钥需要
all权限。
从用户界面（UI）创建上传动作
如果你习惯用可视化的方式构建自动化和脚本，Home Assistant 会逐步引导你完成该动作的配置，无需编写 YAML：
- 进入设置（Settings）>自动化与场景（Automations & scenes）。
- 打开现有的自动化或脚本，或选择创建（Create）新建一个。
- 如果是新建自动化，在When部分添加一个触发器；脚本不需要触发器。
- 在Then do部分选择添加动作（Add action）。
- 在搜索框中搜索并选择Immich: Upload file。
- 选择要上传到的Immich 实例（Immich instance）。
- 选择要上传的文件（File）。
- 可选：输入相册 ID（Album ID），将文件放入指定相册。
- 选择保存（Save）。
UI 中的选项
| 选项 | 描述 | 是否必填 |
|---|---|---|
| Immich instance | 要上传文件到的 Immich 实例。 | 是 |
| File | 要上传的媒体文件。 | 是 |
| Album ID | 上传后将文件放入的相册。查找方法：在 Immich Web 界面中打开该相册，相册 ID 即 URL 的最后一段，例如https://your-immich-instance/albums/<ALBUM-ID>。 | 否 |
在 YAML 中使用该动作
如果直接编写 YAML，或者想确切了解 Home Assistant 底层做了什么，可以使用技术参考部分。在 YAML 中该动作写作immich.upload_file：
action: immich.upload_file data: config_entry_id: YOUR_CONFIG_ENTRY_ID file: media_content_id: "media-source://media_source/local/photo.jpg" media_content_type: "image/jpeg" album_id: YOUR_ALBUM_ID以上示例将本地照片上传到所选 Immich 实例，并将其放入指定相册。
YAML 选项详解
| 参数 | 类型 | 描述 | 是否必填 |
|---|---|---|---|
config_entry_id | string | 要上传文件到的 Immich 实例（即集成配置条目 ID）。 | 是 |
file | map | 要上传的媒体文件。 | 是 |
file.media_content_id | string | 要上传文件的媒体源 URL（media-source://形式）。 | 是 |
file.media_content_type | string | 文件的 MIME 类型，例如image/jpeg。 | 是 |
album_id | string | 上传后将文件放入的相册 ID，查找方式同 UI 选项（Immich Web 界面中相册 URL 的最后一段）。 | 否 |
其中config_entry_id是集成配置条目的唯一标识，可通过设置 > 设备与服务查看 Immich 集成条目获取。
理解media-source://文件路径
file.media_content_id使用 Home Assistant 媒体源（media source）的 URI 语法来定位待上传文件。其通用格式为：
media-source://media_source/<media_dir>/<path>默认的media_dir为local，对应的本地媒体目录默认为/media（Home Assistant OS 用户可通过 Samba 等应用访问；Container 用户可将任意卷挂载到/media）。例如media-source://media_source/local/photo.jpg对应/media/photo.jpg。
如果需要自定义或增加媒体目录，可在 source/_integrations/homeassistant.markdown 描述的homeassistant:核心配置中声明media_dirs：
homeassistant: media_dirs: local: /media recording: /mnt/recordings这样media-source://media_source/recording/xxx.mp4就会指向/mnt/recordings/xxx.mp4。
需要特别说明：媒体源集成不做任何转码，上传时media_content_type必须如实填写文件的真实 MIME 类型（如image/jpeg、video/mp4），Immich 才能正确识别并处理该资产。
实战脚本：上传摄像头抓拍快照
结合camera.snapshot动作（详见 source/_actions/camera.snapshot.markdown），可以构建一条"抓拍 → 存储 → 上传"的完整链路：先用camera.snapshot抓取摄像头画面，保存到本地媒体目录（/media），再用immich.upload_file上传到 Immich 的指定相册。
script: sequence: - variables: file_name: camera.yourcamera_{{ now().strftime("%Y%m%d-%H%M%S") }}.jpg - action: camera.snapshot data: filename: "/media/{{ file_name }}" target: entity_id: camera.yourcamera - action: immich.upload_file data: config_entry_id: 01JVJ0RA387MWA938VE8HGXBMJ file: media_content_id: "media-source://media_source/local/{{ file_name }}" media_content_type: "image/jpeg" album_id: f2de0ede-d7d4-4db3-afe3-7288f4e65bb1该脚本的关键点：
file_name变量使用now().strftime("%Y%m%d-%H%M%S")生成带时间戳的文件名，避免多次抓拍相互覆盖；camera.snapshot将快照写入/media（即默认媒体目录，camera.snapshot默认允许写入/config/www和配置的媒体目录；若要写到其他路径，需在homeassistant:的allowlist_external_dirs中声明）；immich.upload_file中media_content_id使用media-source://media_source/local/前缀拼接变量，media_content_type固定为image/jpeg；album_id指向目标相册，使抓拍照片直接归档到 Immich 的相册中。
调试与验证
立即体验（Try it yourself）：打开设置 > 工具 > 操作（Actions），搜索该动作，填写字段并点击执行动作（Perform action），即可在不编写任何 YAML 的情况下，在真实实体上观察上传效果。
若上传失败，请优先排查：
- API 密钥权限：确认已勾选文档前列出的
asset.upload等相关权限；服务端版本低于 1.138.0 时需使用all权限。 - 媒体文件路径：确认
media_content_id指向的媒体源 URI 真实存在且文件可读，注意/media目录下的文件受 Home Assistant 认证保护。 - MIME 类型：
media_content_type必须与文件实际类型匹配。 - 相册 ID：确保
album_id是 Immich Web 界面中相册 URL 的最后一段（UUID 形式），且当前 API 密钥拥有album.read与albumAsset.create权限。
集成侧的行为补充
理解动作背后的集成行为有助于排查问题。根据 source/_integrations/immich.markdown：
- 集成采用Local Polling方式，每 60 秒轮询一次 Immich 服务端数据；
- 集成提供媒体源，展示你拥有或与你共享的资产，并按相册、人物、标签分组；其搜索为上下文相关搜索，需要 Immich 服务端启用 Smart Search 功能；
- 集成会创建磁盘大小、磁盘可用、照片数、视频数等传感器实体，并提供一个用于提示 Immich 服务端新版本的更新（update）实体（要求 Immich 服务端 v1.134.0 及以上）。
以上信息可帮助你判断"上传成功但迟迟看不到新资产"这类问题是否与轮询周期或服务端版本有关。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
