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参与搜索、相册归类与统计。可选地你还可以在上传时指定一个相册 IDAlbum 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。可选输入相册 IDAlbum 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_fileaction: 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_idstring要上传文件到的 Immich 实例即集成配置条目 ID。是filemap要上传的媒体文件。是file.media_content_idstring要上传文件的媒体源 URLmedia-source://形式。是file.media_content_typestring文件的 MIME 类型例如image/jpeg。是album_idstring上传后将文件放入的相册 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对应的本地媒体目录默认为/mediaHome Assistant OS 用户可通过 Samba 等应用访问Container 用户可将任意卷挂载到/media。例如media-source://media_source/local/photo.jpg对应/media/photo.jpg。如果需要自定义或增加媒体目录可在 source/_integrations/homeassistant.markdown 描述的homeassistant:核心配置中声明media_dirshomeassistant: 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/mp4Immich 才能正确识别并处理该资产。实战脚本上传摄像头抓拍快照结合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/jpegalbum_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），仅供参考 Home Assistant 中的 Immich Upload File 动作：将照片与视频自动上传到 Immich 的完整指南
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参与搜索、相册归类与统计。可选地你还可以在上传时指定一个相册 IDAlbum 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。可选输入相册 IDAlbum 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_fileaction: 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_idstring要上传文件到的 Immich 实例即集成配置条目 ID。是filemap要上传的媒体文件。是file.media_content_idstring要上传文件的媒体源 URLmedia-source://形式。是file.media_content_typestring文件的 MIME 类型例如image/jpeg。是album_idstring上传后将文件放入的相册 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对应的本地媒体目录默认为/mediaHome Assistant OS 用户可通过 Samba 等应用访问Container 用户可将任意卷挂载到/media。例如media-source://media_source/local/photo.jpg对应/media/photo.jpg。如果需要自定义或增加媒体目录可在 source/_integrations/homeassistant.markdown 描述的homeassistant:核心配置中声明media_dirshomeassistant: 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/mp4Immich 才能正确识别并处理该资产。实战脚本上传摄像头抓拍快照结合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/jpegalbum_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），仅供参考