Загрузка файла на общий диск

Чтобы загрузить файл на Диск, необходимо:

  1. Запросить URL для загрузки.
  2. Загрузить файл по полученному адресу.

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

Для 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
}
Описание элементов ответа

Элемент

Описание

operation_id

Идентификатор операции загрузки файла.

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 — Недостаточно свободного места.

Загрузка файла на полученный 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 — удалить файл с совпадающим именем и записать загруженный файл.

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