Добавление функций предварительного просмотра и открытия, а также действий в файлы с помощью обработчиков файлов версии 2.0Adding 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 для бизнеса и в библиотеках документов 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.0What's new with file handlers 2.0

Обновление до версии 2.0 для обработчиков файлов позволяет использовать дополнительные сценарии для SharePoint Online и OneDrive для бизнеса.The 2.0 upgrade to file handlers enables additional scenarios for SharePoint Online and OneDrive for Business.

  • С помощью API Microsoft Graph вы можете более надежно получать доступ к файлам, в том числе к метаданным файлов, разрешениям и функциям предоставления общего доступа.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

Конечная точка обработчика файлов представляет собой размещаемое в облаке приложение, которое содержит функциональную логику для создания, предварительного просмотра, открытия и сохранения файлов с типами, с которыми работает обработчик файлов. Ее можно разместить в любом стеке (не только в стеке Майкрософт). Обработчики файлов используют Azure Active Directory для получения авторизованного доступа к ресурсам Office 365, поэтому необходимо зарегистрировать ваше приложение в Azure AD. Дополнительные сведения о регистрации приложения в Azure AD см. в статье Регистрация приложения для работы с Microsoft Graph.The 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.

Полномасштабный пример обработчика файлов см. в статье об обработчике файлов Markdown на GitHub.For a complete example of a file handler, see the Markdown-FileHandler on GitHub.

Манифест обработчика файловFile handler manifest

Манифест определяет порядок взаимодействия между Office 365 и конечной точкой обработчика файлов. Манифест зарегистрирован в Azure Active Directory с использованием коллекции addIns для объекта приложения в каталоге. Сведения о том, как зарегистрировать манифест обработчика файлов или обновить его регистрацию, см. в статье Практическое руководство. Регистрация обработчика файлов вручную.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 Зашифрованная строка в формате 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 Зашифрованная строка в формате 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 Зашифрованная строка в формате 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 вызывает приложение обработчика файлов, отправив запрос POST на URL-адрес, указанный для действия предварительного просмотра. Office 365 включит параметры активации, указывающие выбранный файл, в текст запроса POST. Другие действия, включая newFile, open и custom, можно вызвать таким же способом.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 и т. д., называемые параметрами активации. Они были нужны для работы с выбранным файлом. Office 365 включает эти сведения в качестве данных формы, отправляемых в запросе POST в конечную точку обработчика файлов, сопоставленную с действием пользователя. Эти параметры включаются в запрос с типом 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 строкаstring Идентификатор языкового стандарта для текущего языка интерфейса пользователя.The locale identifier for the user's current display language.
clientclient строкаstring Приложение Office 365, из которого был вызван обработчик файла, например SharePoint или OneDrive.The Office 365 application from which the file handler was invoked; for example "SharePoint" or "OneDrive".
userIduserId stringstring Имя участника-пользователя или электронный адрес для входа пользователя, вызвавшего обработчик файлов.The AAD object ID for the user who has invoked the file handler.
domainHintdomainHint stringstring Строка подсказки домена, указывающая organizations или consumers.A domain hint string that indicates either organizations or consumers.
itemsitems Коллекция строк JSON с URL-адресамиJSON string collection of URLs Коллекция URL-адресов Microsoft Graph для выбранных элементов.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-адреса, возвращаемые в коллекции элементов, могут быть очень длинными (но меньше максимальной длины URL-адреса — 2048 символов).Note: The URLs returned in the items collection may be very long (but less than the maximum URL length of 2048 characters). В каждый 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 в ответе. При выполнении начального запроса обработчика файлов приложению обработчика файлов может потребоваться перенаправить пользователя для получения маркера доступа в пользовательском интерфейсе OAuth2 Azure Active Directory. Если не сохранить параметры активации до этого перенаправления, они будут потеряны.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.

Вы можете изучить пример использования объекта модели данных и метода обработчика для кэширования параметров активации в файле cookie в статье с примером обработчика файлов Markdown.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.0Seamless authentication with file handlers 2.0

После того как ваш обработчик файлов получит запрос с параметрами активации, ему потребуется получить маркер доступа, чтобы совершать вызовы API к Microsoft Graph. Чтобы получить маркер доступа для пользователя, вошедшего в систему, приложению потребуется вызвать конечную точку аутентификации 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 ОбщедоступнаяGenerally available (GA) Общедоступная версияGA
OneDrive для бизнесаOneDrive for Business Общедоступная версияGA Общедоступная версияGA
OneDrive персональныйOneDrive personal НедоступноNot available НедоступноNot available
Outlook Web AppOutlook Web App НедоступнаNot available ОбщедоступнаяGA