Home Assistant OneDrive 上传动作实战onedrive.upload 配置、通配符与最佳实践【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读本文围绕 Home Assistant 官方文档中的onedrive.upload动作source/_actions/onedrive.upload.markdown展开讲解如何通过 UI 或 YAML 把 Home Assistant 本地的文件如摄像头快照上传到 OneDrive 应用专属文件夹并深入解析allowlist_external_dirs权限约束、多文件列表、glob 通配符规则与响应数据结构。读完本文你将能够在自动化与脚本中可靠地上传单个或批量文件并掌握 OneDrive 命名限制、目录自动创建与通配符不匹配报错等关键行为。一、动作定位OneDrive 集成体系中的文件上传入口onedrive.upload是 Home Assistant 官方 OneDrive 集成ha_release: 2025.2质量等级 platinum提供的两个动作之一另一个是配套的 onedrive.delete 删除动作。该集成通过 Microsoft Graph API 与个人 OneDrive 通信主要用途有两个作为**备份Backup**的后端存储把 Home Assistant 备份写入Home Assistant\backups_id文件夹上传通用文件到你的 OneDrive本文即聚焦这一能力。从源码结构看动作文档定义于 source/_actions/onedrive.upload.markdown其 front matter 声明了动作名、所属 domain、描述以及与onedrive.delete的关联关系。所有动作文档共用同一套 UI/YAML 渲染模板见 source/_includes/actions/ 目录下的ui_header.md、yaml_header.md、try_it.md、more_examples.md、stuck.md、related.md因此下面介绍的 UI 与 YAML 两种写法对所有 Home Assistant 动作都是统一的模式。二、工作原理文件到底上传到哪里onedrive.upload上传的目标位置不是整个 OneDrive 根目录而是集成有权访问的应用专属文件夹Application Folder典型路径为Apps/Home Assistant由于 Microsoft API 的已知问题onedrive-api-docs issue #1866有时会显示为Apps/Graph详见集成文档中的Backup folder is calledGraph小节集成在配置时请求的权限Files.ReadWrite.AppFolder限定了它只能在自己的应用文件夹内读写无法访问 OneDrive 其他部分动作中的destination_folder是相对于该应用文件夹内部的目标目录若目录不存在会被自动创建支持多级子文件夹。这一设计意味着上传行为被严格限制在应用沙箱内即使自动化配置错误也不会向 OneDrive 任意目录写入数据。三、通过 UI 在自动化/脚本中调用在设置 自动化与场景中新建自动化或脚本脚本无需触发器由其他流程调用在Then do部分选择添加动作搜索并选择OneDrive: Upload files然后配置UI 选项说明是否必填Config entry ID选择要上传到的 OneDrive 配置条目是Filenames一个或多个要上传的文件路径是Destination folder应用文件夹内的目标目录不存在会自动创建是保存后即可运行。注意该动作不支持目标targetsUI 中不会提示你选择区域、设备、实体或标签它只作用于指定的配置条目。四、YAML 用法与参数详解若直接编写 YAML自动化/脚本的action字段动作名为onedrive.upload。文档给出的基础示例如下action: onedrive.upload data: config_entry_id: a1bee602deade2b09bc522749bbce48e filename: /media/image.jpg destination_folder: Snapshots/2025上例把/media/image.jpg上传到应用文件夹内的Snapshots/2025目录。各参数完整说明config_entry_id必填string要上传到的 OneDrive 配置条目 ID即集成实例的标识。同一账号下可配置多个 OneDrive 实例例如多个 Microsoft 账号通过该 ID 区分目标。filename必填string 或 list要上传的一个或多个文件路径。关键约束路径必须位于homeassistant:配置的allowlist_external_dirs白名单中详见下一节支持通配符glob 模式可一次上传多个文件使用通配符时第一个通配符之前的目录部分必须位于allowlist_external_dirs中类型可为单个字符串也可为字符串列表多文件。destination_folder必填string应用文件夹内的目标目录支持子文件夹目录不存在会自动创建文件夹名必须符合 OneDrive/SharePoint 的命名限制例如不能包含、*、:、、、?、/、\或|等字符。五、路径权限allowlist_external_dirs白名单filename的路径限制源自 Home Assistant 核心配置。在 source/_integrations/homeassistant.markdown 中allowlist_external_dirs的定义为Extra folders that integrations are allowed to read from or write to, on top of the defaults. By default, thewwwfolder inside your configuration directory and every folder listed undermedia_dirsare already allowed, and you do not need to repeat them here. Only add directories outside of those defaults.即默认已允许配置目录下的www文件夹和media_dirs列出的所有目录除此之外的外部目录需要显式加入白名单。示例配置homeassistant: name: Home allowlist_external_dirs: - /usr/var/dumping-ground - /tmp media_dirs: media: /media recordings: /mnt/recordings实操建议若filename使用/media/...等media_dirs下的路径如摄像头快照存到/media无需额外配置若要上传位于其他路径如/tmp、外部挂载盘的文件必须先将其加入allowlist_external_dirs否则动作会因无权访问而失败使用通配符时只需保证通配符之前的目录在白名单内即可。六、批量上传列表与通配符两种方式6.1 多文件列表将filename传为列表即可一次上传多个文件action: onedrive.upload data: config_entry_id: a1bee602deade2b09bc522749bbce48e filename: - /media/image_1.jpg - /media/image_2.jpg destination_folder: Snapshots/20256.2 glob 通配符规则filename支持以下通配符语法通配符含义示例*匹配单层目录内的任意字符/media/snapshots/*.jpg上传snapshots文件夹下所有 JPG**递归匹配文件夹/media/snapshots/**/*.jpg上传snapshots及其所有子目录下的 JPG?匹配单个字符image?.jpg匹配image1.jpg等[开始一个字符范围[0-9]匹配数字action: onedrive.upload data: config_entry_id: a1bee602deade2b09bc522749bbce48e filename: /media/snapshots/**/*.jpg destination_folder: Snapshots/2025通配符行为要点子目录结构保留当通配符匹配到子文件夹中的文件时会在 OneDrive 的destination_folder内重建相同的子目录结构保持原始层级无匹配即报错若通配符模式没有匹配到任何文件动作会失败并列出没有匹配项的模式*、?、[三个字符始终被当作通配符处理无法转义为字面字符因此文件名本身不能包含这些特殊字符这与 OneDrive 命名限制也一致。七、响应数据上传结果的元数据当你在自动化中为动作提供响应变量response variable时onedrive.upload会返回一个files列表其中每个条目描述一个已上传的文件包含 OneDrive 返回的元数据例如ID文件在 OneDrive 中的唯一标识name文件名size文件大小。利用响应变量可以在后续步骤中读取上传结果做进一步处理如记录日志、判断是否成功。八、配套动作onedrive.delete 与回收站行为onedrive.upload与 onedrive.delete 互为关联动作front matter 中互相引用。删除动作针对应用文件夹内的文件同样支持列表批量删除action: onedrive.delete data: config_entry_id: a1bee602deade2b09bc522749bbce48e destination_path: Snapshots/2025/image.jpg需要留意的行为差异删除动作只删除文件不删除上传时创建的文件夹删除后文件进入回收站默认保留 30 天若在集成选项中启用Delete files permanently备份系统清理时文件会被立即永久删除见集成选项说明。因此一个典型的滚动快照自动化可以组合使用上传新快照 → 按通配符删除过期快照借助回收站保留误删恢复的余地。九、使用前提与注意事项仅支持个人 OneDrive当前集成不适用于 OneDrive for Business见集成文档的 Known limitations账户链接集成默认通过 Home Assistant 提供的应用凭据完成 Microsoft 账户链接若你禁用了default_config中的部分配置account linking 需要my与cloud集成加载会被要求手动输入client ID与client secret冻结风险若 OneDrive 达到配额上限驱动器会进入Exceeded状态并被冻结此时无法再上传任何备份与文件需先清理空间集成提供sensor.my_drive_drive_state等存储传感器状态值为Normal、Nearing limit、Critical、Exceeded每 5 分钟更新可配合自动化告警Graph 文件夹现象应用文件夹名为Home Assistant或Graph均属正常可手动重命名而不破坏集成但重命名后需确保路径一致默认凭据与自定义凭据切换若从默认凭据切换到自定义凭据OneDrive 内的备份文件夹会变化需手动把旧文件夹中的备份复制到新位置。十、故障排查方向上传报路径无权访问检查filename对应目录是否已加入 allowlist_external_dirs或位于默认允许的www、media_dirs内通配符报错列出未匹配模式确认磁盘上确实存在匹配文件注意*、?、[恒为通配符、无法作为字面字符目标文件夹创建失败核对destination_folder是否符合 OneDrive 命名限制不含、*、:、、、?、/、\、|无法添加集成或上传失败检查 OneDrive 是否因长期未使用或超配额被冻结见集成文档 Troubleshooting配置条目缺失确认config_entry_id对应的 OneDrive 集成实例仍然存在且未删除。结语onedrive.upload是 Home Assistant 将本地文件持久化到云端的最直接入口配合allowlist_external_dirs权限体系、glob 通配符批量上传与响应数据可以构建出摄像头快照自动归档批量媒体文件云端备份等实用自动化。建议优先通过 UI 引导完成配置再用 YAML 固化精细场景多文件列表、递归通配符并始终留意 OneDrive 应用文件夹的沙箱边界与配额状态。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考