Документация

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

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

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

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

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

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

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

https://cloud-api.yandex.net/v1/disk/public/resources ?
   public_key
[no-highlight[

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

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

]no-highlight]
=<ключ опубликованного ресурса> [& path
[no-highlight[

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

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

]no-highlight]
=<путь к ресурсу>] [& sort
[no-highlight[

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

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

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

]no-highlight]
=<атрибут сортировки>] [& limit
[no-highlight[

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

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

]no-highlight]
=<ограничение на количество возвращаемых ресурсов>] [& preview_size=<размер превью>] [& preview_crop
[no-highlight[

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

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

  • «false» — параметр игнорируется. Это значение используется по умолчанию.

  • «true» — превью обрезается следующим образом:

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

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

]no-highlight]
=<признак обрезки превью>] [& offset=<смещение относительно начала списка>]
public_key

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

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

path (необязательный)

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

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

sort (необязательный)

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

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

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

limit (необязательный)

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

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

preview_size (необязательный)

Требуемый размер уменьшенного изображения (превью файла), ссылка на которое API возвращает в ключе 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, из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты (в примере — 1/2). Затем вырезанный фрагмент масштабируется до указанных размеров.

preview_crop (необязательный)

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

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

  • «false» — параметр игнорируется. Это значение используется по умолчанию.

  • «true» — превью обрезается следующим образом:

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

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

offset (необязательный)

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

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

{
  "_embedded":
  {
    "sort":"",
    "path":"disk:/foo",
    "items":[
    {
      "path":"disk:/foo/bar-2",
      "type":"dir",
      "name":"bar-2",
      "modified":"2014-05-22T14:30:20+04:00",
      "created":"2014-05-22T14:30:20+04:00"
    },
    {
      "path":"disk:/foo/bar-3",
      "type":"dir",
      "name":"bar-3",
      "modified":"2014-05-22T14:30:16+04:00",
      "created":"2014-05-22T14:30:16+04:00"
    }],
    "limit":20,
    "offset":1
  },
  "name":"foo",
  "created":"2014-05-22T14:30:09+04:00",
  "modified":"2014-05-22T14:30:09+04:00",
  "path":"disk:/foo",
  "type":"dir"
}

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

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

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

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

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

{
  "public_key
[no-highlight[

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

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

]no-highlight]
": "aSsmHLoeyBlJw8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=", "_embedded
[no-highlight[

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

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

]no-highlight]
": { "sort
[no-highlight[

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

]no-highlight]
": "", "public_key
[no-highlight[

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

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

]no-highlight]
": "kLsmHRoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=", "items
[no-highlight[

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

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

]no-highlight]
": [ { "public_key
[no-highlight[

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

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

]no-highlight]
": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=", "name
[no-highlight[

Имя ресурса.

]no-highlight]
": "bar-1", "created
[no-highlight[

Дата и время создания ресурса, в формате ISO 8601.

]no-highlight]
": "2014-05-22T14:30:16+04:00", "modified
[no-highlight[

Дата и время изменения ресурса, в формате ISO 8601.

]no-highlight]
": "2014-05-22T14:30:16+04:00", "path
[no-highlight[

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

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

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

]no-highlight]
": "/bar-1", "type
[no-highlight[

Тип ресурса:

  • «dir» — папка;
  • «file» — файл.
]no-highlight]
": "dir" }, { "public_key
[no-highlight[

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

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

]no-highlight]
": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=", "preview
[no-highlight[

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

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

]no-highlight]
": "https://downloader.disk.yandex.ru/preview/...", "name
[no-highlight[

Имя ресурса.

]no-highlight]
": "photo.png", "created
[no-highlight[

Дата и время создания ресурса, в формате ISO 8601.

]no-highlight]
": "2014-08-08T12:36:23+04:00", "modified
[no-highlight[

Дата и время изменения ресурса, в формате ISO 8601.

]no-highlight]
": "2014-08-08T12:36:23+04:00", "path
[no-highlight[

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

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

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

]no-highlight]
": "/photo.png", "md5
[no-highlight[

MD5-хэш файла.

]no-highlight]
": "dc27c182eda45002d641b68937029301", "type
[no-highlight[

Тип ресурса:

  • «dir» — папка;
  • «file» — файл.
]no-highlight]
": "file", "mime_type
[no-highlight[

MIME-тип файла.

]no-highlight]
": "image/png", "size
[no-highlight[

Размер файла.

]no-highlight]
": 29293 } ], "limit
[no-highlight[

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

]no-highlight]
": 20, "offset
[no-highlight[

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

]no-highlight]
": 0, "path
[no-highlight[

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

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

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

]no-highlight]
": "/", "total
[no-highlight[

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

]no-highlight]
": 4 }, "name
[no-highlight[

Имя ресурса.

]no-highlight]
": "foo", "created
[no-highlight[

Дата и время создания ресурса, в формате ISO 8601.

]no-highlight]
": "2014-05-22T14:30:09+04:00", "public_url
[no-highlight[

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

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

]no-highlight]
": "https://yadi.sk/d/2ARECiNTZGiYX", "modified
[no-highlight[

Дата и время изменения ресурса, в формате ISO 8601.

]no-highlight]
": "2014-05-22T14:30:09+04:00", "path
[no-highlight[

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

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

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

]no-highlight]
": "/", "type
[no-highlight[

Тип ресурса:

  • «dir» — папка;
  • «file» — файл.
]no-highlight]
": "dir" }

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

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

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

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

https://cloud-api.yandex.net/v1/disk/public/resources/download ?
   public_key
[no-highlight[

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

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

]no-highlight]
=<ключ опубликованного ресурса> [& path
[no-highlight[

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

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

]no-highlight]
=<путь к ресурсу>]
public_key

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

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

path (необязательный)

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

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

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

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

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

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

{
  "href
[no-highlight[

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

]no-highlight]
": "https://downloader.dst.yandex.ru/disk/...", "method
[no-highlight[

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

]no-highlight]
": "GET", "templated
[no-highlight[

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

  • «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках.
  • «false» — URL может быть запрошен без изменений.
]no-highlight]
": 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
[no-highlight[

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

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

]no-highlight]
=<ключ опубликованного ресурса> [& path
[no-highlight[

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

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

]no-highlight]
=<путь к ресурсу>] [& name
[no-highlight[

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

]no-highlight]
=<имя сохраненного файла>]
public_key

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

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

path (необязательный)

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

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

name

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

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

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

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

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

    {
      "href
    [no-highlight[

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

    ]no-highlight]
    ": "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
    [no-highlight[

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

    ]no-highlight]
    ": "GET", "templated
    [no-highlight[

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

    • «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках.
    • «false» — URL может быть запрошен без изменений.
    ]no-highlight]
    ": false }
  • Если операция сохранения была запущена, но еще не завершилась, Яндекс.Диск отвечает кодом 202 Accepted.

    Приложения должны самостоятельно следить за статусами запрошенных операций. Яндекс.Диск возвращает ссылку на статус запущенной по запросу операции в теле ответа, в объекте Link.

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

    {
      "href
    [no-highlight[

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

    ]no-highlight]
    ": "https://cloud-api.yandex.net/v1/disk/operations/33ca7d03ab21ct41b4a40182e78d828a3f8b72cdb5f4c0e94cc4b1449a63a2fe", "method
    [no-highlight[

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

    ]no-highlight]
    ": "GET", "templated
    [no-highlight[

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

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

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