Добавление метаинформации для ресурса

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

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

Запрос добавления метаинформации следует отправлять с помощью метода PATCH.

https://cloud-api.yandex.net/v1/disk/resources/
 ? path=<путь к ресурсу>
 & [fields=<свойства, которые нужно включить в ответ>]

path*

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

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

fields

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

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

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

Тело запроса

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

Переданные атрибуты добавляются к уже имеющимся. Например, передается следующий объект, с атрибутами foo и bar:

"custom_properties": {"foo":"1", "bar":"2"}

Если до этого в метаинформации ресурса не было объекта custom_properties, API просто добавит к ней переданный объект.

Если же такой объект уже имеется (например, "custom_properties": {"oof":"3", "bar":"0"}), API обновит ключи с совпадающими именами и добавит новые. В метаинформации ресурса можно будет видеть такой объект:

"custom_properties": {"oof": "3", "bar":"0", "foo":"1"}

Чтобы удалить какой-либо атрибут, следует передать его со значением null, например:

"custom_properties": {"foo": null}

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

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

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

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

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

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