Загрузка файла на общий диск
Чтобы загрузить файл на Диск, необходимо:
- Запросить URL для загрузки.
- Загрузить файл по полученному адресу.
Загружать файлы на общий диск может как администратором, так и другими сотрудниками организации, у которых есть права на чтение данных с общего диска и запись на него.
Для OAuth-приложения необходимо наличие права:
cloud_api:disk.read
cloud_api:disk.write
Запрос URL для загрузки
Сообщите API Диска желаемый путь на общем диске для загрузки файла. В ответе на запрос вы получите URL, который потребуется для дальнейшей загрузки.
Формат запроса
Метод: GET.
https://cloud-api.yandex.net/v1/disk/virtual-disks/resources/upload
? path=<путь, по которому следует загрузить файл>
& [overwrite=<признак перезаписи>]
Описание query-параметров
- path*
-
Путь, по которому следует загрузить файл на общий диск. Максимальная длина имени загружаемого файла — 255 символов; максимальная длина пути — 32760 символов.
Указывается в следующем формате:
vd:<vd_hash>:disk:/<путь внутри общего диска>
Где
-
<vd_hash>
— метка общего диска. Примерvd_hash
: 9Uyws5pZmXgDNA. Метку общего диска можно получить:- по API — с помощью метода, который возвращает информацию о статусе создания общего диска (посмотреть описание метода);
- в интерфейсе Яндекс Диска — перейдите в общий диск, метка будет указана в персональной строке после
vd/
.
-
<путь внутри общего диска>
— путь до файла или папки внутри общего диска.
Например, путь до файла test_file.txt, который лежит в папке test_folder общего диска указывается так:
vd:9Uyws5pZmXgDNA:disk:/test_folder/test_file.txt
-
- overwrite
-
Признак перезаписи файла. Учитывается, если файл загружается в папку, в которой уже есть файл с таким именем.
Допустимые значения:
false
— не перезаписывать файл, отменить загрузку (используется по умолчанию);true
— удалить файл с совпадающим именем и записать загруженный файл.
* Обязательный параметр.
Заголовок
Authorization: OAuth <token>
Формат ответа
Успешный ответ
Если запрос был обработан без ошибок, API отвечает кодом 200 OK
. В теле ответа в объекте Link-upload возвращается сгенерированный URL для загрузки файла. Если в течение 30 минут этот URL не будет запрошен, он перестанет работать и нужно будет запросить новую ссылку.
Пример ответа:
{
"operation_id": "cbb77e87cc43bcdcdd2de397cd05b43368b9e2bda78eab1f94037c9c38a31e43",
"href": "https://uploader1d.dst.yandex.net:443/upload-target/...",
"method": "PUT",
"templated": false
}
Описание элементов ответа
Элемент |
Описание |
|
Идентификатор операции загрузки файла. |
|
URL. Может быть шаблонизирован, см. ключ |
|
HTTP-метод для запроса URL из ключа |
|
Признак URL, который был шаблонизирован согласно RFC 6570. Возможные значения:
|
Ответ с ошибкой
Если запрос вызвал ошибку, возвращается подходящий код ответа, а тело ответа содержит описание ошибки.
Некоторые возможные ошибки:
400
— Некорректные данные.401
— Не авторизован.403
— API недоступно. Ваши файлы занимают больше места, чем у вас есть. Удалите лишнее или увеличьте объём Диска. / Пользователь не имеет прав доступа к общему диску.404
— Не удалось найти запрошенный ресурс.406
— Ресурс не может быть представлен в запрошенном формате.409
— Ресурс по указанному пути уже существует.413
— Загрузка файла недоступна. Файл слишком большой.423
— Технические работы. Сейчас можно только просматривать и скачивать файлы.429
— Слишком много запросов.503
— Сервис временно недоступен.507
— Недостаточно свободного места.
Загрузка файла на полученный URL
Формат запроса
Файл следует отправить с помощью метода PUT на URL для загрузки в течение 30 минут после получения этого URL (через 30 минут ссылка перестанет работать и ее нужно будет запросить заново). OAuth-токен для загрузки в хранилище не нужен.
Пример URL для загрузки:
https://uploader1d.dst.yandex.net:443/upload-target/20240424T101447.217.utd.52csloukwvq67nab1yc84a3xw-k1d.6625
Формат ответа
Успешный ответ
-
Если запрос был обработан без ошибок, API отвечает кодом
201 Created
.Пример HTTP-ответа:
HTTP/1.1 201 Created Content-Length: 0
-
Если файл принят сервером, но еще не перенесен непосредственно на общий диск, API отвечает кодом
202 Accepted
.
Ответ с ошибкой
Возможные коды ответа при загрузке файла
Некоторые возможные ошибки:
412
— при дозагрузке файла был передан неверный диапазон в заголовкеContent-Range
.413
— размер файла больше допустимого. Если у вас есть подписка на Яндекс 360, можно загружать файлы размером до 50 ГБ, если подписки нет — до 1 ГБ.500
— ошибка сервера, попробуйте повторить загрузку.503
— сервер недоступен, попробуйте повторить загрузку.507
— для загрузки файла не хватает места на общем диске.
Путь, по которому следует загрузить файл на общий диск. Максимальная длина имени загружаемого файла — 255 символов; максимальная длина пути — 32760 символов.
Указывается в следующем формате:
vd:<vd_hash>:disk:/<путь внутри общего диска>
Где
-
<vd_hash>
— метка общего диска. Примерvd_hash
: 9Uyws5pZmXgDNA. Метку общего диска можно получить:- по API — с помощью метода, который возвращает информацию о статусе создания общего диска (посмотреть описание метода);
- в интерфейсе Яндекс Диска — перейдите в общий диск, метка будет указана в персональной строке после
vd/
.
-
<путь внутри общего диска>
— путь до файла или папки внутри общего диска.
Например, путь до файла test_file.txt, который лежит в папке test_folder общего диска указывается так:
vd:9Uyws5pZmXgDNA:disk:/test_folder/test_file.txt
Признак перезаписи файла. Учитывается, если файл загружается в папку, в которой уже есть файл с таким именем.
Допустимые значения:
false
— не перезаписывать файл, отменить загрузку (используется по умолчанию);true
— удалить файл с совпадающим именем и записать загруженный файл.
Обязательный параметр.