Сохранение на общий диск файла из интернета

Метод позволяет загружать файлы из интернета сразу на общий диск. Для этого следует передать в запросе URL файла и следить за ходом операции. Если при загрузке возникла ошибка, Диск не будет пытаться повторить ее.

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

Метод могут использовать как администраторы, так и другие сотрудники организации, у которых есть права на чтение данных с общего диска и запись на него.

Для OAuth-приложения необходимо наличие права:

cloud_api:disk.write

Формат запроса

Метод: POST.

https://cloud-api.yandex.net/v1/disk/virtual-disks/resources/upload
 ? url=<ссылка на скачиваемый файл>
 & path=<путь, по которому следует загрузить файл>
 & [disable_redirects=<признак запрета редиректов>]

Описание query-параметров

url*

Ссылка на скачиваемый файл. Например, http%3A%2F%2Fexample.com%2Fphoto.png. Максимальная длина имени загружаемого файла — 255 символов; максимальная длина пути — 32760 символов.

Путь в значении параметра следует кодировать в URL-формате.

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

disable_redirects

Параметр позволяет запретить редиректы по адресу, заданному в параметре url.

Допустимые значения:

false — обнаружив редирект, Диск должен скачать файл с нового адреса. Это значение используется по умолчанию.
true — обнаружив редирект, Диск не должен переходить по нему и что-либо скачивать.

* Обязательный параметр.

Authorization: OAuth <token>

Формат ответа

Успешный ответ

Скачивание файла может занять неопределенное время. Если операция скачивания была запущена, API отвечает кодом 202 Accepted и ссылкой на статус операции (в теле ответа в объекте Link).

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

Статус success значит, что файл скачан успешно.
Статус failed значит, что файл скачать не удалось. В этом случае ваше приложение может попробовать скачать файл самостоятельно и загрузить его с помощью запроса, который позволяет загружать файла на общий диск устройства. Посмотреть описание запроса

Пример ответа:

{
  "href": "https://cloud-api.yandex.net/v1/disk/operations?id=33ca7d03ab21ct41b4a40182e78d828a3f8b72cdb5f4c0e94cc4b1449a63a2fe",
  "method": "GET",
  "templated": false
}

Описание элементов ответа

Элемент	Описание
`href`	URL. Может быть шаблонизирован, см. ключ `templated`.
`method`	HTTP-метод для запроса URL из ключа `href`.
`templated`	Признак URL, который был шаблонизирован согласно RFC 6570. Возможные значения: «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках. «false» — URL может быть запрошен без изменений.

Ответ с ошибкой

Если запрос вызвал ошибку, возвращается подходящий код ответа, а тело ответа содержит описание ошибки.

Некоторые возможные ошибки:

400 — Некорректные данные.
401 — Не авторизован.
403 — API недоступно. Ваши файлы занимают больше места, чем у вас есть. Удалите лишнее или увеличьте объём Диска. / Пользователь не имеет прав доступа к общему диску.
404 — Не удалось найти запрошенный ресурс.
406 — Ресурс не может быть представлен в запрошенном формате.
409 — Ресурс по указанному пути уже существует.
413 — Загрузка файла недоступна. Файл слишком большой.
423 — Технические работы. Сейчас можно только просматривать и скачивать файлы.
429 — Слишком много запросов.
503 — Сервис временно недоступен.
507 — Недостаточно свободного места.