Полка документов

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

В качестве данных на полке документов может храниться содержимое документов, бинарное представление электронной подписи, архив с результатом выполнения метода GenerateDocumentZip и другие бинарные данные. Условно все эти данные в контексте полки будем называть документами.

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

Некоторые методы API требуют передавать в них содержимое документов. Но содержимое может быть большим, что вызовет проблемы при его загрузке одной командой. Такая команда будет выполняться долго и даже может завершиться неуспехом.

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

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

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

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

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

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

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

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

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

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

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

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

Полка является приоритетным методом передачи данных в методы API. Уже при размере содержимого документа от 500 KB мы рекомендуем использовать полку, а не передавать его в методы напрямую.

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

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

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

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

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

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

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

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

Ограничения

  • Нельзя загрузить на полку содержимое документа размером больше 400 MB.

  • Загруженный документ хранится на полке 7 дней, после чего автоматически удаляется.

См. также

Методы для работы с полкой документов:

  • ShelfDownload (V2) — загружает содержимое документа с полки документов

  • ShelfUpload (V2) — загружает содержимое документа на полку документов целиком

  • ShelfUploadPart — загружает фрагмент содержимого документа на полку документов, если первая его часть уже была загружена методом ShelfUploadPartInit

  • ShelfUploadPartInit — загружает первый фрагмент документа на полку документов