企业官网建设流程全解析

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，然后配置：

保存后即可运行。注意：该动作不支持目标（targets），UI 中不会提示你选择区域、设备、实体或标签，它只作用于指定的配置条目。

四、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/2025

6.2 glob 通配符规则

filename支持以下通配符语法：

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，备份系统清理时文件会被立即永久删除（见集成选项说明）。

因此一个典型的"滚动快照"自动化可以组合使用：上传新快照 → 按通配符删除过期快照，借助回收站保留误删恢复的余地。

九、使用前提与注意事项

1. 仅支持个人 OneDrive：当前集成不适用于 OneDrive for Business（见集成文档的 Known limitations）；
2. 账户链接：集成默认通过 Home Assistant 提供的应用凭据完成 Microsoft 账户链接；若你禁用了default_config中的部分配置（account linking 需要my与cloud集成加载），会被要求手动输入client ID与client secret；
3. 冻结风险：若 OneDrive 达到配额上限，驱动器会进入Exceeded状态并被冻结，此时无法再上传任何备份与文件，需先清理空间（集成提供sensor.my_drive_drive_state等存储传感器，状态值为Normal、Nearing limit、Critical、Exceeded，每 5 分钟更新，可配合自动化告警）；
4. Graph 文件夹现象：应用文件夹名为Home Assistant或Graph均属正常，可手动重命名而不破坏集成，但重命名后需确保路径一致；
5. 默认凭据与自定义凭据切换：若从默认凭据切换到自定义凭据，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