20.07.2023 17:38
Prog-Time 0 459 Источник

В новом уроке мы с вами пропишем методы для получения информации о файлах и директориях находящихся на Яндекс.Диске.

Полный список всех записей курса находится на сайте https://prog-time.ru/course_cat/yandeks-disk-api-php/ или в публикациях на Хабр https://habr.com/ru/users/Prog-Time/posts/

Получение директорий с Яндекс.Диска через 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-&gt;sendQueryYaDisk($urlQuery, $arrParams);

}

Пример отправки запроса

...
$yaClass = new Backup();
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);
}

Таким образом мы с вами научились запрашивать информацию о имеющихся файлах и директориях на Яндекс.Диске.

В следующем уроке я вам покажу как загружать и скачивать файлы с Яндекс.Диска.

Комментарии (0)