JSON-объекты в ответах

Каждый ответ API Диска состоит из объектов определенной структуры. В этом разделе описаны все встречающиеся в ответах объекты.

Объект содержит URL для запроса метаданных ресурса.

Пример объекта:

{
  "href": "https://cloud-api.yandex.net/v1/disk/resources?path=disk%3A%2Ffoo%2Fphoto.png",
  "method": "GET",
  "templated": false
}

Элемент

Описание

href

URL. Может быть шаблонизирован, см. ключ templated.

method

HTTP-метод для запроса URL из ключа href.

templated

Признак URL, который был шаблонизирован согласно RFC 6570. Возможные значения:

  • «true» — URL шаблонизирован: прежде чем отправлять запрос на этот адрес, следует указать нужные значения параметров вместо значений в фигурных скобках.
  • «false» — URL может быть запрошен без изменений.

Resource

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

{
  "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmoktUCIo8=",
  "_embedded": { /* объект ResourceList */ },
  "name": "photo.png",
  "created": "2014-04-21T14:57:13+04:00",
  "custom_properties": {"foo": "1", "bar": "2"},
  "public_url": "https://yadi.sk/d/AaaBbb1122Ccc",
  "origin_path": "disk:/foo/photo.png",
  "modified": "2014-04-21T14:57:14+04:00",
  "path": "disk:/foo/photo.png",
  "md5": "4334dc6379c8f95ddf11b8508cfea271",
  "type": "file",
  "mime_type": "application/x-www-form-urlencoded",
  "size": 34567
}

Элемент

Описание

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

Список ресурсов, содержащихся в папке. Содержит объекты Resource и свойства списка.

{
  "sort": "",
  "public_key": "HQsmHLoeyBlJf8Eu1jlmzuU+ZaLkjPkgcvmoktUCIo8=",
  "items": [ /* массив объектов Resource */ ],
  "path": "disk:/foo",
  "limit": 20,
  "offset": 0,
  "total": 3
}

Элемент

Описание

sort

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

public_key

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

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

items

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

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

limit

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

offset

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

path

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

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

total

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

FilesResourceList

Плоский список всех файлов на Диске в алфавитном порядке.

{
  "items": [ /* массив объектов Resource */ ],
  "limit": 20,
  "offset": 0
}

Элемент

Описание

items

Массив последних загруженных файлов (Resource).

limit

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

offset

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

LastUploadedResourceList

Список последних добавленных на Диск файлов, отсортированных по дате загрузки (от поздних к ранним).

{
  "items": [ /* массив объектов Resource */ ],
  "limit": 20
}

Элемент

Описание

items

Массив последних загруженных файлов (Resource).

limit

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

PublicResourcesList

Список опубликованных файлов на Диске.

{
  "items": [ /* массив объектов Resource */ ],
  "type": "dir",
  "limit": 20,
  "offset": 0
}

Элемент

Описание

items

Массив последних загруженных файлов (Resource).

limit

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

type

Тип ресурса:

  • «dir» — папка;
  • «file» — файл.

offset

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

Disk

Данные о свободном и занятом пространстве на Диске

Пример ответа с этими данными:

{
  "trash_size": 4631577437,
  "total_space": 319975063552,
  "used_space": 26157681270,
  "system_folders":
  {
    "applications": "disk:/Приложения",
    "downloads": "disk:/Загрузки/"
  }
}

Элемент

Описание

trash_size

Объем файлов, находящихся в Корзине, в байтах.

total_space

Общий объем Диска, доступный пользователю, в байтах.

used_space

Объем файлов, уже хранящихся на Диске, в байтах.

system_folders

Абсолютные адреса системных папок Диска. Имена папок зависят от языка интерфейса пользователя в момент создания персонального Диска. Например, для англоязычного пользователя создается папка Downloads, для русскоязычного — Загрузки и т. д.

На данный момент поддерживаются следующие папки:

  • applications — папка для файлов приложений;
  • downloads — папка для файлов, загруженных из интернета (не с устройства пользователя).

Operation

Статус операции. Операции запускаются, когда вы копируете, перемещаете или удаляете непустые папки. URL для запроса статуса возвращается в ответ на такие запросы.

Пример ответа со статусом операции:

{
  "status":"success"
}

Элемент

Описание

status

Статус операции. Возможные значения:

  • success — операция успешно завершена.
  • failed — операцию совершить не удалось, попробуйте повторить изначальный запрос копирования, перемещения или удаления.
  • in-progress — операция начата, но еще не завершена.

Ошибка при обработке запроса

Ошибка может произойти, если запрос составлен некорректно, указанный ресурс отсутствует на сервере, сервер неработоспособен и т. п. Все ошибки возвращаются с соответствующими кодами HTTP-ответа. Все возможные коды ответа и пояснения к ним приведены на Полигоне (чтобы увидеть их, разверните нужный запрос и нажмите ссылку Показать рядом с заголовком Сообщения ответа).

Дополнительно ошибки описываются JSON-объектом, например:

{
  "description": "resource already exists",
  "error": "PlatformResourceAlreadyExists"
}

Элемент

Описание

description

Подробное описание ошибки в помощь разработчику.

error

Идентификатор ошибки для программной обработки.

Предыдущая
Следующая