上传、下载和管理文件

适用于： 开发 人员

使用 Microsoft Graph 文件和 DriveItem API 管理 SharePoint Embedded 容器中的文件。

首先完成 创建和管理容器 ，以便获得容器 ID。

了解文件存储

SharePoint Embedded 容器是应用程序内容的存储边界。

每个容器通过 Microsoft Graph 文件存储和 DriveItem API 公开文件内容。

使用应用程序数据模型可以决定哪个业务对象拥有每个容器、应用创建哪些文件夹、哪些用户或服务可以读取和写入，以及应用商店中的文件 ID。

有关体系结构，请参阅 SharePoint Embedded 应用体系结构。

使用 Microsoft Graph 文件存储 API

从以下Microsoft Graph 引用开始：

重要

使用记录Microsoft Graph DriveItem 和文件存储 API。 不要发明特定于 SharePoint Embedded 的文件 API 名称。

先决条件

在管理文件之前，请确保：

  • 你的应用可以获取Microsoft Graph 令牌。
  • 应用已 FileStorageContainer.Selected 同意。
  • 应用具有针对预期操作的容器类型权限。
  • 目标容器存在。
  • 对于委托调用，用户是容器的成员。
  • 应用存储所需的容器 ID 和 DriveItem ID。

将容器 ID 映射到驱动器

预览源指出，Graph 预览终结点使用 driveId，对于 SharePoint Embedded，驱动器 ID 是以 b!开头的容器 ID。

在应用中：

  1. 存储创建容器时返回的容器 ID。

  2. 调用需要驱动器标识符的 DriveItem API 时，请使用容器 ID。

  3. 存储通过上传或文件夹创建操作返回的项目 ID。

  4. 避免从 URL 重新构造 ID。

上传文件

对 DriveItems 使用 Microsoft Graph 上传模式。

对于 (最大为 250 MB) 的小文件，请使用针对 DriveItems 记录的简单上传 API，并单个 PUT 上传到项目的内容。

对于 (大于 250 MB) 的文件，请使用 Microsoft Graph 记录的上传会话，并按字节范围区块 (发送文件，例如，) 320 KB 倍数，直到上传完成。

在上传流中：

  1. 验证写入访问权限。
  2. 在容器中选择目标文件夹。
  3. 如果路径不存在，请先创建文件夹。
  4. 使用适当的 Graph 方法上传文件字节。
  5. 存储返回的 DriveItem ID。
  6. 显示文件名、大小和状态。

提示

在应用程序数据库中保留业务元数据，并在 SharePoint Embedded 中保留文件内容。

下载文件

对文件内容使用 Microsoft Graph DriveItem 下载功能。

在下载流中：

  1. 验证读取访问权限。
  2. 解析容器 ID 和 DriveItem ID。
  3. 使用 DriveItem API 请求文件内容或下载 URL。
  4. 将内容Stream给用户或服务。
  5. 处理短期下载 URL 的过期时间。
  6. 根据审核要求记录。

创建文件夹

使用 DriveItem 文件夹创建 API 来组织内容。

为可预测内容结构、工作流阶段、相关上传和 Office 启动 URL 的稳定父项创建文件夹。

创建文件夹时：

  1. 检查文件夹是否存在。
  2. 仅创建缺少的路径段。
  3. 根据需要存储文件夹 DriveItem ID。
  4. 一致地应用命名规则。

更新文件内容

使用 Microsoft Graph DriveItem 更新或上传会话模式替换内容。

替换内容之前：

  • 确认写入权限。
  • 如果需要并发检查，请读取当前元数据。
  • 在支持的位置保留 DriveItem ID。
  • 在 Graph 成功后更新应用元数据。

SharePoint Embedded 中存储的 Office 文件已自动为Word、Excel 和 PowerPoint 文件启用版本控制。

请参阅 从应用中打开 Office 文件 了解 Office 行为。

重命名或移动项目

在支持的位置使用记录的 DriveItem 更新和移动操作。

安全流应读取当前 DriveItem、确认目标文件夹、应用操作、刷新存储路径或显示名称，并尽可能将 DriveItem ID 保留为持久引用。

删除文件

当文件不应再出现在活动内容体验中时，请使用删除操作。

删除前：

  • 确认用户意向。
  • 确认写入或删除权限。
  • 确定应用是否需要软删除。
  • 仅在 Graph 返回成功后更新应用状态。

还原文件

使用为 DriveItems 和服务体验记录的 Microsoft Graph 和 SharePoint 文件还原功能。

还原流应标识已删除的项或版本、确认权限、执行还原、刷新项列表并传达还原的位置。

注意

recycleBinItem：还原 支持 driveItemId 作为备用密钥 (2025 年 10 月) 。 如果知道原始 driveItem 的 ID，则可以直接还原相应的 recycleBinItem ，而无需首先枚举回收站。

注意

有关确切的文件操作请求和响应详细信息，请使用 Microsoft Graph DriveItem 文档。

连接到 Office 和预览体验

上传后，添加更丰富的体验：

验证文件操作

创建冒烟测试：

  1. 创建测试容器。
  2. 创建文件夹。
  3. 上传文件。
  4. 读取返回的 DriveItem 元数据。
  5. 下载文件。
  6. 替换内容。
  7. 重命名文件。
  8. 删除该文件。
  9. 如果支持，请还原它。
  10. 清理测试容器。

排查文件操作问题

症状 支票
上传失败 WriteContent 权限和用户编写者角色。
下载失败 ReadContent 权限和用户读取者角色。
文件夹创建失败 父文件夹 ID 和写入权限。
预览失败 文件类型支持和预览 URL 生成。
Office 启动打开错误模式 启动 URL action 参数或 Office URI 方案。
访问权限因用户而异 委托访问将应用权限与成员身份相交。

后续步骤

在应用中打开 Office 文件中启用 Office 启动体验。

  • Last updated on