从应用打开 Office 文件

适用于: 开发人员版

使用 Microsoft 365 支持的 Microsoft Graph DriveItem 元数据和 Office 启动模式从 SharePoint Embedded 应用打开 Microsoft 文件。

首先完成 上传、下载和管理文件, 以便应用有要启动的文件。

在 SharePoint Embedded 容器中存储 Office 文件时,应用将链接到完整的协作堆栈,而无需生成一个堆栈。 Word、Excel 和 PowerPoint 文件支持实时共同创作、自动保存、自动版本历史记录以及通过可共享链接和 @mentions共享,并具有特定范围的访问级别。 无需生成协作引擎。 编辑在新的浏览器选项卡或窗口) 或 Office 桌面客户端的 Office 网页版 (中打开,因此用户可以离开应用的 UI 进行编辑;当你需要内联应用内查看时,嵌入只读预览。 有关决策上下文,请参阅在不 生成的情况下添加 Office 共同创作功能。

注意

@mentions 仅通知拥有 Microsoft 365 许可证的收件人。 SharePoint Embedded 共享不发送电子邮件邀请。

了解 Office 体验

SharePoint Embedded Office 文件体验的工作方式类似于 Microsoft 365 文件体验。 受支持的体验包括:

  • 在 Office 网页版中打开 Office 文档。
  • 在 Office 桌面客户端中打开 Office 文档。
  • 查看和编辑文件。
  • 自动保存 Word、Excel 和 PowerPoint 文件。
  • Office 文档的版本历史记录。
  • 合著。
  • 共享和可共享链接。
  • 评论和提及,具有记录的限制。
  • Office 客户端中将文件与应用关联的痕迹导航。

注意

无法查看或访问存储在已存档容器中的文档。 应用必须通过显示相应错误并指导用户执行后续步骤(例如重新激活容器)来处理存档状态。

控制 Office 集成

默认情况下,为 SharePoint Embedded 容器类型启用 Office 集成。 授权用户可以在 Office 网页版和 Office 桌面客户端中打开受支持的文件,包括通过应用的自定义用户界面之外的 Office 体验打开。 如果应用要求文件访问权限保留在应用控制的体验中,可以通过将属性fileStorageContainerTypeSettingstrue设置为 isOfficeRestricted 来禁用容器类型的 Office 集成。

有关属性定义,请参阅 fileStorageContainerTypeSettings 资源类型。

使用 Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} API 设置settings.isOfficeRestricted。

PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}
Content-Type: application/json

{
  "settings": {
    "isOfficeRestricted": true
  }
}

禁用 Office 集成后,用户无法从 Office 网页版或 Office 桌面客户端中受影响的容器启动文件。 在启用此限制之前,请确保应用为用户提供或引导用户到适当的替代体验来查看或编辑文件。

先决条件

启动 Office 文件之前,请确保:

  • 该文件存储在 SharePoint Embedded 容器中。
  • 应用可以读取文件的 DriveItem 元数据。
  • 用户具有查看或编辑文件的权限。
  • 目标 Office 客户端支持文件类型。
  • 应用处理浏览器重定向或新窗口行为。

获取 DriveItem Web URL

当应用从 Microsoft Graph 检索 DriveItem 时,响应可能包括 webUrl。

对于支持的 Office 文件类型,webUrl指向在 Office 网页版中打开文档的 URL。

受支持的 Office Web URL 具有以下形状:

https://host/:w:r/contentstorage/sitecollection/_layouts/15/doc2.aspx?sourcedoc=guid&file=filename.docx&action=default&mobileredirect=true

有关请求的详细信息,请参阅 获取 DriveItem 资源。

启动 Office 网页版

当应用应在浏览器中打开 Office 时,请使用 DriveItem webUrl 。

  1. 读取所选文件的 DriveItem。
  2. 确认响应包括 webUrl。
  3. 在浏览器选项卡、窗口或应用控制的导航界面中打开 URL。
  4. 保留应用上下文,以便用户可在编辑后返回。
  5. 通过检查文件权限和容器成员身份来处理拒绝访问错误。

注意

当用户编辑存储在 SharePoint Embedded 中的 Word、Excel 和 PowerPoint 文件时,Office 文件使用自动保存。

配置默认启动体验

默认情况下,Office URL 包含action=default

若要强制模式,请使用以下模式更新查询参数:

System.UriBuilder builder = new System.UriBuilder(webUrl);
System.Collections.Specialized.NameValueCollection queryDictionary = System.Web.HttpUtility.ParseQueryString(builder.Query);
queryDictionary["action"] = "view";
builder.Query = queryDictionary.ToString();
string modifiedWebUrl = builder.ToString();

请使用:

  • action=view 为只读查看。
  • action=edit 在用户具有编辑权限时进行编辑。
  • action=default Office 应选择默认行为时。

有关支持的action值,请参阅 Web 应用程序开放平台接口操作。

在 Office 桌面客户端中打开文件

当应用应直接打开桌面客户端时,请使用 Office URI 方案。

格式为:

<scheme-name>:<command-name>|<command-argument-descriptor>|<command-argument>

常见值包括:

用户群 值
方案名称 ms-word、 或 ms-excelms-powerpoint
“打开文件视图”命令 ofv
“打开文件”“编辑”命令 ofe
URL 描述符 u

示例:

ms-word:ofv|u|https://contoso.com/document.docx
ms-powerpoint:ofe|u|https://contoso.com/presentation.pptx

注意

在空白窗口或新选项卡中打开 URI。

生成桌面客户端 URL

由于指向用于 Office 文档的 Office Online,因此 webUrl 通过两个步骤构建桌面 URI:

  1. 获取父文件夹的 。webUrl
  2. 追加文件名。

示例模式:

ms-word:ofe|u|{folder.WebUrl}/{item.Name}

生成的形状:

ms-word:ofe|u|https://contoso.sharepoint.com/contentstorage/CSP_1234765465/Document%20Library/MyDocument.docx

有关方案的详细信息,请参阅 Office URI 方案。

配置重定向行为

当 Microsoft 365 无法在受支持的查看器中打开文件时,使用重定向设置将用户路由回应用。

ApplicationRedirectUrl 在容器类型上配置应用程序重定向 URL。 将其用于处理工作负载的文件返回方案的应用路由。

该 urlTemplate 设置控制 Microsoft 365 将用户发送到何处以获取没有受支持查看器的文件。 受支持的 Office Web 查看器文件(如 Word、Excel 和 PowerPoint)在 Office Web 查看器中打开。 PDF 文件在嵌入查看器中打开。 其他文件类型在配置时重定向。urlTemplate 如果未配置,则 urlTemplate Microsoft 365 会将用户发送到 Microsoft 帮助页面。

使用 Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} API 设置settings.urlTemplate。 使用不会解析为环回地址的有效绝对 https:// URL。

PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}
Content-Type: application/json

{
  "settings": {
    "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}"
  }
}

Microsoft 365 解析支持的令牌,对其值进行 URL 编码,并将其替换到模板中。 例如,支持的令牌可以包括 {tenant-id}、 、 {drive-id}{folder-id}{item-id}、 {site-domain}{list-id}{site-url}、 和 。

当应用收到 urlTemplate 重定向时,对用户进行身份验证,分析令牌值,然后使用 Microsoft Graph 检索文件。 如果需要规范文件 URL,请使用 DriveItem webDavUrl 属性而不是 webUrl。

从容器自定义属性添加自定义令牌

除了内置令牌之外,还可以根据容器上的自定义属性定义自己的urlTemplate令牌。 在自定义属性上设置为 isPatternToken , true 使其名称可用作令牌,解析为该属性的值,与 Microsoft 365 解析内置令牌的方式相同。

使用 Microsoft Graph PATCH /storage/fileStorage/containers/{containerId}/customProperties API 添加或更新自定义属性。 有关请求和响应的详细信息,请参阅 将自定义属性添加到 fileStorageContainer 和 更新 fileStorageContainer 的自定义属性。

PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containers/{containerId}/customProperties
Content-Type: application/json

{
  "projectId": {
    "value": "c5d88310-1fc7-49be-80ca-e7d7a11e638b",
    "isPatternToken": true
  }
}

设置自定义属性后,像引用任何其他令牌一样引用它 urlTemplate ,例如 https://app.contoso.com/open?t={tenant-id}&i={item-id}&p={projectId}。

请记住这些约束:

  • 自定义属性名称不能以 vti_ 开头或包含 |.
  • 模式令牌值必须为 GUID、整数、布尔值或编码项 ID。 设置为 时,会拒绝isPatternTokentrue其他值类型。
  • 如果容器没有模式令牌属性的值,Microsoft 365 将从解析的 URL 中删除该令牌,而不是使其保持未解析状态,就像处理其他未填充的可选令牌的相同方式。

设计重定向时:

  • 为应用使用稳定的生产 URL。
  • 仅将开发 URL 用于本地或试用工作。
  • 使 Microsoft Entra ID 重定向 URI 与应用路由保持一致。
  • 验证用户是否在执行 Office 操作后返回到正确的应用内上下文。
  • 避免 URL 重写删除了必需的 Office 查询参数。
  • 更新后验证 urlTemplate ,因为无效值存储为 null.

支持共享和共同创作

Office 体验包括协作功能。

用户可以共享文档、创建可共享链接、实时共同创作、查看状态指示器、使用批注,并在支持的情况下使用提及。

当用户创建共享链接时,他们选择向谁授予访问权限:

共享范围 谁可以使用链接
任何人 接收链接的任何人,包括组织外部的人员,无论你直接发送还是转发链接。
组织中的人员 组织中具有链接(无论是直接发送还是转发)的任何人。
特定人员 仅你指定的人员。 如果转发邀请,则只有已具有访问权限的人员才能使用该链接。
现有访问权限者 已有权访问文件或文件夹的 People。 此作用域不会更改现有权限。

注意

提及要求目标用户分配 Microsoft 365 许可证。 提及仅限于使用租户组织内的人员,并在多租户设置中排除来自其他租户的来宾和用户。

使用版本历史记录

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

用户可以查看更改、比较版本、还原以前的版本、从错误中恢复以及查看共同创作会话中的更改。

使用痕迹导航属性

Office 客户端可以显示痕迹导航样式的元素,这些元素将 Office 文件与应用程序相关联。

痕迹导航模式是根据为应用配置的容器属性构建的。

使用 Microsoft 365 应用版的当前频道更新频道,以便用户获得最新的 Office 痕迹导航行为和未来的 Office 应用增强功能。

有关 Office 更新频道信息,请参阅 Microsoft 365 应用版更新频道概述。

验证 Office 启动

测试每个启动路径:

  1. 将 Word 文档上传到容器。
  2. 读取 DriveItem 并捕获 webUrl。
  3. 打开 webUrl 方式 action=default.
  4. 将查询字符串修改为 action=view.
  5. 将查询字符串修改为 action=edit.
  6. 为桌面启动构建 Office URI 方案。
  7. 确认权限,适当时阻止编辑。
  8. 确认自动保存和版本历史记录行为。
  9. 确认用户可以返回你的应用。

Office 启动疑难解答

症状 支票
URL 在视图中打开,而不是在编辑中打开 action 参数和用户编辑权限。
桌面客户端打不开 Office URI 方案、浏览器策略和新选项卡行为。
用户无法共同创作 文件类型、权限和 Office 客户端支持。
提及找不到用户 Microsoft 365 许可证和租户成员资格限制。
痕迹导航看起来不正确 容器属性和 Office 更新频道。
重定向返回到错误的路由 ApplicationRedirectUrl 和应用路由处理。
Office 网页版或 Office 桌面客户端无法打开文件 通过 确认isOfficeRestricted未为容器类型禁用 Office 集成,然后检查用户的文件权限和现有的客户端特定启动要求。

后续步骤

在 应用中的预览文件中添加嵌入式预览。