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 может быть запрошен без изменений.

Объект содержит URL для загрузки ресурса.

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

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

Элемент

Описание

operation_id

Идентификатор операции загрузки файла.

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

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

ResourceShort

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

{
  "created_at": "2018-01-28T12:08:48.372+03:00",
  "public_hash": "R6S/Qw7oKwz2PM7DC1koM+p4QtVSb+jFDVU4QwKCoadwq9AOoMLHPuvojlS6t7TOq/J6bpmRyOJonT3VoXnDag==",
  "modified_at": "2018-01-28T12:08:48.372+03:00",
  "name": "aa_dir",
  "path": "/disk/aa_dir",
  "type": "dir"
}

Элемент

Описание

public_hash

Ключ опубликованного ресурса.

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

created_at

Дата и время создания ресурса, в формате ISO 8601.

modified_at

Дата и время изменения ресурса, в формате ISO 8601.

name

Имя ресурса.

path

Полный путь к ресурсу на Диске.

В метаинформации опубликованной папки пути указываются относительно самой папки. Для опубликованных файлов значение ключа всегда «/».

Для ресурса, находящегося в Корзине, к атрибуту может быть добавлен уникальный идентификатор (например, trash:/foo_1408546879). С помощью этого идентификатора ресурс можно отличить от других удаленных ресурсов с тем же именем.

type

Тип ресурса:

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

ResourceAccess

Описание ресурса, к которому есть доступ у сотрудника.

{
  "uid": "128280859",
  "path": "/disk/dir_admin",
  "public_hash": "/6qcdDRxMeG94WxbQWNnPnR02YBr9FBxAFS9Q9rUZRkkKKlXjO0fRKBPETdxtNvIq/J6bpmRyOJofT3VoXnDag=="
}

Элемент

Описание

uid

Идентификатор владельца публичного ресурса.

path

Полный путь к ресурсу на Диске.

В метаинформации опубликованной папки пути указываются относительно самой папки. Для опубликованных файлов значение ключа всегда «/».

Для ресурса, находящегося в Корзине, к атрибуту может быть добавлен уникальный идентификатор (например, trash:/foo_1408546879). С помощью этого идентификатора ресурс можно отличить от других удаленных ресурсов с тем же именем.

public_hash

Ключ опубликованного ресурса.

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

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

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

ResourceListShort

Список публичных ресурсов, которыми владеет сотрудник.

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

Элемент

Описание

items

Массив описаний публичных ресурсов (ResourceShort).

limit

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

offset

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

ResourceListAccess

Список публичных ресурсов, к которым есть доступ у сотрудника.

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

Элемент

Описание

items

Массив описаний публичных ресурсов (ResourceAccess).

limit

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

iteratation_key

Ключ итерирования.

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

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

PublicSettings

Список всех настроек доступа к опубликованному ресурсу.

{
  "available_until": null,
  "accesses": [ /* массив объектов PublicAccesses */ ]
}

Элемент

Описание

available_until

Время жизни ссылки на ресурс (в секундах). По истечении указанного времени ссылка на опубликованный ресурс перестанет быть действительной.

accesses

Массив объектов, которые описывают права доступа пользователей к ресурсу (PublicAccesses).

PublicAccesses

Массив объектов, которые описывают права доступа пользователей к ресурсу.

[
  {
    "rights": [
      "read_with_password_without_download"
    ],
    "org_id": 8012499,
    "type": "macro",
    "macros": [
      "employees"
    ]
  },
  {
    "id": 1130000066112015,
    "type": "user",
    "rights": [
      "read"
    ],
    "org_id": 8012499
  },
  {
    "id": 32,
    "type": "group",
    "rights": [
      "write"
    ],
    "org_id": 8012499
  },
  {
    "id": 8,
    "type": "department",
    "rights": [
      "write"
    ],
    "org_id": 8012499
  }
]

  • Общий доступ ("type": "macro")

    Элемент

    Описание

    macros

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

    • employees — общий доступ к ресурсу только внутри определенной организации;
    • all — общий доступ для всех пользователей.

    org_id

    Идентификатор организации, сотрудникам которой предоставляется общий доступ к ресурсу с правами, указанными в параметре rights данного объекта. Указывается, только если параметр macros имеет значение employees.

    type

    Уровень права доступа: macro — общий доступ.

    rights

    Права доступа к ресурсу. Возможные значения:

    • write — редактирование;
    • read — просмотр;
    • read_without_download — просмотр без возможности скачивания;
    • read_with_password — просмотр с доступом по паролю;
    • read_with_password_without_download — просмотр с доступом по паролю без возможности скачивания.

  • Персональный доступ для сотрудников ("type": "user")

    Элемент

    Описание

    id

    Уникальный идентификатор (uid) сотрудника организации, которому предоставлен персональный доступ к ресурсу с правами, указанными в параметре rights данного объекта.

    org_id

    Идентификатор организации, к которой относится сотрудник.

    type

    Уровень права доступа: user — персональный доступ для сотрудника организации.

    rights

    Права доступа к ресурсу. Возможные значения:

    • write — редактирование;
    • read — просмотр.

  • Персональный доступ для групп ("type": "group")

    Элемент

    Описание

    id

    Уникальный идентификатор (id) группы в организации, которой предоставлен персональный доступ к ресурсу с правами, указанными в параметре rights данного объекта.

    org_id

    Идентификатор организации, которой принадлежит группа.

    type

    Уровень права доступа: group — персональный доступ для группы.

    rights

    Права доступа к ресурсу. Возможные значения:

    • write — редактирование;
    • read — просмотр.

  • Персональный доступ для подразделений ("type": "department")

    Элемент

    Описание

    id

    Уникальный идентификатор (id) подразделения в организации, которому предоставлен персональный доступ к ресурсу с правами, указанными в параметре rights данного объекта.

    org_id

    Идентификатор организации, которой принадлежит подразделение.

    type

    Уровень права доступа: department — персональный доступ для подразделения.

    rights

    Права доступа к ресурсу. Возможные значения:

    • write — редактирование;
    • read — просмотр.

PublicAvailableSettings

Список всех настроек доступа к опубликованному ресурсу.

{
  "permissions": [
    "read",
    "read_with_password",
    "read_with_password_without_download",
    "read_without_download",
    "write"
  ],
  "address_access_sharing": "all",
  "use_sharing": true,
  "macro_sharing": "all",
  "default": [ /* массив объектов Default */ ]
}

Элемент

Описание

permissions

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

  • write — редактирование;
  • read — просмотр;
  • read_without_download — просмотр без возможности скачивания;
  • read_with_password — просмотр с доступом по паролю;
  • read_with_password_without_download — просмотр с доступом по паролю без возможности скачивания.

use_sharing

Признак возможности предоставлять персональный доступ на опубликованный ресурс. Возможные значения:

  • true — пользователь может предоставлять персональный доступ;
  • false — пользователь не может предоставлять персональный доступ.

address_access_sharing

На кого можно предоставить персональный доступ. Возможные значения:

  • inner — только на сотрудников организации;
  • all — на всех пользователей.

macro_sharing

На кого можно предоставить общий доступ. Возможные значения:

  • inner — только на сотрудников организации;
  • all — на всех пользователей.

accesses

Параметр предоставления доступа по-умолчанию, если флаг не включен, то отправляется пустой массив. Флаг - эксперимент public_resources_default_settings. (Default).

PublicDefault

Массив объектов, которые описывают права доступа пользователей к ресурсу.

{
  "macros": [
    "employees"
  ],
  "org_id": 8012499,
  "rights": [
    "read_with_password_without_download"
  ]
}

Элемент

Описание

macros

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

  • employees — общий доступ к ресурсу только внутри определенной организации;
  • all — общий доступ для всех пользователей.

org_id

Идентификатор организации, сотрудникам которой предоставляется общий доступ к ресурсу с правами, указанными в параметре rights данного объекта. Актуален, только если параметр macros имеет значение employees.

rights

Права доступа к ресурсу. Возможные значения:

  • write — редактирование;
  • read — просмотр;
  • read_without_download — просмотр без возможности скачивания;
  • read_with_password — просмотр с доступом по паролю;
  • read_with_password_without_download — просмотр с доступом по паролю без возможности скачивания.

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 — операция начата, но еще не завершена.

VirtualDiskList

Список общих дисков для организации.

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

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

Элемент

Описание

items

Массив общих дисков организации (VirtualDisk).

total

Общее количество общих дисков.

limit

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

offset

Смещение начала выборки от первого элемента в списке всех общих дисков.

VirtualDisk

Информация об общем диске.

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

{
  "total_space": 10737418240,
  "name": "First Group",
  "resource_id": "057583f5-3313-492b-bwb5-da428e1c9846",
  "trash_size": 0,
  "vd_hash": "9Uyws5pZmXgDNA",
  "used_space": 138936,
  "permissions": [
    "read"
  ]
}

Элемент

Описание

total_space

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

name

Наименование общего диска.

resource_id

Идентификатор общего диска в организации.

trash_size

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

vd_hash

Метка общего диска.

used_space

Количество занятого места на общем диске, в байтах.

permissions

Права доступа к общему диску, которые есть у пользователя, отправляющего запрос:

  • read — чтение данных общего диска;
  • write — запись в любом месте общего диска;
  • delete — удаление общего диска (данное право есть только у администраторов организации).

VirtualDiskResourceID

Идентификатор общего диска в организации.

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

{
  "resource_id": "440050dc-178a-4ae1-beca-ae0587e4b0bf"
}

Элемент

Описание

resource_id

Идентификатор общего диска в организации.

VirtualDiskCreateState

Идентификатор общего диска организации.

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

{
  "vd_hash": "9Uyws5pZmXgDNA",
  "resource_id": "057583f5-3313-492b-bub5-da428e0c9846",
  "description": "Описание общего_диска 1",
  "name": "Общий_диск 1",
  "state": "created"
}

Элемент

Описание

vd_hash

Метка общего диска. Является уникальной и идентифицирует конкретный общий диск в Яндекс Диске.

Значение vd_hash является действительным, только если в параметре state вернулось значение created.

resource_id

Идентификатор общего диска в организации, который направлялся в запросе. Идентифицирует конкретный общий диск в кабинете организации Яндекс 360 для бизнеса.

description

Описание общего диска.

name

Наименование общего диска.

state

Статус создания общего диска:

  • initialize — процесс создания общего диска не окончен;
  • created — общий диск создан.

VirtualDiskPermissions

Список субъектов, имеющих доступ к общему диску.

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

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

Элемент

Описание

items

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

VirtualDiskPermissionsSubject

Информация об отдельном субъекте (сотруднике, группе или подразделении), имеющем доступ к общему диску.

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

{
  "rights": [
    "read",
    "write"
  ],
  "id": 1130000006678996,
  "type": "user",
  "org_id": 123456
}

Элемент

Описание

rights

Массив прав доступа к общему диску, которые есть у субъекта:

  • read — чтение данных общего диска;
  • write — запись в любом месте общего диска.

type

Тип субъекта:

  • user — сотрудник организации;
  • group — группа;
  • department — подразделение.

id

Идентификатор субъекта:

  • для типа user — идентификатор сотрудника;
  • для типа group — идентификатор группы;
  • для типа department — идентификатор подразделения.

org_id

Идентификатор организации, к которой принадлежит субъект.

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

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

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

{
  "message": "Не авторизован.",
  "description": "Unauthorized",
  "error": "UnauthorizedError"
}

Элемент

Описание

message

Сообщение об ошибке.

description

Описание ошибки.

error

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

Ключ итерирования — параметр, который используется для управления процессом получения данных частями (постранично). Он позволяет API понимать, на каком этапе находится процесс вывода данных, и возвращать следующую порцию информации при последующих запросах.

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

Предыдущая
Статус операции
Следующая
Обратная связь