Полка документов¶
Полка документов — временное хранилище данных в Диадоке. Полка используется для удобства передачи и получения данных методами API.
В качестве данных на полке документов может храниться содержимое документов, бинарное представление электронной подписи, архив с результатом выполнения метода GenerateDocumentZip и другие бинарные данные. Условно все эти данные в контексте полки будем называть документами.
Преимущества полки¶
Некоторые методы API требуют передавать в них содержимое документов. Но содержимое может быть большим, что вызовет проблемы при его загрузке одной командой. Такая команда будет выполняться долго и даже может завершиться неуспехом.
Для решения этой проблемы используется полка документов. Она позволяет загрузить содержимое документа в хранилище небольшими частями, а после передавать в методы API ссылку на документ на полке — имя документа. Таким образом, в методы можно передавать не содержимое документа, а только его имя на полке. Это ускоряет работу метода и повышает его надежность.
Один и тот же документ, хранящийся на полке, можно использовать в разных методах. Для этого не придется в каждый метод загружать содержимое документа, достаточно будет указать его имя на полке.
Использование¶
Полка предоставляет возможность загружать, хранить и скачивать содержимое документов. Для этого в API реализованы следующие методы:
Метод ShelfUpload используется для загрузки содержимого документа на полку.
С помощью этого метода можно загрузить содержимое документа целиком или по частям и присвоить ему имя на полке. Если во время загрузки какой-то части возникнут проблемы, метод сообщит об этом.
Метод ShelfDownload используется для загрузки содержимого документа с полки.
Для загрузки содержимого документа нужно знать его имя на полке.
Полка является приоритетным методом передачи данных в методы API. Уже при размере содержимого документа от 500 Кб мы рекомендуем использовать полку, а не передавать его в методы напрямую.
Пространства имен полки¶
Обращение к документам на полке осуществляется с помощью имени документа. Имя присваивается документу при вызове метода ShelfUpload. Впоследствии это имя используется в других методах API.
Пространство имен документов на полке делится на локальное и публичное. Доступ к локальному пространству есть только у текущего пользователя, к публичному — у любого пользователя.
По умолчанию при загрузке на полку имя документа будет публичным. То есть если вызвать метод ShelfUpload с параметром nameOnShelf = filename, то имя загруженного документа будет публичным: public/filename.
Чтобы загрузить документ с локальным именем, при вызове метода ShelfUpload укажите в качестве параметра nameOfShelf значение __userId__/filename. Строка __userId__ в этом случае сообщает сервису, что текущий пользователь загружает данные в свое локальное пространство; ее не нужно заменять каким-либо значением. Документ будет загружен на полку с именем {userId}/filename, значение {userId} будет взято из текущего авторизационного токена. Доступ к таким файлам можно получить с помощью метода ShelfDownload, указав параметр nameOnShelf = __userId__/filename.
Методы PostMessage и PostMessagePatch всегда трактуют переданное имя документа как локальное, поэтому в этих методах имя файла нужно указывать без префикса userId.
Ограничения¶
Нельзя загрузить на полку содержимое документа размером больше 400 Мб.
Загруженный документ хранится на полке 7 дней, после чего автоматически удаляется.
Представление в API¶
- Методы для работы с полкой:
ShelfUpload — загружает данные на полку.
ShelfDownload — загружает данные с полки.