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

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

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

  1. Метаинформация о публичном ресурсе
  2. Скачивание публичного файла или папки
  3. Сохранение публичного файла в «Загрузки»

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

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

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

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

https://cloud-api.yandex.net/v1/disk/public/resources
 ? public_key=<ключ опубликованного ресурса>
 & [path=<путь к ресурсу>]
 & [sort=<атрибут сортировки>]
 & [limit=<ограничение на количество возвращаемых
                ресурсов>]
 & [preview_size=<размер превью>]
 & [preview_crop=<признак обрезки превью>]
 & [offset=<смещение относительно начала списка>]
Query-параметры
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/2ARECiNTZGiYX",
  "modified": "2014-05-22T14:30:09+04:00",
  "path": "/",
  "type": "dir"
}
Описание элементов ответа
Элемент Описание
public_key

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

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

public_url

Ссылка на опубликованный ресурс.

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

_embedded

Ресурсы, непосредственно содержащиеся в папке (содержит объект ResourceList).

Включается в ответ только при запросе метаинформации о папке.

preview

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

Запросить превью можно только с OAuth-токеном пользователя, имеющего доступ к самому файлу.

name Имя ресурса.
custom_properties Объект со всеми атрибутами, заданными с помощью запроса Добавление метаинформации для ресурса. Содержит только ключи вида имя:значение (объекты или массивы содержать не может).
created Дата и время создания ресурса, в формате ISO 8601.
modified Дата и время изменения ресурса, в формате ISO 8601.
path

Полный путь к ресурсу на Диске.

В метаинформации опубликованной папки пути указываются относительно самой папки. Для опубликованных файлов значение ключа всегда «/».

Для ресурса, находящегося в Корзине, к атрибуту может быть добавлен уникальный идентификатор (например, trash:/foo_1408546879). С помощью этого идентификатора ресурс можно отличить от других удаленных ресурсов с тем же именем.

origin_path

Путь к ресурсу до перемещения в Корзину.

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

md5 MD5-хэш файла.
type

Тип ресурса:

  • «dir» — папка;
  • «file» — файл.
mime_type MIME-тип файла.
size Размер файла.
Элемент Описание
sort

Поле, по которому отсортирован список.

public_key

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

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

items

Массив ресурсов (Resource), содержащихся в папке.

Вне зависимости от запрошенной сортировки, ресурсы в массиве упорядочены по их виду: сначала перечисляются все вложенные папки, затем — вложенные файлы.

limit

Максимальное количество элементов в массиве items, заданное в запросе.

offset

Смещение начала списка от первого ресурса в папке.

path

Путь к папке, чье содержимое описывается в данном объекте ResourceList.

Для публичной папки значение атрибута всегда равно «/».

total

Общее количество ресурсов в папке.

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

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

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

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

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

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

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

path

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

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

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

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

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

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

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

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

URL. Может быть шаблонизирован, см. ключ templated.

method

HTTP-метод для запроса URL из ключа href.

templated

Признак URL, который был шаблонизирован согласно RFC 6570. Возможные значения:

  • «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках.
  • «false» — URL может быть запрошен без изменений.

Скачивать файл следует с помощью метода 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/resources/download
 ? public_key=<ключ опубликованного ресурса>
 & [path=<путь к ресурсу>]
 & [name=<имя сохраненного файла>]
Query-параметры
public_key *

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

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

path

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

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

name

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

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

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

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

Если к моменту ответа запрос удалось обработать без ошибок, API отвечает кодом 201 Created и возвращает ссылку на сохраненный файл в теле ответа (в объекте Link).

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

{
  "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

URL. Может быть шаблонизирован, см. ключ templated.

method

HTTP-метод для запроса URL из ключа href.

templated

Признак URL, который был шаблонизирован согласно RFC 6570. Возможные значения:

  • «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках.
  • «false» — URL может быть запрошен без изменений.