企业官网建设流程全解析

Home Assistant OneDrive 集成onedrive.delete动作完全指南：删除文件的 UI 操作、YAML 配置与回收站行为解析

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

onedrive.delete是 Home Assistant OneDrive 集成提供的核心动作之一，用于从集成专属应用文件夹中删除一个或多个文件。本文以 关联动作文档 为主体，结合 OneDrive 集成文档 与配套的 onedrive.upload 动作文档，完整讲解该动作的 UI 操作步骤、YAML 参数定义、批量删除写法，以及删除文件是进入回收站还是被永久清除的真实行为边界，帮助你安全地在自动化与脚本中管理云端文件生命周期。

动作概述：能做什么，不能做什么

onedrive.delete用于从 OneDrive 中删除一个或多个文件。它的作用范围被严格限定在集成有权访问的应用专属文件夹内：

• 文件夹路径为Apps/Home Assistant（由于微软 Graph API 的已知问题，有时显示为Apps/Graph，详见 集成文档中的说明）；
• 该文件夹即备份默认存放的Home Assistant\backups_<id>所在的应用文件夹，集成只拥有该文件夹的读写权限，无法访问 OneDrive 其他区域；
• 该动作只删除文件，不删除上传过程中创建的文件夹；
• 该动作不支持 targets，UI 中不会提示选择区域（area）、设备（device）、实体（entity）或标签（label），因为删除的对象是云端的纯路径文件，而非 Home Assistant 实体。

文件被删除后去向何方，取决于集成设置中的Delete files permanently（永久删除文件）选项：

• 默认情况下，删除的文件进入 OneDrive 回收站（Recycle Bin），可在约 30 天内恢复；
• 若启用该选项，文件在删除时即被立即清除（按集成文档描述，该选项影响"备份系统清理文件"时的行为）。

从用户界面使用该动作

如果你偏好可视化搭建自动化或脚本，Home Assistant 会引导你逐步完成该动作，无需编写 YAML（对应通用说明见 actions/ui_header.md）。操作步骤如下：

1. 进入设置>自动化与场景（Automations & scenes）；
2. 打开现有的自动化或脚本；新建时选择创建自动化>创建新自动化；
3. 新建自动化时，在何时（When）部分添加触发条件；脚本不需要触发条件，由其他对象调用时直接运行；
4. 在然后执行（Then do）部分选择添加动作；
5. 在搜索框中搜索并选择OneDrive: Delete files；
6. 选择要删除文件的 OneDrive配置条目（Config entry），并填写要删除文件的目标路径（Destination paths）；
7. 点击保存。

UI 中的选项

在 YAML 中使用该动作

如果你直接编写 YAML，或想确切了解 Home Assistant 底层会做什么，可以参考以下技术参考（通用说明见 actions/yaml_header.md）。YAML 中该动作的名称为onedrive.delete，基本示例如下：

action: onedrive.delete data: config_entry_id: a1bee602deade2b09bc522749bbce48e destination_path: Snapshots/2025/image.jpg

上面的示例会删除Snapshots/2025文件夹中的单个文件image.jpg。

YAML 中的参数

注意config_entry_id的取值：每个 OneDrive 配置条目的 ID 都是实例特有的，你可以在设置>设备与服务中打开对应条目查看，或在 UI 中构建动作后切换到 YAML 模式获取实际值。一个 Home Assistant 实例可配置多个 OneDrive 条目，config_entry_id用于精确指定删除目标，尤其适合多实例备份到同一 OneDrive 账号的场景（该集成按实例唯一 id 生成独立的backups_<id>文件夹，避免不同实例的备份混淆，详见 集成文档）。

批量删除多个文件

destination_path支持传入路径列表，一次动作调用即可删除多个文件：

action: onedrive.delete data: config_entry_id: a1bee602deade2b09bc522749bbce48e destination_path: - Snapshots/2025/image.jpg - Snapshots/2025/image2.jpg

与上传动作 onedrive.upload 不同，delete的路径参数不支持 glob 通配符（通配符能力目前仅存在于upload的filename参数中），因此批量删除需要显式列出每一个文件路径。

动手试一试

想快速验证效果？打开设置>工具>动作（Actions），搜索该动作，填写字段后点击执行动作（Perform action），无需写一行 YAML 即可在真实环境观察删除行为（对应通用说明见 actions/try_it.md）。测试前建议先在应用文件夹中放一个无关紧要的测试文件。

底层行为与边界：回收站、永久删除与应用文件夹

理解onedrive.delete的行为，需要回到集成层面的设计约束：

• 删除范围 = 应用文件夹：集成通过微软 Graph API 通信，只申请Files.ReadWrite.AppFolder（在自身专属应用文件夹内读写）、offline_access（无人工干预刷新令牌）与openid（读取基础信息）三项权限，因此动作只能操作Apps/Home Assistant（或Apps/Graph）文件夹内的文件；
• 永久删除选项：集成配置（option flow）中的Delete files permanently默认关闭，此时删除进入回收站并可保留约 30 天；启用后文件将被立即清除。如果你的自动化会在删除后依赖"文件已不存在"的即时状态（例如随后立即重新上传同名文件），请注意两种模式下的可见性差异；
• 不删除文件夹：动作仅删除文件本身，上传时自动创建的目录结构会保留，适合配合 onedrive.upload 做"上传快照 → 清理旧文件"的循环任务；
• 应用文件夹命名差异：由于微软 API 的已知问题，应用文件夹常被命名为Graph而非Home Assistant，你可以手动重命名该文件夹而不破坏集成，但删除动作中的路径始终是相对于应用文件夹根的路径，与文件夹显示名称无关。

与备份联动：实际使用场景

onedrive.delete最常见的真实使用场景是与 Home Assistant 备份机制联动。集成文档指出，备份默认存放在应用文件夹下的Home Assistant\backups_<id>中，且该集成质量等级为 platinum（详见 集成文档）。你可以用onedrive.delete实现：

• 定期清理旧备份文件，仅保留最近 N 份；
• 删除不再需要的相机快照或临时上传文件；
• 配合upload动作构建"上传 → 校验 → 删除本地副本"的归档流程（upload支持 glob 通配符与**递归匹配，且会返回上传文件的元数据列表，可据此构造精确的删除清单）。

故障排查与社区帮助

若动作执行失败，优先检查：配置条目 ID 是否对应正确的 OneDrive 账号；目标路径是否位于应用文件夹内且拼写正确（包括大小写与子文件夹层级）；OneDrive 是否处于冻结状态（长期未使用或超出配额会导致驱动器冻结，此时无法上传与删除，见 集成文档的故障排查部分）。

如果仍无法解决，可以参考 actions/stuck.md 中的指引向社区求助，并在提问时附上你正在调用的动作、完整 YAML 与预期结果。

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