Список элементов в корзине общего диска

Метод возвращает список ресурсов, которые содержатся в корзине общего диска.

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

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

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

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

Метод: GET.

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

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

path*

Путь к корзине общего диска или паке внутри нее.

Указывается в следующем формате: vd:<vd_hash>:trash:/ — для корзины или vd:<vd_hash>:trash:/<путь к папке> — для папки внутри корзины, где:

  • <vd_hash> — метка общего диска. Пример vd_hash: 9Uyws5pZmXgDNA. Метку общего диска можно получить:
    • по API — с помощью метода, который возвращает информацию о статусе создания общего диска (посмотреть описание метода);
    • в интерфейсе Яндекс Диска — перейдите в общий диск, метка будет указана в персональной строке после vd/.
  • <путь к папки> — путь к папке от корневого каталога корзины общего диска.
limit

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

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

offset

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

Допустим, папка /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 информацию о корзине общего диска (или о паке в корзине, если запрос содержал путь к папке). Содержащиеся внутри нее ресурсы описываются в параметре _embedded объектом ResourceList. Каждый вложенный ресурс является элементом массива items.

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

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

{
    "_embedded": {
        "sort": "",
        "items": [
            {
                "name": "test",
                "exif": {},
                "created": "2025-02-25T09:59:00+00:00",
                "resource_id": "1130000068688485:afa2391fef087eee4119e6c6440be32481405c91696438e65588df6962b09bab",
                "modified": "2025-02-25T10:00:03+00:00",
                "path": "vd:/uiQRSrv1U4lBCg/trash/test_cdc9a19ca7baebedb13bc116ed176488d0dc75fb",
                "comment_ids": {
                    "private_resource": "1130000068688485:afa2391fef087eee4119e6c6440be32481405c91696438e65588df6962b09bab",
                    "public_resource": "1130000068688485:afa2391fef087eee4119e6c6440be32481405c91696438e65588df6962b09bab"
                },
                "type": "dir",
                "revision": 1740477606993879
            },
            {
                "antivirus_status": "clean",
                "size": 37,
                "comment_ids": {
                    "private_resource": "1130000068688485:7d215e6208a5a5d8e7e19e3d0f60f1af3e85bbebdfe83d27f6fff0461bba522d",
                    "public_resource": "1130000068688485:7d215e6208a5a5d8e7e19e3d0f60f1af3e85bbebdfe83d27f6fff0461bba522d"
                },
                "name": "testSHD1.txt",
                "exif": {},
                "created": "2025-02-25T08:36:24+00:00",
                "resource_id": "1130000068688485:7d215e6208a5a5d8e7e19e3d0f60f1af3e85bbebdfe83d27f6fff0461bba522d",
                "modified": "2025-02-25T08:36:28+00:00",
                "mime_type": "text/plain",
                "file": "https://downloader.disk.yandex.ru/disk/1772d83b8dcc0246e05bc8182e9690cf658b1241b438588ba651734d3caea3b1/67bdd946/...",
                "path": "vd:/uiQRSrv1U4lBCg/trash/testSHD1.txt_f613c836d971ec52ab653952de89796f3143f946",
                "media_type": "text",
                "sha256": "60ea65b3fa28675708ef0ceecb8565cf32a2e4bd97de6dfda48951f8f61b62cb",
                "type": "file",
                "md5": "84a897b43b09bac95f26cb6bc05cdbc2",
                "revision": 1740472588376851
            },
            {
                "antivirus_status": "clean",
                "size": 37,
                "comment_ids": {
                    "private_resource": "1130000068688485:32ffd2080f4d37e6b62ccf897577d16a3280bd4a343e327ef535fabacb522f92",
                    "public_resource": "1130000068688485:32ffd2080f4d37e6b62ccf897577d16a3280bd4a343e327ef535fabacb522f92"
                },
                "name": "testSHD2.txt",
                "exif": {},
                "created": "2025-02-25T08:37:16+00:00",
                "resource_id": "1130000068688485:32ffd2080f4d37e6b62ccf897577d16a3280bd4a343e327ef535fabacb522f92",
                "modified": "2025-02-25T08:37:40+00:00",
                "mime_type": "text/plain",
                "file": "https://downloader.disk.yandex.ru/disk/fba782829cd96b93e8ab990d6c41439fbc420adb986016fb1f91d17c538c300f/67bdd946/...",
                "path": "vd:/uiQRSrv1U4lBCg/trash/testSHD2.txt_ea8b3f48c8051a462a045b3a0589faf95ec64c26",
                "media_type": "text",
                "sha256": "60ea65b3fa28675708ef0ceecb8565cf32a2e4bd97de6dfda48951f8f61b62cb",
                "type": "file",
                "md5": "84a897b43b09bac95f26cb6bc05cdbc2",
                "revision": 1740472660674421
            }
        ],
        "limit": 20,
        "offset": 0,
        "path": "vd:/uiQRSrv1U4lBCg/trash",
        "total": 3
    },
    "name": "trash",
    "exif": {},
    "resource_id": "1130000068688485:687c09a4417c6aa2b309f7975e15ffa814499e3daec87d89bcb5e263cd456e64",
    "created": "2012-04-04T20:00:00+00:00",
    "modified": "2012-04-04T20:00:00+00:00",
    "path": "vd:/uiQRSrv1U4lBCg/trash",
    "comment_ids": {},
    "type": "dir",
    "revision": 1738913631920075
}
{
    "_embedded": {
        "sort": "",
        "items": [
            {
                "antivirus_status": "clean",
                "size": 114448,
                "comment_ids": {
                    "private_resource": "1130000068688584:16756726bae142f7b503b5ab733460d97a598b4016c54ce08634d60f1434a8bf",
                    "public_resource": "1130000068688584:16756726bae142f7b503b5ab733460d97a598b4016c54ce08634d60f1434a8bf"
                },
                "name": "test1.txt",
                "exif": {},
                "created": "2025-02-25T09:59:14+00:00",
                "resource_id": "1130000068688584:16756726bae142f7b503b5ab733460d97a598b4016c54ce08634d60f1434a8bf",
                "modified": "2025-02-25T09:59:14+00:00",
                "mime_type": "text/html",
                "file": "https://downloader.disk.yandex.ru/disk/2283c55b73ce2de829a2ee30e6ff5eb5a8b8bc03096ba4d318dedbe978a0c20f/67bdd623/fKqInKw3d7bLFOeFnMGnhF2hGW2sVNrsoY1ZHN9lRYCGV3f7iPqebSpte-Vabaaf5MgIeMeQReMkC8EtvHsdTaMfIFVy7ohKOkNW1XDzLE-r8npumZHI4midPdWhecNq?uid=1130000062907327&filename=test_txt.txt&disposition=attachment&hash=&limit=0&content_type=text%2Fhtml&owner_uid=1130000062907327&fsize=114448&hid=5959b555f13faf0ff9945f377923ddc7&media_type=document&tknv=v2&etag=912c411473b2df86efa3f0acd546038e",
                "path": "vd:/uiQRSrv5U4lADg/trash/test_cdc9a19ca7baebedb58bc116ed176488d0dc54fb/test_txt.txt",
                "media_type": "document",
                "sha256": "1f3db9f89801571fc10f739bef6981e777e6a44438cb1b180b5a35cbd132f494",
                "type": "file",
                "md5": "912c411853b2df86efa3f0acd546043e",
                "revision": 1740477604872578
            }
        ],
        "limit": 20,
        "offset": 0,
        "path": "vd:/uiQRSrv1U4lBCg/trash/test_cdc9a19fb7baebedb13bc116ed176488d0dc23fb",
        "total": 1
    },
    "name": "test",
    "exif": {},
    "resource_id": "1130000068688584:abd2391fef087fff4119e6c6440be32481405c91696438e49588fb6962b09bab",
    "created": "2025-02-25T09:59:00+00:00",
    "modified": "2025-02-25T10:00:03+00:00",
    "path": "vd:/uiQRSrv5U4lADg/trash/test_cdc9a19fb7baebedb13bc116ed176488d0dc23fb",
    "comment_ids": {
        "private_resource": "1130000068688584:afa2391fef087fff5236e6c6440be32481405c91696438e49588fb6962b09bab",
        "public_resource": "1130000068688584:afa2391fef087fff5236e6c6440be32481405c91696438e49588fb6962b09bab"
    },
    "type": "dir",
    "revision": 1740477606993879
}

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

Resource

Элемент

Описание

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

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

ResourceList

Элемент

Описание

sort

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

public_key

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

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

items

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

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

limit

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

offset

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

path

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

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

total

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

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

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

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

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

Путь к корзине общего диска или паке внутри нее.

Указывается в следующем формате: vd:<vd_hash>:trash:/ — для корзины или vd:<vd_hash>:trash:/<путь к папке> — для папки внутри корзины, где:

  • <vd_hash> — метка общего диска. Пример vd_hash: 9Uyws5pZmXgDNA. Метку общего диска можно получить:
    • по API — с помощью метода, который возвращает информацию о статусе создания общего диска (посмотреть описание метода);
    • в интерфейсе Яндекс Диска — перейдите в общий диск, метка будет указана в персональной строке после vd/.
  • <путь к папки> — путь к папке от корневого каталога корзины общего диска.

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

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

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

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

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

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

  • false — параметр игнорируется (по умолчанию).
  • true — превью обрезается следующим образом:

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

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

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

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

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

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