В новом уроке мы с вами пропишем методы для получения информации о файлах и директориях находящихся на Яндекс.Диск.
Получение директорий с Яндекс.Диска через API
Для получения информации из области РЕСУРСОВ нужно отправить запрос на URL
https://cloud-api.yandex.net/v1/disk/resources
Для получения информации из области КОРЗИНЫ нужно отправить запрос на URL
https://cloud-api.yandex.net/v1/disk/trash/resources
В качестве параметров вы можете передать следующие данные.
path * | Путь к нужному ресурсу относительно корневого каталога Диска. Путь к ресурсу в Корзине следует указывать относительно корневого каталога Корзины.Путь в значении параметра следует кодировать в URL-формате. |
fields | Список свойств JSON, которые следует включить в ответ. Ключи, не указанные в этом списке, будут отброшены при составлении ответа. Если параметр не указан, ответ возвращается полностью, без сокращений.Имена ключей следует указывать через запятую, а вложенные ключи разделять точками. Например: name,_embedded.items.path . |
limit | Количество ресурсов, вложенных в папку, описание которых следует вернуть в ответе (например, для постраничного вывода).Значение по умолчанию — 20. |
offset | Количество вложенных в папку ресурсов, которые следует опустить в ответе (например, для постраничного вывода). Список сортируется согласно значению параметра sort .Допустим, папка /foo содержит три файла. Если запросить метаинформацию о папке с параметром 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 . |
Метод для получения директорий принимает 2 аргумента: массив с параметрами для запроса и тип директории (активные ресурсы или корзина).
/**
* Получение директорий
*
* @param array $arrParams параметры для получения ресурсов
* @param string $typeDir тип области ресурсов
*
* @return array
*/
public function disk_resources(array $arrParams, string $typeDir = ''): array
{
switch ($typeDir) {
case 'trash':
/* запрос для директорий в корзине */
$urlQuery = 'https://cloud-api.yandex.net/v1/disk/trash/resources';
break;
case 'standart':
/* запрос для активных директорий */
$urlQuery = 'https://cloud-api.yandex.net/v1/disk/resources';
break;
}
return $this->sendQueryYaDisk($urlQuery, $arrParams);
}
Пример отправки запроса
...
$backupClass = new Backup();
$arrQuery = [
'path' => '/',
'fields' => '_embedded.items.name,_embedded.items.type',
'limit' => 100,
'offset' => 0,
'preview_crop' => '',
'preview_size' => '',
'sort' => ''
];
$backupClass->disk_resources($arrQuery);
Пример ответа
{
"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/2AEJCiNTZGiYX",
"modified": "2014-04-22T10:32:49+04:00",
"path": "disk:/foo",
"type": "dir"
}
Данные получаемые в ответе:
Элемент | Описание |
---|---|
sort | Поле, по которому отсортирован список. |
public_key | Ключ опубликованной папки, в которой содержатся ресурсы из данного списка. Включается только в ответ на запрос метаинформации о публичной папке. |
items | Массив ресурсов (Resource), содержащихся в папке. Вне зависимости от запрошенной сортировки, ресурсы в массиве упорядочены по их виду: сначала перечисляются все вложенные папки, затем — вложенные файлы. |
limit | Максимальное количество элементов в массиве items , заданное в запросе. |
offset | Смещение начала списка от первого ресурса в папке. |
path | Путь к папке, чье содержимое описывается в данном объекте ResourceList . Для публичной папки значение атрибута всегда равно «/». |
total | Общее количество ресурсов в папке. |
Получение сплошного списка файлов и директорий с Яндекс.Диска
Для получение всех файлов и директорий, без учёта структуры директорий, используют метод resources/files.
Данный API метод принимает следующие параметры:
limit | Количество файлов, описание которых следует вернуть в ответе (например, для постраничного вывода). Значение по умолчанию — 20. |
media_type | Тип файлов, которые нужно включить в список. Диск определяет тип каждого файла при загрузке. Чтобы запросить несколько типов файлов, можно перечислить их в значении параметра через запятую. Например, media_type="audio,video" .Поддерживаемые типы: - audio — аудио-файлы.- backup — файлы резервных и временных копий.- book — электронные книги.- compressed — сжатые и архивированные файлы.- data — файлы с базами данных.- development — файлы с кодом (C++, Java, XML и т. п.), а также служебные файлы IDE.- diskimage — образы носителей информации и сопутствующие файлы (например, ISO и CUE).- document — документы офисных форматов (Word, OpenOffice и т. п.).- encoded — зашифрованные файлы.- executable — исполняемые файлы.- flash — файлы с флэш-видео или анимацией.- font — файлы шрифтов.- image — изображения.- settings — файлы настроек для различных программ.- spreadsheet — файлы офисных таблиц (Excel, Numbers, Lotus).- text — текстовые файлы.- unknown — неизвестный тип.- video — видео-файлы.- web — различные файлы, используемые браузерами и сайтами (CSS, сертификаты, файлы закладок). |
offset | Количество ресурсов с начала списка, которые следует опустить в ответе (например, для постраничного вывода). Допустим, папка /foo содержит три файла. Если запросить метаинформацию о папке с параметром offset=1 , API Диска вернет только описания второго и третьего файла. |
fields | Список свойств JSON, которые следует включить в ответ. Ключи, не указанные в этом списке, будут отброшены при составлении ответа. Если параметр не указан, ответ возвращается полностью, без сокращений. Имена ключей следует указывать через запятую, а вложенные ключи разделять точками. Например: name,_embedded.items.path . |
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 , из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты (в примере — один к двум). Затем вырезанный фрагмент масштабируется до указанных размеров. |
preview_crop | Параметр позволяет обрезать превью согласно размеру, заданному в значении параметра preview_size .Допустимые значения: false — параметр игнорируется (по умолчанию).true — превью обрезается следующим образом:— Если передана только ширина или высота, картинка уменьшается до этого размера с сохранением пропорций. Затем из центра уменьшенного изображения также вырезается квадрат с заданной стороной. — Если передан точный размер (например, "120x240" ), из центра оригинального изображения вырезается фрагмент максимального размера в заданных пропорциях ширины и высоты. Затем вырезанный фрагмент масштабируется до указанных размеров. |
Отправляем запрос на получение списка файлов и директорий.
/**
* Получение плоского списка всех файлов
*
* @param array $arrParams параметры для получения ресурсов
*
* @return array
*/
public function disk_resources_files(array $arrParams = []): array
{
$urlQuery = 'https://cloud-api.yandex.net/v1/disk/resources/files';
return $this->sendQueryYaDisk($urlQuery, $arrParams);
}
Пример ответа:
{
"items": [
{
"name": "photo2.png",
"preview": "https://downloader.disk.yandex.ru/preview/...",
"created": "2014-04-22T14:57:13+04:00",
"modified": "2014-04-22T14:57:14+04:00",
"path": "disk:/foo/photo2.png",
"md5": "53f4dc6379c8f95ddf11b9508cfea271",
"type": "file",
"mime_type": "image/png",
"size": 54321
},
{
"name": "photo1.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/photo1.png",
"md5": "4334dc6379c8f95ddf11b9508cfea271",
"type": "file",
"mime_type": "image/png",
"size": 34567
}
],
"limit": 20,
"offset": 0
}
Описание элементов ответа:
Элемент | Описание |
---|---|
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 | Размер файла. |
Получение последних добавленных файлов и директорий
Для получения последних добавленных ресурсов используется метод resources/last-uploaded. Данный метод использует те же параметры, что и resources/files.
/**
* Получение последних загруженных элементов
*
* @param array $arrParams параметры для получения ресурсов
*
* @return array
*/
public function disk_resources_last_uploaded(array $arrParams = []): array
{
$urlQuery = 'https://cloud-api.yandex.net/v1/disk/resources/last-uploaded';
return $this->sendQueryYaDisk($urlQuery, $arrParams);
}
Таким образом мы с вами научились запрашивать информацию о имеющихся файлах и директориях на Яндекс.Диске.
В следующем уроке я вам покажу как загружать и скачивать файлы с Яндекс.Диска.