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

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

Метод могут использовать как администраторы, так и другие сотрудники организации, у которых есть права на чтение данных с общего диска.

Для OAuth-приложения необходимо наличие одного из прав:

• cloud_api:disk.info
• cloud_api:disk.read

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

Метод: GET.

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

Описание query-параметров

path*

Путь к ресурсу на общем диске.

Указывается в следующем формате:

vd:<vd_hash>:disk:/<путь внутри общего диска>

Где

• <vd_hash> — метка общего диска. Пример vd_hash: 9Uyws5pZmXgDNA. Метку общего диска можно получить:

  • по API — с помощью метода, который возвращает информацию о статусе создания общего диска (посмотреть описание метода);
  • в интерфейсе Яндекс Диска — перейдите в общий диск, метка будет указана в персональной строке после vd/.

• <путь внутри общего диска> — путь до файла или папки внутри общего диска.

Например, путь до файла test_file.txt, который лежит в папке test_folder общего диска указывается так:

vd:9Uyws5pZmXgDNA:disk:/test_folder/test_file.txt

limit

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

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

offset

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

Допустим, папка /doc содержит три файла. Если запросить метаинформацию о папке с параметром 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.

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

Заголовок

Authorization: OAuth <token>

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

Успешный ответ

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

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

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

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

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

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

Resource

ResourceList

Ответ с ошибкой

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

Некоторые возможные ошибки:

• 400 — Некорректные данные.
• 401 — Не авторизован.
• 403 — Доступ к ресурсу запрещен. / Пользователь не имеет прав доступа к общему диску.
• 404 — Путь общего диска не найден.
• 406 — Ресурс не может быть представлен в запрошенном формате.
• 413 — Загрузка файла недоступна. Файл слишком большой.
• 423 — Технические работы. Сейчас можно только просматривать и скачивать файлы.
• 429 — Слишком много запросов.
• 503 — Сервис временно недоступен.

vd:<vd_hash>:disk:/<путь внутри общего диска>

vd:9Uyws5pZmXgDNA:disk:/test_folder/test_file.txt