--- metadata: - name: generator content: Diplodoc Platform v5.44.0 alternate: - https://yandex.ru/dev/disk-api/doc/en/reference/public.md - https://yandex.ru/dev/disk-api/doc/ru/reference/public.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/disk-api/doc/ru/llms.txt # Операции над опубликованными файлами и папками {% note alert %} Метаинформация о запрошенном ресурсе недоступна, если владелец ссылки на файл или папку установил [запрет на скачивание](https://yandex.ru/support/disk/share/sharing-to-me.html#restriction). {% endnote %} Ресурсы, опубликованные другими пользователями, можно скачать или поместить в папку «Загрузки». Также можно запросить метаинформацию о них. В каждом запросе к чужим опубликованным ресурсам необходимо указывать публичный ключ, который возвращается Яндекс Диском при [публикации файла](https://yandex.ru/dev/disk-api/doc/ru/reference/publish.md). OAuth-токен (и, соответственно, заголовок `Authorization`) в таких запросах указывать не нужно. ## Метаинформация о публичном ресурсе {#meta} Зная ключ опубликованного ресурса или публичную ссылку на него, можно запросить метаинформацию об этом ресурсе (свойства файла или свойства и содержимое папки). ### Формат запроса {#meta-request} Запрос метаинформации следует отправлять с помощью метода GET. ``` https://cloud-api.yandex.net/v1/disk/public/resources ? [public_key](*popup-public_key_1)=<ключ опубликованного ресурса> & [[path](*popup-path_1)=<путь к ресурсу>] & [[sort](*popup-sort)=<атрибут сортировки>] & [[limit](*popup-limit)=<ограничение на количество возвращаемых ресурсов>] & [[preview_size](*popup-preview_size)=<размер превью>] & [[preview_crop](*popup-preview_crop)=<признак обрезки превью>] & [[offset](*popup-offset)=<смещение относительно начала списка>] ``` #### Описание query-параметров {#query} public_key[*](*popup-a) : Ключ опубликованного ресурса или публичная ссылка на ресурс. Значение параметра следует кодировать в URL-формате. path : Относительный путь к ресурсу внутри публичной папки. Указывая ключ опубликованной папки в параметре `public_key`, вы можете запросить метаинформацию любого вложенного в нее ресурса. Например, чтобы получить свойства папки `/foo`, которая вложена в опубликованную папку, передайте параметр `path=%2Ffoo`. Путь в значении параметра следует кодировать в URL-формате. sort : Атрибут, по которому нужно сортировать список ресурсов, вложенных в папку. В качестве значения можно указывать имена следующих свойств объекта [Resource](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#resource): - `name` (имя ресурса); - `path` (путь к ресурсу на Диске); - `created` (дата создания ресурса); - `modified` (дата изменения ресурса); - `size` (размер файла). Для сортировки в обратном порядке добавьте дефис к значению параметра, например: `sort=-name`. limit : Количество ресурсов, вложенных в папку, описание которых следует вернуть в ответе (используется для постраничного вывода). Значение по умолчанию — 20. preview_size : Требуемый размер уменьшенного изображения (превью файла), ссылку на которое Диск должен вернуть в ключе preview. Вы можете задать как точный размер превью, так и размер одной из сторон. Получившееся изображение можно обрезать до квадрата с помощью параметра preview_crop. {% cut "Варианты значений" %} - Предопределенный размер большей стороны. Картинка уменьшается до указанного размера по большей стороне, пропорции исходного изображения сохраняются. Например, для размера 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`, из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты (в примере — один к двум). Затем вырезанный фрагмент масштабируется до указанных размеров. {% endcut %} preview_crop : Параметр позволяет обрезать превью согласно размеру, заданному в значении параметра `preview_size`. Допустимые значения: - `false` — параметр игнорируется (по умолчанию). - `true` — превью обрезается следующим образом: - Если передана только ширина или высота, картинка уменьшается до этого размера с сохранением пропорций. Затем из центра уменьшенного изображения также вырезается квадрат с заданной стороной. - Если передан точный размер (например, `"120x240"`), из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты. Затем вырезанный фрагмент масштабируется до указанных размеров. offset : Количество ресурсов с начала списка, которые следует опустить в ответе (например, для постраничного вывода). Допустим, папка `/doc` содержит три файла. Если запросить метаинформацию о папке с параметром `offset=1`, API Диска вернет только описания второго и третьего файла. \* Обязательный параметр. #### Заголовок {#header} ``` Authorization: OAuth ``` ### Формат ответа {#meta-response} Если запрос был обработан без ошибок, API отвечает кодом `200 OK` и возвращает метаинформацию о запрошенном ресурсе в теле ответа в объекте [Resource](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#resource). Если запрос вызвал ошибку, возвращается подходящий код ответа, а тело ответа содержит [описание ошибки](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#error). Для непустых папок в ответ включается объект [ResourceList](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#resourcelist) (под именем `_embedded`). Каждый вложенный в папку ресурс является элементом массива `items`. Вне зависимости от запрошенной сортировки, ресурсы в массиве упорядочены по их виду: сначала перечисляются все вложенные папки, затем — вложенные файлы. Все пути в метаинформации для опубликованной папки указываются относительно самой папки. Пример ответа приведен для опубликованной папки `/foo`, в которой содержатся папка `/bar` и файл `photo.png`: ```json { "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" } ``` #| || **Элемент** | **Описание** || ||`public_key` | Ключ опубликованного ресурса. Включается в ответ только если указанный файл или папка опубликован.|| ||`public_url` | Ссылка на опубликованный ресурс. Включается в ответ только если указанный файл или папка опубликован.|| ||`_embedded` | Ресурсы, непосредственно содержащиеся в папке (содержит объект [ResourceList](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#resourcelist)). Включается в ответ только при запросе метаинформации о папке.|| ||`preview` | Ссылка на уменьшенное изображение из файла (превью). Включается в ответ только для файлов поддерживаемых графических форматов. Запросить превью можно только с OAuth-токеном пользователя, имеющего доступ к самому файлу.|| ||`name` | Имя ресурса.|| ||`custom_properties` | Объект со всеми атрибутами, заданными с помощью запроса [Добавление метаинформации для ресурса](https://yandex.ru/dev/disk-api/doc/ru/reference/meta-add.md). Содержит только ключи вида `имя:значение` (объекты или массивы содержать не может).|| ||`created` | Дата и время создания ресурса, в формате [ISO 8601](http://ru.wikipedia.org/wiki/ISO_8601).|| ||`modified` | Дата и время изменения ресурса, в формате [ISO 8601](http://ru.wikipedia.org/wiki/ISO_8601).|| ||`path` | Полный путь к ресурсу на Диске. В метаинформации опубликованной папки пути указываются относительно самой папки. Для опубликованных файлов значение ключа всегда «/». Для ресурса, находящегося в Корзине, к атрибуту может быть добавлен уникальный идентификатор (например, `trash:/foo_1408546879`). С помощью этого идентификатора ресурс можно отличить от других удаленных ресурсов с тем же именем.|| ||`origin_path` | Путь к ресурсу до перемещения в Корзину. Включается в ответ только для запроса метаинформации о ресурсе в Корзине.|| ||`md5` | MD5-хэш файла.|| ||`type` | Тип ресурса: - «dir» — папка; - «file» — файл.|| ||`mime_type` | MIME-тип файла.|| ||`size` | Размер файла.|| |# #| || **Элемент** | **Описание** || ||`sort` | Поле, по которому отсортирован список.|| ||`public_key` | Ключ опубликованной папки, в которой содержатся ресурсы из данного списка. Включается только в ответ на запрос [метаинформации о публичной папке](https://yandex.ru/dev/disk-api/doc/ru/reference/public.md#meta).|| ||`items` | Массив ресурсов ([Resource](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#resource)), содержащихся в папке. Вне зависимости от запрошенной сортировки, ресурсы в массиве упорядочены по их виду: сначала перечисляются все вложенные папки, затем — вложенные файлы.|| ||`limit` | Максимальное количество элементов в массиве `items`, заданное в запросе.|| ||`offset` | Смещение начала списка от первого ресурса в папке.|| ||`path` | Путь к папке, чье содержимое описывается в данном объекте `ResourceList`. Для [публичной папки](https://yandex.ru/dev/disk-api/doc/ru/reference/public.md#meta) значение атрибута всегда равно «/».|| ||`total` | Общее количество ресурсов в папке.|| |# ## Скачивание публичного файла или папки {#download} Ресурс, опубликованный на Диске, можно скачать, зная его ключ или публичную ссылку на него. Также этой операцией можно скачивать отдельные файлы из публичных папок. ### Формат запроса {#download-request} Запрос на скачивание файла следует отправлять с помощью метода GET. ``` https://cloud-api.yandex.net/v1/disk/public/resources/download ? [public_key](*popup-public_key_2)=<ключ опубликованного ресурса> & [[path](*popup-path_2)=<путь к ресурсу>] ``` #### Описание query-параметров {#query} public_key[*](*popup-a) : Ключ публичного файла или папки. Значение параметра следует кодировать в URL-формате. path : Путь к файлу внутри публичной папки. Следует указать, если в значении параметра `public_key` передан ключ публичной папки, в которой находится нужный файл. Путь в значении параметра следует кодировать в URL-формате. \* Обязательный параметр. #### Заголовок {#header} ``` Authorization: OAuth ``` ### Формат ответа {#download-response} Если запрос был обработан без ошибок, API отвечает кодом `200 OK`. В теле ответа, в объекте [Link](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#link), возвращается сгенерированный URL для скачивания файла. Если запрос вызвал ошибку, возвращается подходящий код ответа, а тело ответа содержит [описание ошибки](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#error). Пример ответа: ```json { "href": "https://downloader.dst.yandex.ru/disk/...", "method": "GET", "templated": false } ``` #| || **Элемент** | **Описание**|| || `href` | URL. Может быть шаблонизирован, см. ключ `templated`. || || `method` | HTTP-метод для запроса URL из ключа `href`. || || `templated` | Признак URL, который был шаблонизирован согласно [RFC 6570](http://tools.ietf.org/html/rfc6570). Возможные значения: - «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках. - «false» — URL может быть запрошен без изменений.|| |# Скачивать файл следует с помощью метода GET: ```no-highlight 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`. ## Сохранение публичного файла в «Загрузки» {#save} Файл, опубликованный на Диске, можно скопировать в папку «Загрузки» на Диске пользователя. Для этого нужно знать ключ файла или публичную ссылку на него. Если вы знаете ключ публичной папки, вы также можете копировать отдельные файлы из нее. ### Формат запроса {#save-request} Запрос на сохранение файла следует отправлять с помощью метода POST. ``` https://cloud-api.yandex.net/v1/disk/public/resources/save-to-disk ? [public_key](*popup-public_key_3)=<ключ опубликованного ресурса> & [[path](*popup-path_3)=<путь к ресурсу>] & [[name](*popup-name)=<имя сохраненного файла>] ``` #### Описание query-параметров {#query} public_key[*](*popup-a) : Ключ сохраняемого ресурса. Значение параметра следует кодировать в URL-формате. path : Путь внутри публичной папки. Следует указать, если в значении параметра `public_key` передан ключ публичной папки, в которой находится нужный файл. Путь в значении параметра следует кодировать в URL-формате. name : Имя, под которым файл следует сохранить в папку «Загрузки». \* Обязательный параметр. #### Заголовок {#header} ``` Authorization: OAuth ``` ### Формат ответа {#save-response} Сохранение публичного файла на Диск может занять неопределенное время. В зависимости от статуса операции, сервер Яндекс Диска возвращает один из вариантов ответа: {% list tabs %} - Операция завершена Если к моменту ответа запрос удалось обработать без ошибок, API отвечает кодом `201 Created` и возвращает ссылку на сохраненный файл в теле ответа (в объекте [Link](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#link)). Пример ответа: ```json { "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 } ``` {% include [link-table](../_includes/reference/response-objects/id-link/link-table.md) %} - Операция запущена Если операция сохранения была запущена, но еще не завершилась, Яндекс Диск отвечает кодом `202 Accepted`. Приложения должны самостоятельно следить за [статусами запрошенных операций](https://yandex.ru/dev/disk-api/doc/ru/reference/operations.md). Яндекс Диск возвращает ссылку на статус запущенной по запросу операции в теле ответа, в объекте [Link](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#link). Пример ответа: ```json { "href": "https://cloud-api.yandex.net/v1/disk/operations/33ca7d03ab21ct41b4a40182e78d828a3f8b72cdb5f4c0e94cc4b1449a63a2fe", "method": "GET", "templated": false } ``` {% include [link-table](../_includes/reference/response-objects/id-link/link-table.md) %} - Ошибка Если запрос вызвал ошибку, возвращается подходящий код ответа, а тело ответа содержит [описание ошибки](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#error). {% endlist %} [*popup-public_key_1]: Ключ опубликованного ресурса или публичная ссылка на ресурс. Значение параметра следует кодировать в URL-формате. [*popup-path_1]: Относительный путь к ресурсу внутри публичной папки. Указывая ключ опубликованной папки в параметре `public_key`, вы можете запросить метаинформацию любого вложенного в нее ресурса. Например, чтобы получить свойства папки `/foo`, которая вложена в опубликованную папку, передайте параметр `path=%2Ffoo`. Путь в значении параметра следует кодировать в URL-формате. [*popup-sort]: Атрибут, по которому нужно сортировать список ресурсов, вложенных в папку. В качестве значения можно указывать имена следующих свойств объекта [Resource](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#resource): - `name` (имя ресурса); - `path` (путь к ресурсу на Диске); - `created` (дата создания ресурса); - `modified` (дата изменения ресурса); - `size` (размер файла). Для сортировки в обратном порядке добавьте дефис к значению параметра, например: `sort=-name`. [*popup-limit]: Количество ресурсов, вложенных в папку, описание которых следует вернуть в ответе (используется для постраничного вывода). Значение по умолчанию — 20. [*popup-preview_size]: Требуемый размер уменьшенного изображения (превью файла), ссылку на которое Диск должен вернуть в ключе preview. Вы можете задать как точный размер превью, так и размер одной из сторон. Получившееся изображение можно обрезать до квадрата с помощью параметра preview_crop. {% cut "Варианты значений" %} - Предопределенный размер большей стороны. Картинка уменьшается до указанного размера по большей стороне, пропорции исходного изображения сохраняются. Например, для размера 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`, из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты (в примере — один к двум). Затем вырезанный фрагмент масштабируется до указанных размеров. {% endcut %} [*popup-preview_crop]: Параметр позволяет обрезать превью согласно размеру, заданному в значении параметра `preview_size`. Допустимые значения: - `false` — параметр игнорируется (по умолчанию). - `true` — превью обрезается следующим образом: - Если передана только ширина или высота, картинка уменьшается до этого размера с сохранением пропорций. Затем из центра уменьшенного изображения также вырезается квадрат с заданной стороной. - Если передан точный размер (например, `"120x240"`), из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты. Затем вырезанный фрагмент масштабируется до указанных размеров. [*popup-offset]: Количество ресурсов с начала списка, которые следует опустить в ответе (например, для постраничного вывода). Допустим, папка `/doc` содержит три файла. Если запросить метаинформацию о папке с параметром `offset=1`, API Диска вернет только описания второго и третьего файла. [*popup-public_key_2]: Ключ публичного файла или папки. Значение параметра следует кодировать в URL-формате. [*popup-path_2]: Путь к файлу внутри публичной папки. Следует указать, если в значении параметра `public_key` передан ключ публичной папки, в которой находится нужный файл. Путь в значении параметра следует кодировать в URL-формате. [*popup-public_key_3]: Ключ сохраняемого ресурса. Значение параметра следует кодировать в URL-формате. [*popup-path_3]: Путь внутри публичной папки. Следует указать, если в значении параметра `public_key` передан ключ публичной папки, в которой находится нужный файл. Путь в значении параметра следует кодировать в URL-формате. [*popup-name]: Имя, под которым файл следует сохранить в папку «Загрузки». [*popup-a]: Обязательный параметр. {% included (../_includes/reference/response-objects/id-link/link-table.md) %} #| || **Элемент** | **Описание**|| || `href` | URL. Может быть шаблонизирован, см. ключ `templated`. || || `method` | HTTP-метод для запроса URL из ключа `href`. || || `templated` | Признак URL, который был шаблонизирован согласно [RFC 6570](http://tools.ietf.org/html/rfc6570). Возможные значения: - «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках. - «false» — URL может быть запрошен без изменений.|| |# {% endincluded %}