--- metadata: - name: generator content: Diplodoc Platform v5.44.0 alternate: - https://yandex.ru/dev/disk-api/doc/en/reference/meta-add.md - https://yandex.ru/dev/disk-api/doc/ru/reference/meta-add.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/disk-api/doc/ru/llms.txt # Добавление метаинформации для ресурса Для любого файла или папки, доступной на запись, можно задать дополнительные произвольные атрибуты. Эти атрибуты будут возвращаться в ответ на все запросы метаинформации о ресурсах ([список всех файлов](https://yandex.ru/dev/disk-api/doc/ru/reference/all-files.md), [последние загруженные](https://yandex.ru/dev/disk-api/doc/ru/reference/recent-upload.md) и т. д.). ## Формат запроса {#format} Запрос добавления метаинформации следует отправлять с помощью метода PATCH. ``` https://cloud-api.yandex.net/v1/disk/resources/ ? [path](*popup-path)=<путь к ресурсу> & [[fields](*popup-fields)=<свойства, которые нужно включить в ответ>] ``` ### Описание query-параметров {#query} path[*](*popup-a) : Путь к нужному ресурсу относительно корневого каталога Диска. Путь к ресурсу в Корзине следует указывать относительно корневого каталога Корзины. Путь в значении параметра следует кодировать в URL-формате. fields : Список свойств JSON, которые следует включить в ответ. Ключи, не указанные в этом списке, будут отброшены при составлении ответа. Если параметр не указан, ответ возвращается полностью, без сокращений. Имена ключей следует указывать через запятую, а вложенные ключи разделять точками. Например: `name,_embedded.items.path`. \* Обязательный параметр. ### Заголовок {#header} ``` Authorization: OAuth Content-Type: application/json ``` ### Тело запроса {#body} Добавляемые атрибуты следует передавать в теле запроса, в свойствах объекта `custom_properties` (можно передавать любые части объекта [Resource](https://yandex.ru/dev/disk-api/doc/ru/reference/response-objects.md#resource), но все кроме `custom_properties` будет проигнорировано). Атрибуты могут быть только свойствами вида `имя:значение` и, соответственно, не могут быть массивами или родительскими объектами. {% note alert "Ограничение" %} Ограничение на длину объекта `custom_properties` (имена и значения вложенных ключей, а также синтаксические знаки) — 1024 символа. {% endnote %} Переданные атрибуты добавляются к уже имеющимся. Например, передается следующий объект, с атрибутами `foo` и `bar`: ```json "custom_properties": {"foo":"1", "bar":"2"} ``` Если до этого в метаинформации ресурса не было объекта `custom_properties`, API просто добавит к ней переданный объект. Если же такой объект уже имеется (например, `"custom_properties": {"oof":"3", "bar":"0"}`), API обновит ключи с совпадающими именами и добавит новые. В [метаинформации ресурса](https://yandex.ru/dev/disk-api/doc/ru/reference/meta.md) можно будет видеть такой объект: ```json "custom_properties": {"oof": "3", "bar":"0", "foo":"1"} ``` Чтобы удалить какой-либо атрибут, следует передать его со значением `null`, например: ```json "custom_properties": {"foo": null} ``` ## Формат ответа {#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`.Вне зависимости от запрошенной сортировки, ресурсы в массиве упорядочены по их виду: сначала перечисляются все вложенные папки, затем — вложенные файлы. ```json { "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/AaaBbb1122Ccc", "modified": "2014-04-22T10:32:49+04:00", "path": "disk:/foo", "type": "dir" } ``` Описание элементов ответа {#response} #| || **Элемент** | **Описание** || ||`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` | Общее количество ресурсов в папке.|| |# [*popup-path]: Путь к нужному ресурсу относительно корневого каталога Диска. Путь к ресурсу в Корзине следует указывать относительно корневого каталога Корзины. Путь в значении параметра следует кодировать в URL-формате. [*popup-fields]: Список свойств JSON, которые следует включить в ответ. Ключи, не указанные в этом списке, будут отброшены при составлении ответа. Если параметр не указан, ответ возвращается полностью, без сокращений. Имена ключей следует указывать через запятую, а вложенные ключи разделять точками. Например: `name,_embedded.items.path`. [*popup-a]: Обязательный параметр.