Операции над опубликованными файлами и папками

Ресурсы, опубликованные другими пользователями, можно скачать или поместить в папку «Загрузки». Также можно запросить метаинформацию о них.

В каждом запросе к чужим опубликованным ресурсам необходимо указывать публичный ключ, который возвращается Яндекс Диском при публикации файла. OAuth-токен (и, соответственно, заголовок Authorization) в таких запросах указывать не нужно.

Метаинформация о публичном ресурсеМетаинформация о публичном ресурсе

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

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

Запрос метаинформации следует отправлять с помощью метода GET.

https://cloud-api.yandex.net/v1/disk/public/resources
 ? public_key=<ключ опубликованного ресурса>
 & [path=<путь к ресурсу>]
 & [sort=<атрибут сортировки>]
 & [limit=<ограничение на количество возвращаемых ресурсов>]
 & [preview_size=<размер превью>]
 & [preview_crop=<признак обрезки превью>]
 & [offset=<смещение относительно начала списка>]

public_key*

Ключ опубликованного ресурса или публичная ссылка на ресурс.

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

path

Относительный путь к ресурсу внутри публичной папки. Указывая ключ опубликованной папки в параметре public_key, вы можете запросить метаинформацию любого вложенного в нее ресурса. Например, чтобы получить свойства папки /foo, которая вложена в опубликованную папку, передайте параметр path=%2Ffoo.

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

sort

Атрибут, по которому нужно сортировать список ресурсов, вложенных в папку. В качестве значения можно указывать имена следующих свойств объекта Resource:

• name (имя ресурса);
• path (путь к ресурсу на Диске);
• created (дата создания ресурса);
• modified (дата изменения ресурса);
• size (размер файла).
  

Для сортировки в обратном порядке добавьте дефис к значению параметра, например: sort=-name.

limit

Количество ресурсов, вложенных в папку, описание которых следует вернуть в ответе (например, для постраничного вывода).

Значение по умолчанию — 20.

preview_size

Требуемый размер уменьшенного изображения (превью файла), ссылку на которое Диск должен вернуть в ключе preview.

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

Варианты значений

• Предопределенный размер большей стороны.

  Картинка уменьшается до указанного размера по большей стороне, пропорции исходного изображения сохраняются. Например, для размера S и картинки размером 120×200 будет сгененерировано превью размером 90×150, а для картинки 300×100 — превью размером 150×50.

  Поддерживаемые значения:

  -"S" — 150 пикселей;
  -"M" — 300 пикселей;
  -"L" — 500 пикселей;
  -"XL" — 800 пикселей;
  -"XXL" — 1024 пикселей;
  -"XXXL" — 1280 пикселей.

• Точная ширина (например, "120" или "120x") или точная высота (например, "x145").

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

  Если передан параметр preview_crop, из центра уменьшенного изображения также вырезается квадрат с заданной стороной.

• Точный размер (в формате <ширина>x<высота>, например "120x240").

  Картинка уменьшается до меньшего из указанных размеров, пропорции исходного изображения сохраняются.

  Если передан параметр preview_crop, из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты (в примере — один к двум). Затем вырезанный фрагмент масштабируется до указанных размеров.

preview_crop

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

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

• false — параметр игнорируется (по умолчанию).
• true — превью обрезается следующим образом:
  
  
  • Если передана только ширина или высота, картинка уменьшается до этого размера с сохранением пропорций. Затем из центра уменьшенного изображения также вырезается квадрат с заданной стороной.
    
  • Если передан точный размер (например, "120x240"), из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты. Затем вырезанный фрагмент масштабируется до указанных размеров.

offset

Количество ресурсов с начала списка, которые следует опустить в ответе (например, для постраничного вывода).

Допустим, папка /foo содержит три файла. Если запросить метаинформацию о папке с параметром offset=1, API Диска вернет только описания второго и третьего файла.

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

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

Если запрос был обработан без ошибок, API отвечает кодом 200 OK и возвращает метаинформацию о запрошенном ресурсе в теле ответа в объекте Resource.

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

Для непустых папок в ответ включается объект ResourceList (под именем _embedded). Каждый вложенный в папку ресурс является элементом массива items.Вне зависимости от запрошенной сортировки, ресурсы в массиве упорядочены по их виду: сначала перечисляются все вложенные папки, затем — вложенные файлы.

Все пути в метаинформации для опубликованной папки указываются относительно самой папки.

Пример ответа приведен для опубликованной папки /foo, в которой содержатся папка /bar и файл photo.png:

{
  "public_key": "aSsmHLoeyBlJw8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",
  "_embedded":
  {
    "sort": "",
    "public_key": "kLsmHRoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",
    "items": [
    {
      "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",
      "name": "bar-1",
      "created": "2014-05-22T14:30:16+04:00",
      "modified": "2014-05-22T14:30:16+04:00",
      "path": "/bar-1",
      "type": "dir"
    },
    {
      "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",
      "preview": "https://downloader.disk.yandex.ru/preview/...",
      "name": "photo.png",
      "created": "2014-08-08T12:36:23+04:00",
      "modified": "2014-08-08T12:36:23+04:00",
      "path": "/photo.png",
      "md5": "dc27c182eda45002d641b68937029301",
      "type": "file",
      "mime_type": "image/png", 
      "size": 29293
    }
    ],
    "limit": 20,
    "offset": 0,
    "path": "/",
    "total": 4
  },
  "name": "foo",
  "created": "2014-05-22T14:30:09+04:00",
  "public_url": "https://yadi.sk/d/AaaBbb1122Ccc",
  "modified": "2014-05-22T14:30:09+04:00",
  "path": "/",
  "type": "dir"
}

Скачивание публичного файла или папкиСкачивание публичного файла или папки

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

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

Запрос на скачивание файла следует отправлять с помощью метода GET.

https://cloud-api.yandex.net/v1/disk/public/resources/download
 ? public_key=<ключ опубликованного ресурса>
 & [path=<путь к ресурсу>]

public_key*

Ключ публичного файла или папки.

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

path

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

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

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

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

Если запрос был обработан без ошибок, API отвечает кодом 200 OK. В теле ответа, в объекте Link, возвращается сгенерированный URL для скачивания файла.

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

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

{
  "href": "https://downloader.dst.yandex.ru/disk/...",
  "method": "GET",
  "templated": false
}

Скачивать файл следует с помощью метода GET:

https://downloader.dst.yandex.ru/disk/53139aa0et584d3bac7eeab405d3574b/535320b4/YyjTJtEHob8R5WbpojJbiiUuU2HC_2JSTU0gW9qE0NHGW2uncmBjM_-IXun3Msyij96FTHQGSX-fDL-XwokDvA%3D%3D?uid=202727674&filename=photo.png&disposition=attachment&hash=&limit=0&content_type=application%2Fx-www-form-urlencoded&fsize=34524&hid=93528043563b8r55723a253f4730290a&media_type=document

Если запрос был обработан без ошибок, API отвечает файлом с кодом 200 OK.

Сохранение публичного файла в «Загрузки»Сохранение публичного файла в «Загрузки»

Файл, опубликованный на Диске, можно скопировать в папку «Загрузки» на Диске пользователя. Для этого нужно знать ключ файла или публичную ссылку на него. Если вы знаете ключ публичной папки, вы также можете копировать отдельные файлы из нее.

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

Запрос на сохранение файла следует отправлять с помощью метода POST.

https://cloud-api.yandex.net/v1/disk/public/resources/save-to-disk
 ? public_key=<ключ опубликованного ресурса>
 & [path=<путь к ресурсу>]
 & [name=<имя сохраненного файла>]

public_key*

Ключ сохраняемого ресурса.

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

path

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

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

name

Имя, под которым файл следует сохранить в папку «Загрузки».

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

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

Сохранение публичного файла на Диск может занять неопределенное время. В зависимости от статуса операции, сервер Яндекс Диска возвращает один из вариантов ответа:

{
  "href": "https://cloud-api.yandex.net/v1/disk/resources?path=disk%3A%2F%D0%97%D0%B0%D0%B3%D1%80%D1%83%D0%B7%D0%BA%D0%B8%photo.png",
  "method": "GET",
  "templated": false
}

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