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

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

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

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

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

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

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

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

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

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

Начните со следующих ссылок на Microsoft Graph:

• Тип ресурса fileStorageContainer
• Тип ресурса DriveItem
• Общие сведения о хранилище файлов Microsoft Graph

Важно!

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

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

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

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

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

API-интерфейсы Microsoft Graph DriveItem используют 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-адресов для кратковременных URL-адресов для скачивания.
6. Войдите в журнал в соответствии с требованиями аудита.

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

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

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

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

1. Проверьте, существует ли папка.
2. Создайте только отсутствующий сегмент пути.
3. При необходимости сохраните идентификатор driveItem папки.
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 и предварительные версии интерфейсов

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

• Откройте файлы Office из приложения для запуска Word, Excel и PowerPoint.
• Предварительный просмотр файлов в приложении для предварительной версии браузера.
• Поиск контейнеров и файлов для обнаружения.

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

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

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

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

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

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

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