Добавление функций предварительного просмотра и открытия, а также действий в файлы с помощью обработчиков файлов версии 2.0

Статья
04/08/2023

Обработчики файлов — это тип надстройки 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	Недоступна	Общедоступная

Поделиться через