Отправка и скачивание файлов, а также управление ими

Применяется к: Для разработчиков

Используйте API файлов Microsoft Graph и DriveItem для управления файлами внутри контейнеров SharePoint Embedded.

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

SharePoint Embedded предоставляет вашему приложению хранилище документов только для API со встроенными возможностями Microsoft 365. Управление файлами осуществляется полностью программно с помощью Microsoft Graph без пользовательского интерфейса SharePoint. Полный жизненный цикл включает отправку и скачивание, папки, управление версиями, корзину и 93-дневное восстановление содержимого. Контент доступен для поиска через API поиска (Майкрософт) и наследует соответствие клиента требованиям Microsoft Purview. Конечным пользователям вашего приложения не нужна лицензия Microsoft 365 для выполнения основных операций с файлами.

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

Контейнер SharePoint Embedded — это граница хранилища для содержимого приложения.

Каждый контейнер предоставляет содержимое файла через хранилище файлов Microsoft Graph и API-интерфейсы DriveItem.

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

Сведения об архитектуре см. в статье Архитектура приложения SharePoint Embedded.

Использование API хранилища файлов Microsoft Graph

Начните с этих ссылок на Microsoft Graph:

Важно!

Используйте документированные API Microsoft Graph, DriveItem и файлового хранилища. Не изобретайте имена API файлов, специфичные для SharePoint Embedded.

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

Перед началом работы с файлами убедитесь, что:

  • Ваше приложение может получать маркеры Microsoft Graph.
  • У приложения есть FileStorageContainer.Selected согласие.
  • У приложения есть разрешения типа контейнера для предполагаемых операций.
  • Целевой контейнер существует.
  • Для делегированных звонков пользователь является участником контейнера.
  • Приложение сохраняет нужный идентификатор контейнера и идентификаторы DriveItem.

Сопоставление идентификаторов контейнеров с дисками

API DriveItem Microsoft Graph используют driveId. Для SharePoint Embedded идентификатор диска — это идентификатор контейнера, начинающийся с b!.

В приложении:

  1. Сохранить идентификатор контейнера, возвращенный при его создании.
  2. Используйте идентификатор контейнера при вызове API DriveItem, которым требуется идентификатор диска.
  3. Идентификаторы элементов хранения, возвращенные операциями отправки или создания папок.
  4. Избегайте восстановления идентификаторов из URL-адресов.

Отправка файлов

Используйте шаблоны отправки Microsoft Graph для DriveItems.

Для небольших файлов (до 250 МБ) используйте простой API отправки, задокументированный для DriveItems, с одним PUT для содержимого элемента.

Для больших файлов (более 250 МБ) используйте сеанс отправки, как описано в Microsoft Graph, и отправляйте файл байтовыми блоками (например, кратными 320 КБ) до завершения отправки.

В потоке отправки:

  1. Проверка доступа на запись.
  2. Выберите целевую папку в контейнере.
  3. Сначала создайте папки, если пути не существует.
  4. Загрузите байты файла с помощью соответствующего метода Graph.
  5. Сохраните возвращенный идентификатор DriveItem.
  6. Отображение имени, размера и состояния файла.

Совет

Храните метаданные бизнеса в базе данных приложения, а содержимое файлов — в SharePoint Embedded.

Скачать файлы

Используйте возможности скачивания Microsoft Graph DriveItem для содержимого файлов.

В процессе скачивания:

  1. Проверка доступа на чтение.
  2. Сопоставьте идентификатор контейнера и идентификатор DriveItem.
  3. Запросите содержимое файла или URL-адрес загрузки с помощью API DriveItem.
  4. Stream содержимое пользователю или службе.
  5. Обработка истечения срока действия для краткосрочных URL-адресов загрузки.
  6. Ведение журнала в соответствии с требованиями аудита.

Создание папок

Используйте API создания папок DriveItem для упорядочения содержимого.

Создавайте папки для предсказуемой структуры содержимого, этапов рабочего процесса, связанных отправок и стабильных родительских элементов для URL-адресов запуска Office.

При создании папок:

  1. Проверьте, существует ли папка.
  2. Создайте только отсутствующий сегмент пути.
  3. При необходимости сохраните идентификатор элемента диска папки.
  4. Последовательно применяйте правила именования.

Обновление содержимого файла

Использование Microsoft Graph DriveItem для обновления или отправки шаблонов сеансов для замены содержимого.

Перед заменой содержимого:

  • Подтвердите разрешение на запись.
  • Чтение текущих метаданных, если требуются проверки параллелизма.
  • Сохраните идентификатор DriveItem там, где это поддерживается.
  • Обновите метаданные приложения после успешной работы Graph.

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

Инструкции по работе в Office см. в статье "Открытие файлов Office" в приложении .

Переименование и перемещение элементов

Используйте документированное обновление DriveItem и перемещайте операции там, где это поддерживается.

Чтение текущего элемента DriveItem, подтверждение конечной папки, применение операции, обновление сохраненного пути или отображаемого имени и, по возможности, сохранение идентификатора DriveItem в качестве надежного справочника.

Удаление файлов

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

Перед удалением:

  • Подтвердите намерение пользователя.
  • Подтвердите разрешение на запись или удаление.
  • Решите, нужно ли вашему приложению выполнить обратимое удаление.
  • Обновляйте состояние приложения только после того, как Graph возвращает результат "Успешно".

Восстановление файлов

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

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

Примечание.

recycleBinItem: восстановление поддерживается driveItemId в качестве альтернативного ключа в бета-версии Microsoft Graph (октябрь 2025 г.). Если известен идентификатор исходного элемента driveItem, можно восстановить соответствующий recycleBinItem напрямую, без первоначального перечисления корзины.

Для получения точных сведений о запросе и ответе операции с файлом используйте документацию Microsoft Graph DriveItem.

Подключение к Office и предварительные просмотры интерфейсов

После отправки добавьте более широкие возможности:

Проверка операций с файлами

Создайте дымовой тест:

  1. Создайте тестовый контейнер.
  2. Создайте папку.
  3. Отправка файла.
  4. Чтение возвращенных метаданных DriveItem.
  5. Скачайте файл.
  6. Замените содержимое.
  7. Переименуйте файл.
  8. Удалите этот файл.
  9. Восстановите его, если он поддерживается.
  10. Очистите тестовый контейнер.

Устранение неполадок при операциях с файлами

Признак Проверка
Сбой отправки WriteContent разрешение и роль пользователя "Писатель".
Сбой скачивания ReadContent разрешение и роль пользователя с правами чтения.
Не удается создать папку Идентификатор родительской папки и разрешения на запись.
Сбой предварительного просмотра Поддержка типов файлов и предварительный просмотр создания URL-адресов.
При запуске Office открывается неправильный режим Параметр URL-адреса action запуска или схема URI Office.
Доступ отличается для разных пользователей Делегированный доступ пересекает разрешения приложения с членством.

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

Включите запуск Office в разделе "Открытие файлов Office из приложения".

  • Last updated on