Добавление функций предварительного просмотра и открытия, а также действий в файлы с помощью обработчиков файлов версии 2.0
Обработчики файлов — это тип надстройки Microsoft 365, который интегрирует пользовательские типы файлов в службу, обеспечивая широкие возможности для любого специального формата.
С помощью обработчиков файлов вы можете включить указанные ниже пользовательские интерфейсы в OneDrive для бизнеса и в библиотеках документов SharePoint:
- Пользовательские значки файлов (для файлов с защищаемыми расширениями)
- Создание файлов в браузере (для файлов с защищаемыми расширениями)
- Предварительный просмотр файлов (для файлов с защищаемыми расширениями)
- Расширенные функции просмотра и редактирования (для файлов со всеми расширениями)
- Дополнительные действия, запускаемые в вашем приложении (для файлов со всеми расширениями)
- Поддержка выбора нескольких элементов и действий над папками (только для дополнительных действий)
Дополнительные сведения см. в статье Примеры решений для обработчиков файлов.
Важно!
Агрессивное кэширование конфигураций обработчиков файлов выполняется во всей системе для оптимальной производительности. Чтобы изменения конфигурации вступили в силу, может потребоваться 24–48 часов. Сведения о настройке обработчиков файлов см. в статье Регистрация.
Изменения обработчиков файлов версии 2.0
Обновление до версии 2.0 для обработчиков файлов позволяет использовать дополнительные сценарии для SharePoint Online и OneDrive для бизнеса.
- С помощью API Microsoft Graph вы можете более надежно получать доступ к файлам, в том числе к метаданным файлов, разрешениям и функциям предоставления общего доступа.
- Вы можете добавить пользовательские кнопки, запускающие вашу надстройку с обработчиком файлов, с настраиваемым текстом и значками.
Компоненты, из которых состоит обработчик файлов
Обработчик файлов состоит из указанных ниже компонентов.
- Конечная точка обработчика файлов. Размещаемое у поставщика услуг приложение, включающее пользовательский интерфейс вашего обработчика файлов. Кроме того, эта конечная точка может предоставлять пользовательский интерфейс для функций создания, предварительного просмотра и редактирования файлов, зарегистрированных в вашем обработчике файлов.
- Манифест обработчика файлов. Набор метаданных, который определяет порядок взаимодействия между Office 365 и конечной точкой вашего обработчика файлов.
- Приложение, зарегистрированное в Azure Active Directory. Это приложение используется для авторизации доступа к выбранным файлам с помощью Microsoft Graph и является местом регистрации манифеста обработчика файлов.
Конечная точка обработчика файлов
Конечная точка обработчика файлов — это размещенное в облаке приложение, которое содержит функциональную логику для создания, предварительного просмотра, открытия и сохранения файлов типа, который он обрабатывает. Он может размещаться в любом стеке, включая стеки сторонних специалистов. Обработчики файлов используют Azure Active Directory для получения авторизованного доступа к Office 365 ресурсам, поэтому приложение необходимо зарегистрировать в Azure AD. Дополнительные сведения о регистрации приложения с помощью Azure AD см. в статье Регистрация приложения для Microsoft Graph.
Законченные примеры обработчика файлов см. в списке доступных примеров.
Манифест обработчика файлов
Манифест определяет взаимодействие между Office 365 и конечной точкой обработчика файлов. Манифест регистрируется в Azure Active Directory с помощью коллекции addIns для объекта приложения в каталоге. Сведения о регистрации или обновлении регистрации манифеста обработчика файлов см. в статье Практическое руководство. Регистрация обработчика файлов вручную.
Вот пример манифеста обработчика файлов:
{
"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 | Строка | Указывает версию обработчика файлов. Это значение должно быть равно 2. Обязательное свойство для обработчиков файлов версии 2.0. |
| appIcon | Зашифрованная строка в формате JSON | Коллекция URL-адресов значков в разных форматах, используемых для представления приложения с обработчиком файлов. Необязательный параметр. |
| fileTypeDisplayName | Строка | Описание языкового стандарта, используемого по умолчанию, для типа файлов. Необязательный параметр. |
| fileTypeIcon | Зашифрованная строка в формате JSON | Коллекция URL-адресов значков в разных форматах, используемых для представления типов файлов, для которых предназначен этот обработчик. Необязательный параметр. |
| actionMenuDisplayName | String | Необязательный параметр. Отображаемая строка для языкового стандарта по умолчанию, используемая при сворачивании действий, связанных с этим обработчиком файлов, в меню. |
| actions | Строка в закодированном формате JSON | Коллекция действий, реализованных этим расширением обработчика файлов. Дополнительные сведения см. в разделе Указание действий . Обязательно. |
Обработчики файлов в среде выполнения
Для вызова надстройки обработчика файлов используется URL-адрес конечной точки, указанный в манифесте обработчика файлов для вызванного действия. Чтобы понять, что произошло, рассмотрим сценарий, в котором пользователь щелкает файл, чтобы просмотреть его. Если имеется зарегистрированный обработчик файлов этого типа, Office 365 вызывает приложение обработчика файлов, отправив запрос POST на URL-адрес, указанный для действия предварительного просмотра. Office 365 включит параметры активации, указывающие выбранный файл, в текст запроса POST. Другие действия, включая newFile, open и custom, можно вызвать таким же способом.
Параметры активации
В предыдущих сценариях приложению обработчика файлов требуются сведения, называемые параметрами активации, о файле, клиенте, клиенте Office 365 клиенте и т. д., чтобы работать с выбранным файлом.
Office 365 включает эти сведения в виде данных формы, отправляемых в запросе POST к конечной точке обработчика файлов, связанной с действием пользователя.
Эти параметры включаются в запрос с типом application/x-www-form-urlencoded MIME, а URL-адрес закодирован в тексте запроса.
Среди параметров активации имеются указанные ниже параметры.
| Имя параметра | Тип | Описание |
|---|---|---|
| cultureName | строка | Идентификатор языкового стандарта для текущего языка интерфейса пользователя. |
| client | строка | Приложение Office 365, из которого был вызван обработчик файла, например SharePoint или OneDrive. |
| userId | string | Имя участника-пользователя или электронный адрес для входа пользователя, вызвавшего обработчик файлов. |
| domainHint | string | Строка подсказки домена, указывающая organizations или consumers. |
| items | Коллекция строк JSON с URL-адресами | Коллекция URL-адресов Microsoft Graph для выбранных элементов. |
Эти значения закодированы в запросе 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-адреса, возвращаемые в коллекции элементов, могут быть очень длинными (но меньше максимальной длины URL-адреса — 2048 символов). В каждый URL-адрес встроен маркер, позволяющий приложению обработчика файлов получать доступ к содержимому без области разрешений с полным доверием. Однако следует гарантировать, что конечная точка обработчика файлов рассчитана на возврат длинных URL-адресов и корректно обрабатывает их.
Разработчики ASP.NET могут получать доступ к этим значениям с помощью коллекции Request.Form. Пример:
var itemsJson = Request.Form["items"];
var itemUrls = JsonConvert.DecodeObject<string[]>(items);
При получении запроса следует выполнить кэширование параметров активации, используя либо кэш на сервере, либо файлы cookie в ответе. При выполнении начального запроса обработчика файлов приложению обработчика файлов может потребоваться перенаправить пользователя для получения маркера доступа в пользовательском интерфейсе OAuth2 Azure Active Directory. Если не сохранить параметры активации до этого перенаправления, они будут потеряны.
Вы можете изучить пример использования объекта модели данных и метода обработчика для кэширования параметров активации в файле cookie, перейдя по ссылке ниже на статью с примерами решений для C# и TypeScript.
Примеры решений для обработчика файлов
Эффективная проверка подлинности с помощью обработчиков файлов версии 2.0
После того как ваш обработчик файлов получит запрос с параметрами активации, ему потребуется получить маркер доступа, чтобы совершать вызовы API к Microsoft Graph.
Чтобы получить маркер доступа для вошедшего пользователя, приложению потребуется вызвать конечную точку проверки подлинности Azure Active Directory.
Чтобы включить функцию единого входа и не предлагать пользователю выбрать учетную запись, вы можете использовать параметр login_hint и указать значение параметра активации userId.
В некоторых случаях обработчик файлов может предложить пользователю войти.
Если обработчик файлов выполняется в качестве действия preview, то перенаправить интерфейс входа в объект IFRAME не удастся. Вам потребуется создать всплывающее окно входа для обработчика файлов.
Доступность обработчика файлов
В таблице ниже перечислены службы Office 365, поддерживающие обработчики файлов.
| Имя службы | Обработчики файлов версии 2.0 | Обработчики файлов версии 1.0 |
|---|---|---|
| SharePoint Online | Общедоступная | Общедоступная версия |
| OneDrive для бизнеса | Общедоступная версия | Общедоступная версия |
| OneDrive персональный | Недоступно | Недоступно |
| Outlook Web App | Недоступна | Общедоступная |