使用文件处理程序 2.0 向文件添加 custom、preview 和 open 等操作Adding custom preview, open, and actions to files with File Handlers 2.0

文件处理程序是一种 Office 外接程序,可将自定义文件类型集成到 Office 365 中,就像集成 Office 文件类型一样。File handlers are a type of Office add-in that integrate custom file types into Office 365 the same way that Office file types are.

使用文件处理程序,可以在 OneDrive for Business 和 SharePoint 文档库中提供以下用户体验:With file handlers, you can enable the following user experiences in OneDrive for Business and SharePoint document libraries:

  • 自定义文件图标(适用于专有文件扩展名)Customized file icons (for proprietary file extensions)
  • 在浏览器中新建文件(适用于专有文件扩展名)Create new files in the browser (for proprietary file extensions)
  • 文件预览(适用于专有文件扩展名)File preview (for proprietary file extensions)
  • 丰富的查看/编辑功能(所有文件扩展名)Rich view/edit capability (all file extensions)
  • 可以在应用内使用自定义操作(所有文件扩展名)Custom actions that launch into your app (all file extensions)
  • 支持多重选择和对文件夹执行操作(仅限自定义操作)Support multiple selection and acting on folders (custom actions only)

有关详细信息,请参阅 Markdown 文件处理程序示例项目Check out the Markdown File Handler example project for more specifics.

文件处理程序 2.0 的更改内容What's new with file handlers 2.0

升级到文件处理程序 2.0 后,可以完成其他 SharePoint Online 和 OneDrive for Business 方案。The 2.0 upgrade to file handlers enables additional scenarios for SharePoint Online and OneDrive for Business.

  • 使用 Microsoft Graph API 更可靠地访问文件,包括文件元数据、权限和共享内容。Use Microsoft Graph API for more robust access to files, including file metadata, permissions, and sharing.
  • 添加包含自定义文本和图标的自定义操作按钮,用于启动文件处理程序外接程序。Add custom action buttons that launch your file handler add-in, with custom text and icons.

文件处理程序的组成What's in a file handler

文件处理程序由以下部分组成:A file handler is comprised of the following components:

  • 文件处理程序终结点。 提供程序托管的应用,可提供文件处理程序体验。 此终结点可以视需要提供创建、预览和编辑已向文件处理程序注册的文件的体验。File handler endpoint. A provider-hosted app that enables the experience of your file handler. This end point can optionally provide an experience for creating, previewing, and editing files that are registered with your file handler.
  • 文件处理程序清单。 一组定义 Office 365 和文件处理程序终结点之间交互的元数据。File handler manifest. A set of metadata that defines the interaction between Office 365 and your file handler endpoint.
  • 在 Azure Active Directory 中注册的应用。 此应用用于授予通过 Microsoft Graph 访问选定文件的权限,同时也是文件处理程序清单的注册位置。Application registered in Azure Active Directory. This application is used to authorize your access to selected files via Microsoft Graph, and is where the file handler manifest is registered.

文件处理程序终结点File handler endpoint

文件处理程序终结点是包含功能逻辑的云托管应用,用于创建、预览、打开和保存所处理类型的文件。 它可以托管在任何堆栈上,包括非 Microsoft 堆栈。 文件处理程序使用 Azure Active Directory 获取对 Office 365 资源的授权访问权限,因此必须向 Azure AD 注册应用。 若要详细了解如何向 Azure AD 注册应用,请参阅注册应用以连接 Microsoft GraphThe file handler endpoint is a cloud-hosted app that contains the functional logic for creating, previewing, opening, and saving files of the type that it handles. It can be hosted on any stack, including non-Microsoft stacks. File handlers uses Azure Active Directory to gain authorized access to Office 365 resources, so your application needs to be registered with Azure AD. For more information about registering an application with Azure AD, see Registering your app for Microsoft Graph.

有关文件处理程序的完整示例,请参阅 GitHub 上的 Markdown-FileHandlerFor a complete example of a file handler, see the Markdown-FileHandler on GitHub.

文件处理程序清单File handler manifest

此清单定义了 Office 365 和文件处理程序终结点之间的交互。 使用目录中应用对象的 addIns 集合向 Azure Active Directory 注册此清单。 若要注册文件处理程序清单或更新注册,请参阅如何:手动注册文件处理程序The manifest defines the interaction between Office 365 and the file handler endpoint. The manifest is registered with Azure Active Directory, using the addIns collection for an application object in the directory. To register or update the registration for your file handler manifest, see How to: Register a file handler manually.

示例文件处理程序清单:An example file handler manifest:

{
    "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 数组中均包含以下键值对:Each file handler manifest includes the following key-value pairs as part of the properties array:

属性名Property Name 类型Type 说明Description
versionversion StringString 指定文件处理程序的版本。 必须将此值设置为 2。 对于文件处理器 2.0,此为必需属性。Specify the version of the file handler. This value must be set to 2. Required for file handlers 2.0.
appIconAppIcon String, encoded JSONString, encoded JSON 用于表示文件处理程序应用程序的不同格式的图标 URL 集合。A collection of icon URLs in different formats that are used to represent the file handler application. 可选。Optional.
fileTypeDisplayNamefileTypeDisplayName StringString 文件类型的默认区域设置说明。 可选。The default locale description for the file type. Optional.
fileTypeIconfileTypeIcon String, encoded JSONString, encoded JSON 用于表示此文件处理程序处理的文件类型的不同格式的图标 URL 集合。A collection of icon URLs in different formats that are used to represent file types handled by this file handler. 可选。Optional.
actionMenuDisplayNameactionMenuDisplayName StringString 可选。Optional. 与此文件处理程序相关联的操作折叠到一个菜单时在默认区域设置中使用的显示字符串。A display string in the default locale that is used when the actions associated with this file handler are collapsed into a menu.
actionsactions String, encoded JSONString, encoded JSON 此文件处理程序扩展实现的一组操作。 有关详细信息,请参阅指定操作。 必需。A collection of actions implemented by this file handler extension. See specifying actions for more information. Required.

运行时的文件处理程序File handlers at runtime

文件处理程序外接程序通过已调用操作的文件处理程序清单中指定的终结点 URL 进行调用。 为了解所发生的具体情况,我们来看看用户单击以预览文件这一方案。 如果此文件类型对应有已注册的文件处理程序,Office 365 会向 preview 操作的指定 URL 发出 POST 请求,从而调用文件处理程序应用。 在 POST 请求正文中,Office 365 会添加指定选定文件的激活参数。 其他操作(包括 newFileopencustom)的调用方式也相同。The file handler add-in is invoked via the endpoint URL specified in the file handler manifest for the invoked action. To understand what happens, let's take a look at the scenario where a user clicks to preview a file. If there is a registered file handler for that file type, Office 365 invokes the file handler app by making a POST request to the URL specified for the preview action. In the body of the POST request, Office 365 will include the activation parameters that specify the file that was selected. The other actions, including newFile, open, and custom are invoked the same way.

激活参数Activation parameters

在上面的方案中,文件处理程序应用需要获取关于文件、租户、Office 365 客户端等的详细信息(称为“激活参数”),才能处理选定文件。 在向与用户操作关联的文件处理程序终结点发出的 POST 请求中,Office 365 将这些详细信息添加为表单数据。 这些参数包含在 MIME 类型为 application/x-www-form-urlencoded 的请求中,并在请求正文中进行 URL 编码。In the previous scenarios, your file handler app requires details, called activation parameters, about the file, tenant, Office 365 client, etc., to work with the selected file. Office 365 includes these details as form data sent in the POST request to the file handler endpoint associated with the user's action. These parameters are included in the request with the MIME type application/x-www-form-urlencoded and are URL encoded in the body of the request.

激活参数如下:The following parameters are provided in the activation parameters:

参数名称Parameter Name 类型Type 说明Description
cultureNamecultureName stringstring 用户的当前显示语言的区域设置标识符。The locale identifier for the user's current display language.
clientclient stringstring 从中调用文件处理程序的 Office 365 应用(例如,“SharePoint”或“OneDrive”)。The Office 365 application from which the file handler was invoked; for example "SharePoint" or "OneDrive".
userIdUserId stringstring 已调用文件处理程序的用户的 UPN/登录电子邮件。The AAD object ID for the user who has invoked the file handler.
domainHintdomainHint stringstring 指示 organizationsconsumers 的域提示字符串。A domain hint string that indicates either organizations or consumers.
itemsitems JSON string collection of URLsJSON string collection of URLs 选定项的 Microsoft Graph URL 集合。A collection of Microsoft Graph URLs to the selected item(s).

这些值在 POST 请求中编码成表单值。These values are encoded in the POST request as form values.

下面的示例展示了向文件处理程序终结点发送的请求:Here is an example request that will be sent to the file handler endpoint:

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 长度)。Note: The URLs returned in the items collection may be very long (but less than the maximum URL length of 2048 characters). 每个 URL 都包含一个嵌入在 URL 中的令牌,该令牌允许文件处理程序应用程序访问内容,而无需完全信任权限范围。Each URL contains a token embedded in the URL that allows the file handler app to access the content without a full-trust permission scope. 但是,文件处理程序终结点应该确保返回长 URL 并正确处理它们。However, your file handler endpoint should ensure it expects long URLs to be returned and handles them correctly.

对于 ASP.NET 开发者,可以使用 Request.Form 集合访问这些值,例如:For ASP.NET developers, you can access these values using the Request.Form collection, for example:

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

应在请求传入时,使用服务器端缓存或通过响应上的 Cookie 缓存激活参数。 对于初始文件处理程序请求,文件处理程序应用可能需要重定向用户,以通过 Azure Active Directory OAuth2 体验检索 accessToken。 如果在此重定向发生前未进行保存,激活参数将会丢失。The activation parameters should be cached when the request comes in, either using a server-side cache or via cookies on the response. For the initial file handler request, it's likely that the file handler app will need to redirect the user to retrieve an accessToken via Azure Active Directory OAuth2 experience. The activation parameters will be lost if not persisted before this redirect occurs.

可以参阅 Markdown 文件处理程序示例,了解如何使用数据模型对象和处理程序方法在 Cookie 中缓存激活参数。You can see an example of using a data model object and handler method for caching the activation parameters in a cookie, in the Markdown File Handler sample.

文件处理程序 2.0 的无缝身份验证Seamless authentication with file handlers 2.0

收到包含激活参数的请求后,文件处理程序需要检索访问令牌,才能对 Microsoft Graph 发出 API 调用。 应用需要调用 Azure Active Directory 身份验证终结点来检索登录用户的访问令牌。 若要启用单一登录(以免提示用户选择帐户),可以使用 login_hint 参数,并提供 userId 激活参数的值。After your file handler has received a request with activation parameters, it will need to retrieve an access token to make API calls to Microsoft Graph. Your app will need to call the Azure Active Directory authentication endpoint to retrieve an access token for the signed in user. To enable single sign-on and avoid prompting the user to select an account, you can use the login_hint parameter and provide the value of the userId activation parameter.

在某些情况下,文件处理程序可能需要提示用户登录。In some scenarios, your file handler may need to prompt the user to sign-in. 如果文件处理程序作为 preview 操作运行,你将无法重定向到 IFRAME 内部的登录体验,并且将需要为文件处理程序弹出登录体验窗口。If your file handler is running as a preview action, you cannot redirect to the sign-in experience inside an IFRAME and will need to popup the sign-in experience for your file handler.

文件处理程序可用性File handler availability

下表列出了支持文件处理程序的 Office 365 服务。The following table lists the Office 365 services that support file handlers.

服务名称Service name 文件处理程序 2.0File handlers 2.0 文件处理程序 1.0File handlers 1.0
SharePoint OnlineSharePoint Online 通用版 (GA)Generally available (GA) GAGA
OneDrive for BusinessOneDrive for Business GAGA GAGA
OneDrive 个人版OneDrive personal 不可用Not available 不可用Not available
Outlook Web AppOutlook Web App 不适用Not available GAGA