Метаинформация о файле или папке

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

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

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

Запрос метаинформации следует отправлять с помощью метода GET. URL запроса немного отличается для запроса ресурсов, находящихся в Корзине.

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

Путь к нужному ресурсу относительно корневого каталога Диска. Путь к ресурсу в Корзине следует указывать относительно корневого каталога Корзины.

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

fields

Список свойств JSON, которые следует включить в ответ. Ключи, не указанные в этом списке, будут отброшены при составлении ответа. Если параметр не указан, ответ возвращается полностью, без сокращений.

Имена ключей следует указывать через запятую, а вложенные ключи разделять точками. Например: name,_embedded.items.path.

limit

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

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

offset

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

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

preview_crop

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

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

  • false — параметр игнорируется (по умолчанию).

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

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

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

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

sort

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

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

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

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

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

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

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

{
  "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmokRUCIo8=",
  "_embedded": {
    "sort": "",
    "path": "disk:/foo",
    "items": [
      {
        "path": "disk:/foo/bar",
        "type": "dir",
        "name": "bar",
        "modified": "2014-04-22T10:32:49+04:00",
        "created": "2014-04-22T10:32:49+04:00"
      },
      {
        "name": "photo.png",
        "preview": "https://downloader.disk.yandex.ru/preview/...",
        "created": "2014-04-21T14:57:13+04:00",
        "modified": "2014-04-21T14:57:14+04:00",
        "path": "disk:/foo/photo.png",
        "md5": "4334dc6379c8f95ddf11b9508cfea271",
        "type": "file",
        "mime_type": "image/png",
        "size": 34567
      }
    ],
    "limit": 20,
    "offset": 0
  },
  "name": "foo",
  "created": "2014-04-21T14:54:42+04:00",
  "custom_properties": {"foo":"1", "bar":"2"},
  "public_url": "https://yadi.sk/d/2AEJCiNTZGiYX",
  "modified": "2014-04-22T10:32:49+04:00",
  "path": "disk:/foo",
  "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

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