Открытие файлов Office из приложения

Применимо к: Разработчик

Откройте файлы Office из приложения SharePoint Embedded с помощью метаданных Microsoft Graph DriveItem и шаблонов запуска Office, поддерживаемых Microsoft 365.

Сначала завершите отправку, скачивание и управление файлами, чтобы в приложении были файлы для запуска.

Общие сведения о интерфейсах Office

Интерфейсы sharePoint Embedded Office работают аналогично работе с файлами Microsoft 365. Поддерживаемые возможности:

  • Открытие документов Office в Office для Интернета.
  • Открытие документов Office в классических клиентах Office.
  • Просмотр и редактирование файлов.
  • Автосохранение для файлов Word, Excel и PowerPoint.
  • Журнал версий документов Office.
  • Совместная работа.
  • Ссылки для общего доступа и общего доступа.
  • Комментарии и упоминания с задокументированных ограничений.
  • Навигация в клиентах Office, которые связывают файл с приложением.

Примечание.

Документы, хранящиеся в архивном контейнере, невозможно просмотреть или получить к ней доступ. Приложение должно обрабатывать архивированное состояние, отображая соответствующую ошибку и направляя пользователей на дальнейшие действия, такие как повторная активация контейнера.

Предварительные условия

Перед запуском файлов Office убедитесь, что:

  • Файл хранится в контейнере SharePoint Embedded.
  • Приложение может считывать метаданные DriveItem для файла.
  • Пользователь имеет разрешение на просмотр или изменение файла.
  • Тип файла поддерживается целевым клиентом Office.
  • Приложение обрабатывает перенаправления браузера или поведение нового окна.

Получение URL-адреса веб-сайта DriveItem

Когда приложение получает объект DriveItem из Microsoft Graph, ответ может содержать .webUrl

Для поддерживаемых типов файлов Office указывает НА URL-адрес, webUrl который открывает документ в Office для Интернета.

Поддерживаемый ВЕБ-URL-адрес Office имеет следующий вид:

https://host/:w:r/contentstorage/sitecollection/_layouts/15/doc2.aspx?sourcedoc=guid&file=filename.docx&action=default&mobileredirect=true

Сведения о запросе см. в разделе Получение ресурса DriveItem.

Запуск Office для Интернета

Используйте DriveItem webUrl , когда приложение должно открыть Office в браузере.

  1. Чтение элемента DriveItem для выбранного файла.
  2. Убедитесь, что ответ содержит .webUrl
  3. Откройте URL-адрес на вкладке браузера, окне или в области навигации, управляемой приложением.
  4. Сохраните контекст приложения, чтобы пользователи могли вернуться после редактирования.
  5. Обработка ошибок отказа в доступе путем проверки разрешений файлов и членства в контейнере.

Примечание.

Файлы Office используют автосохранение, когда пользователи редактируют файлы Word, Excel и PowerPoint, хранящиеся в SharePoint Embedded.

Настройка интерфейса запуска по умолчанию

По умолчанию URL-адрес Office содержит .action=default

Чтобы принудительно применить режим, обновите параметр запроса с помощью следующего шаблона:

System.UriBuilder builder = new System.UriBuilder(webUrl);
System.Collections.Specialized.NameValueCollection queryDictionary = System.Web.HttpUtility.ParseQueryString(builder.Query);
queryDictionary["action"] = "view";
builder.Query = queryDictionary.ToString();
string modifiedWebUrl = builder.ToString();

Используйте:

  • action=view для просмотра только для чтения.
  • action=edit для редактирования, если у пользователя есть разрешение на изменение.
  • action=default когда Office должен выбрать поведение по умолчанию.

Поддерживаемые action значения см. в разделе Действия интерфейса открытой платформы веб-приложения.

Открытие файлов в классических клиентах Office

Используйте схемы URI Office, когда приложение должно открывать классические клиенты напрямую.

Используется следующий формат:

<scheme-name>:<command-name>|<command-argument-descriptor>|<command-argument>

Общие значения:

Сегмент Значение
Имя схемы ms-word, ms-excel или ms-powerpoint
Команда "Открыть представление файлов" ofv
Команда "Открыть изменение файла" ofe
Дескриптор URL-адреса u

Примеры:

ms-word:ofv|u|https://contoso.com/document.docx
ms-powerpoint:ofe|u|https://contoso.com/presentation.pptx

Примечание.

Откройте универсальный код ресурса (URI) в пустом окне или на новой вкладке.

Создание URL-адреса клиента рабочего стола

Так как webUrl указывает на документы Office Online для Office, создайте URI рабочего стола в два этапа:

  1. webUrl Получите значение родительской папки.
  2. Добавьте имя файла.

Пример шаблона:

ms-word:ofe|u|{folder.WebUrl}/{item.Name}

Результирующая фигура:

ms-word:ofe|u|https://contoso.sharepoint.com/contentstorage/CSP_1234765465/Document%20Library/MyDocument.docx

Сведения о схеме см. в разделе Схемы URI Office.

Настройка поведения перенаправления

Используйте параметры перенаправления для перенаправления пользователей обратно в приложение, если Microsoft 365 не может открыть файл в поддерживаемом средстве просмотра.

ApplicationRedirectUrl настраивает URL-адрес перенаправления приложения для типа контейнера. Используйте его для маршрута приложения, который обрабатывает сценарии возврата файлов для рабочей нагрузки.

Параметр urlTemplate определяет, где Microsoft 365 отправляет пользователей для файлов без поддерживаемого средства просмотра. Поддерживаемые файлы веб-просмотра Office, такие как Word, Excel и PowerPoint, открываются в веб-средстве просмотра Office. PDF-файлы открываются во встроенном средстве просмотра. Другие типы файлов перенаправляются через urlTemplate , когда он настроен. Если urlTemplate параметр не настроен, Microsoft 365 отправляет пользователей на страницу справки Майкрософт.

Задайте settings.urlTemplate с помощью API Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} . Используйте допустимый абсолютный https:// URL-адрес, который не разрешается в адрес замыкания на себя.

PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}
Content-Type: application/json

{
  "settings": {
    "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}"
  }
}

Microsoft 365 разрешает поддерживаемые маркеры, URL-адрес кодирует их значения и подставляет их в шаблон. Например, поддерживаемые маркеры могут включать {tenant-id}, {drive-id}, {folder-id}, {item-id}, {site-domain}, {list-id}и {site-url}.

Когда приложение получает перенаправление urlTemplate , выполните проверку подлинности пользователя, выполните синтаксический анализ значений маркеров и используйте Microsoft Graph для получения файла. Если вам нужен канонический URL-адрес файла, используйте свойство DriveItem webDavUrl вместо webUrl.

При разработке перенаправлений:

  • Используйте стабильный РАБОЧИЙ URL-адрес для приложения.
  • Используйте URL-адреса разработки только для локальной или пробной работы.
  • Используйте Microsoft Entra ID URI перенаправления в соответствии с маршрутами приложений.
  • Убедитесь, что пользователи возвращаются в правильный контекст в приложении после действий Office.
  • Избегайте перезаписи URL-адресов, которые удаляют необходимые параметры запроса Office.
  • Проверьте urlTemplate после обновления, так как недопустимые значения хранятся как null.

Поддержка совместного доступа и совместного редактирования

Возможности Office включают функции совместной работы.

Пользователи могут делиться документами, создавать ссылки для общего доступа, совместно использовать соавторов в режиме реального времени, просматривать индикаторы присутствия, использовать комментарии и упоминания там, где они поддерживаются.

Когда пользователь создает ссылку для общего доступа, он выбирает, кому она предоставляет доступ:

Совместное использование область Кто может использовать ссылку
Все Любой, кто получает ссылку, включая людей за пределами вашей организации, независимо от того, отправляете ли вы ее напрямую или пересылаете.
Сотрудники организации Любой пользователь вашей организации, у которого есть ссылка, как отправленная напрямую, так и пересылаемая.
Определенные пользователи Только указанные вами люди. Если приглашение переадресовано, ссылку могут использовать только пользователи, у которых уже есть доступ.
Пользователи с существующим доступом People, у которых уже есть доступ к файлу или папке. Это область не изменяет существующие разрешения.

Примечание.

Для упоминаний требуется, чтобы целевым пользователям была назначена лицензия Microsoft 365. Упоминания ограничиваются пользователями в организации потребляющего клиента и исключают гостей и пользователей из других клиентов в параметрах мультитенантной поддержки.

Использование журнала версий

Управление версиями автоматически включается для файлов Word, Excel и PowerPoint, хранящихся в приложениях SharePoint Embedded.

Пользователи могут просматривать изменения, сравнивать версии, восстанавливать предыдущие версии, восстанавливать ошибки и просматривать изменения из сеансов совместного редактирования.

Использование свойств навигации

Клиенты Office могут отображать элементы в стиле навигации, которые связывают файлы Office с приложением.

Шаблоны навигации создаются на основе свойств контейнера, настроенных для вашего приложения.

Используйте канал обновления текущего канала для Приложения Microsoft 365, чтобы пользователи получали последние возможности навигации Office и будущие улучшения приложений Office.

Сведения о каналах обновления Office см. в статье Обзор каналов обновления для Приложения Microsoft 365.

Проверка запуска Office

Протестируйте каждый путь запуска:

  1. Отправьте документ Word в контейнер.
  2. Считайте DriveItem и запишите webUrl.
  3. Откройте webUrl с помощью action=default.
  4. Измените строку запроса на action=view.
  5. Измените строку запроса на action=edit.
  6. Создание схемы URI Office для запуска классических приложений.
  7. При необходимости подтвердите изменение блока разрешений.
  8. Подтвердите поведение автосохранений и журнала версий.
  9. Убедитесь, что пользователь может вернуться в приложение.

Устранение неполадок при запуске Office

Признак Проверка
URL-адрес открывается в представлении вместо редактирования action параметр и разрешение на изменение пользователя.
Классический клиент не открывается Схема URI Office, политика браузера и поведение новой вкладки.
Пользователь не может быть соавтором Тип файла, разрешения и поддержка клиентов Office.
Упоминания не находят пользователя Ограничения на членство в лицензиях и клиентах Microsoft 365.
Навигация не выглядит правильно Свойства контейнера и канал обновления Office.
Перенаправление возвращает неправильный маршрут ApplicationRedirectUrl и обработка маршрутов приложений.

Дальнейшие действия

Добавьте внедренные предварительные версии в файлы предварительного просмотра в приложении.

  • Last updated on