使用文件处理程序 2.0 向文件添加 custom、preview 和 open 等操作

项目
04/08/2023

文件处理程序是一种 Microsoft 365 加载项，可以将自定义文件类型集成到服务中，允许你使用任何文件格式。

使用文件处理程序，可以在 OneDrive for Business 和 SharePoint 文档库中获得以下用户体验：

自定义文件图标（适用于专有文件扩展名）
在浏览器中新建文件（适用于专有文件扩展名）
文件预览（适用于专有文件扩展名）
丰富的查看/编辑功能（所有文件扩展名）
可以在应用内使用自定义操作（所有文件扩展名）
支持多重选择和对文件夹执行操作（仅限自定义操作）

有关其他详细信息，请查看文件处理程序解决方案示例。

重要

文件处理程序配置在整个系统中主动进行缓存，以获得最佳性能。任何配置更改可能需要24-48 小时才会生效。有关如何配置文件处理程序的信息，请参阅正在注册。

文件处理程序 2.0 的更改内容

升级到文件处理程序 2.0 后，可以完成其他 SharePoint Online 和 OneDrive for Business 方案。

使用 Microsoft Graph API 更可靠地访问文件，包括文件元数据、权限和共享内容。
添加包含自定义文本和图标的自定义操作按钮，用于启动文件处理程序外接程序。

文件处理程序的组成

文件处理程序由以下部分组成：

文件处理程序终结点。提供程序托管的应用，可提供文件处理程序体验。此终结点可以视需要提供创建、预览和编辑已向文件处理程序注册的文件的体验。
文件处理程序清单。一组定义 Office 365 和文件处理程序终结点之间交互的元数据。
在 Azure Active Directory 中注册的应用。此应用用于授予通过 Microsoft Graph 访问选定文件的权限，同时也是文件处理程序清单的注册位置。

文件处理程序终结点

文件处理程序终结点是包含功能逻辑的云托管应用，用于创建、预览、打开和保存所处理类型的文件。它可以托管在任何堆栈上，包括非 Microsoft 堆栈。文件处理程序使用 Azure Active Directory 获取对 Office 365 资源的授权访问权限，因此必须向 Azure AD 注册应用。若要详细了解如何向 Azure AD 注册应用，请参阅注册应用以连接 Microsoft Graph。

有关文件处理程序的完整示例，请参阅可用样本列表。

文件处理程序清单

此清单定义了 Office 365 和文件处理程序终结点之间的交互。使用目录中应用对象的 addIns 集合向 Azure Active Directory 注册此清单。若要注册文件处理程序清单或更新注册，请参阅如何：手动注册文件处理程序。

示例文件处理程序清单：

{
    "id": "guid",
    "type": "FileHandler",
    "properties": [
        { "key": "version", "value": "2" },
        { "key": "appIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "fileTypeDisplayName", "value": "Contoso Document File" },
        { "key": "fileTypeIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "actionMenuDisplayName", "value": "Contoso Actions" },
        { "key": "actions", "value": "json" }
    ]
}

每个文件处理程序清单在 properties 数组中均包含以下键值对：

属性名	类型	说明
version	String	指定文件处理程序的版本。必须将此值设置为 `2`。对于文件处理器 2.0，此为必需属性。
appIcon	String, encoded JSON	用于表示文件处理程序应用程序的不同格式的图标 URL 集合。可选。
fileTypeDisplayName	String	文件类型的默认区域设置说明。可选。
fileTypeIcon	String, encoded JSON	用于表示此文件处理程序处理的文件类型的不同格式的图标 URL 集合。可选。
actionMenuDisplayName	String	可选。与此文件处理程序相关联的操作折叠到一个菜单时在默认区域设置中使用的显示字符串。
actions	String, encoded JSON	此文件处理程序扩展实现的一组操作。有关详细信息，请参阅指定操作。必填。

运行时的文件处理程序

文件处理程序外接程序通过已调用操作的文件处理程序清单中指定的终结点 URL 进行调用。为了解所发生的具体情况，我们来看看用户单击以预览文件这一方案。如果此文件类型对应有已注册的文件处理程序，Office 365 会向 preview 操作的指定 URL 发出 POST 请求，从而调用文件处理程序应用。在 POST 请求正文中，Office 365 会添加指定选定文件的激活参数。其他操作（包括 newFile、open 和 custom）的调用方式也相同。

激活参数

在上面的方案中，文件处理程序应用需要获取关于文件、租户、Office 365 客户端等的详细信息（称为“激活参数”），才能处理选定文件。在向与用户操作关联的文件处理程序终结点发出的 POST 请求中，Office 365 将这些详细信息添加为表单数据。这些参数包含在 MIME 类型为 application/x-www-form-urlencoded 的请求中，并在请求正文中进行 URL 编码。

激活参数如下：

参数名称	类型	说明
cultureName	string	用户的当前显示语言的区域设置标识符。
client	string	从中调用文件处理程序的 Office 365 应用（例如，“SharePoint”或“OneDrive”）。
userId	string	已调用文件处理程序的用户的 UPN/登录电子邮件。
domainHint	string	指示 `organizations` 或 `consumers` 的域提示字符串。
items	JSON string collection of URLs	选定项的 Microsoft Graph URL 集合。

这些值在 POST 请求中编码成表单值。

下面的示例展示了向文件处理程序终结点发送的请求：

POST https://contoso.com/_api/filehandlers/preview
Content-Type: application/x-www-form-urlencoded

cultureName=en-us&client=OneDrive&userId=rgregg%40contoso.com&items=%5B%22https%3A%2F%2Fgraph.microsoft.com%2Fv1.0%2Fme%2Fdrive%2Fitems%2F4D679BEA-6F9B-4106-AB11-101DDE52B06E%22%5D

注意：在项集合中返回的 URL 可能会非常长（但小于 2048 个字符的最大 URL 长度）。每个 URL 都包含一个嵌入在 URL 中的令牌，该令牌允许文件处理程序应用程序访问内容，而无需完全信任权限范围。但是，文件处理程序终结点应该确保返回长 URL 并正确处理它们。

对于 ASP.NET 开发者，可以使用 Request.Form 集合访问这些值，例如：

var itemsJson = Request.Form["items"];
var itemUrls = JsonConvert.DecodeObject<string[]>(items);

应在请求传入时，使用服务器端缓存或通过响应上的 Cookie 缓存激活参数。对于初始文件处理程序请求，文件处理程序应用可能需要重定向用户，以通过 Azure Active Directory OAuth2 体验检索 accessToken。如果在此重定向发生前未进行保存，激活参数将会丢失。

可以查看解决方案示例下方链接的C#或Typesript示例，了解如何使用数据模型对象和处理程序方法在cookie中缓存激活参数。

文件处理程序解决方案示例

文件处理程序 2.0 的无缝身份验证

收到包含激活参数的请求后，文件处理程序需要检索访问令牌，才能对 Microsoft Graph 发出 API 调用。应用需要调用 Azure Active Directory 身份验证终结点来检索登录用户的访问令牌。若要启用单一登录（以免提示用户选择帐户），可以使用 login_hint 参数，并提供 userId 激活参数的值。

在某些情况下，文件处理程序可能需要提示用户登录。如果文件处理程序作为 preview 操作运行，你将无法重定向到 IFRAME 内部的登录体验，并且将需要为文件处理程序弹出登录体验窗口。

文件处理程序可用性

下表列出了支持文件处理程序的 Office 365 服务。

服务名称	文件处理程序 2.0	文件处理程序 1.0
SharePoint Online	通用版 (GA)	GA
OneDrive for Business	GA	GA
OneDrive 个人版	不可用	不可用
Outlook Web App	不适用	GA

通过