Работа с полкой документов

Определение полки приведено на странице Полка документов.

Загрузка документа на полку

Для загрузки документа на полку в API реализованы следующие методы:

  • Для загрузки на полку документов небольшого размера целиком используйте метод ShelfUpload (V2): метод загрузит документ на полку, сгенерирует его имя и вернет это имя в ответе. Подробнее об ограничениях размера — на странице метода.

  • Для загрузки на полку документов большого размера по частям используйте методы ShelfUploadPartInit и ShelfUploadPart:

    1. С помощью метода ShelfUploadPartInit загрузите первый фрагмент документа. Метод сгенерирует имя файла на полке и вернет его в ответе.

    2. Методом ShelfUploadPart загрузите по очереди на полку все остальные фрагменты документа, указав его имя.

    Последний фрагмент документа загрузите с параметром isLastPart = true: это сообщит серверу, что вы загрузили все части документа.

    Подробнее об ограничениях размера фрагментов и документа — на страницах метода.

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

Использование документа с полки

Один и тот же документ, хранящийся на полке, можно использовать в разных методах. Для этого не нужно в каждый метод загружать содержимое документа — достаточно указать его имя на полке.

Загруженный на полку документ можно использовать следующими способами:

Пространства имен полки

Предупреждение

Эта информация относится к устаревшим версиям методов ShelfUpload и ShelfDownload.

Обращение к документам на полке осуществляется с помощью имени документа. Имя присваивается документу при вызове метода ShelfUpload. Впоследствии это имя используется в других методах API.

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

По умолчанию при загрузке на полку имя документа будет публичным. То есть если вызвать метод ShelfUpload с параметром nameOnShelf = filename, то имя загруженного документа будет публичным: public/filename.

Чтобы загрузить документ с локальным именем, при вызове метода ShelfUpload укажите в качестве параметра nameOfShelf значение __userId__/filename. Строка __userId__ в этом случае сообщает сервису, что текущий пользователь загружает данные в свое локальное пространство; ее не нужно заменять каким-либо значением. Документ будет загружен на полку с именем {userId}/filename, значение {userId} будет взято из текущего авторизационного токена. Доступ к таким файлам можно получить с помощью метода ShelfDownload, указав параметр nameOnShelf = __userId__/filename.

Методы PostMessage (V3) и PostMessagePatch (V4) всегда трактуют переданное имя документа как локальное, поэтому в этих методах имя файла нужно указывать без префикса userId.