上传、下载和管理文件

适用于： 开发人员版

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

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

SharePoint Embedded 为应用提供一个仅限 API 的文档存储，其中包含内置的 Microsoft 365 功能。 文件管理完全通过 Microsoft Graph 进行编程，无需 SharePoint UI。 整个生命周期包括上传和下载、文件夹、版本控制、回收站和 93 天内容还原。 内容可通过 Microsoft 搜索 API 搜索，并继承租户的 Microsoft Purview 合规性。 应用的最终用户无需 Microsoft 365 许可证即可执行基本文件操作。

了解文件存储

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 映射到驱动器

Microsoft Graph DriveItem API 使用 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 和驱动器项 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 作为 Microsoft Graph Beta 中的备用键 (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