7.17. Работа с содержимым хранилища через API

Для отправки запросов используйте ваш адрес хранилища.

Получение токена:

1. Создайте пользователя веб-интерфейса (если не создан).
2. Авторизуйтесь с помощью логина и пароля созданного пользователя и получите токен.

Далее используйте полученный токен при работе с остальными методами (токен указывается в заголовке Authorization: Bearer).

Авторизация и загрузка файла в хранилище:

<?php

// Адрес хоста хранилища, выводится вверху раздела в панели управления
$host = 'example.cdn.express';

// Файл, который нужно загрузить в хранилище
$file = '/path/to/local/file.ext';

// Путь для загрузки в хранилище и исходное имя файла
$path = '/upload/dir/' . basename($file);

// Логин пользователя веб-доступа к хранилищу (данные можно получить в панели управления на вкладке "Пользователи и API")
$login = 'storage_login';

// Пароль пользователя веб-доступа к хранилищу
$password = 'storage_password';

$curl = curl_init();

// Авторизация
curl_setopt($curl, CURLOPT_URL, 'https://' . $host . '/~/api/auth');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_POSTFIELDS, ['login' => $login, 'password' => $password]);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: multipart/form-data']);
$json = curl_exec($curl);
$token = json_decode($json, true)['data']['token'];
if (!empty($token)) {
    echo 'Authenticated successfully' . PHP_EOL;
} else {
    // Проверьте правильность указания хоста, логина и пароля
    echo 'Authentication failed. Check host, login and password.' . PHP_EOL;
    exit;
}

// Загрузка файла (если файл уже существует в хранилище, будет ошибка)
echo 'Uploading ' . $file . ' ... ';
curl_setopt($curl, CURLOPT_VERBOSE, 1);
curl_setopt($curl, CURLOPT_URL, 'https://' . $host . '/~/api/file?path=' . urlencode($path));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($curl, CURLOPT_PUT, true);
curl_setopt($curl, CURLOPT_INFILE, fopen($file, 'rb'));
curl_setopt($curl, CURLOPT_INFILESIZE, filesize($file));
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $token]);
var_dump(curl_exec($curl));
$success = curl_getinfo($curl)['http_code'] === 200;
if ($success) {
    echo 'success.' . PHP_EOL;
} else {
    echo 'failed.' . PHP_EOL;
}
curl_close($curl);

Методы для работы с токенами.

PUT /~/api/auth

Параметры в теле запроса:
multipart/form-data

• login — логин пользователя веб-доступа.
• password — пароль пользователя веб-доступа.
• remember — срок действия токена:
  • 0 — 6 часов (значение по умолчанию).
  • 1 — 7 дней.

Авторизует под указанным пользователем и возвращает токен со сроком действия.

Ответ:

• token — токен для использования в заголовке Authorization: Bearer при работе с остальными методами.
• till — временная метка окончания срока действия токена.

DELETE /~/api/auth

Токен передаётся в заголовке (как в остальных методах).

Деактивирует полученный ранее токен.

Методы для работы с каталогами и получения их содержимого.

GET /~/api/directory

Параметры запроса:

• path — путь к каталогу, содержимое которого нужно получить (в одном запросе можно указывать несколько параметров path — данные будут возвращаться по уникальным значениям с сортировкой по длине пути в сторону увеличения).
• recursive (необязательный) — рекурсивное получение данных:
  • 0 — получить содержимое только указанного каталога (значение по умолчанию).
  • 1 — получить содержимое указанного каталога и всех его подкаталогов.
• iterator (необязательный) — получение данных в специальном формате, когда вместо одного большого JSON ответ содержит строки с отдельными JSON для каждого элемента каталога. Это позволяет существенно экономить оперативную память при обработке содержимого каталогов с большим количеством элементов — можно просматривать ответ построчно, находить JSON только нужного элемента и распаковать его без необходимости распаковки большого JSON со всеми элементами.
  • 0 — получить ответ в виде одного большого JSON (значение по умолчанию).
  • 1 — получить ответ в виде строк с отдельными JSON.

Ответ содержит список объектов с информацией по каждому из них:

• name — имя файла или каталога.
• path — путь к объекту от корня хранилища.
• isDirectory — тип объекта: каталог или нет.
• size — размер файла в байтах (для каталогов всегда 4096).
• mtime — временная метка последнего изменения содержимого объекта.
• ctime — временная метка последнего изменения метаданных объекта.
• birthtime — временная метка создания или загрузки объекта.
• media — тип медиа (для медиафайлов).
• ext — расширение (для файлов с расширением).
• share — информация о наличии публичной ссылки: ID публичной ссылки или null (при нескольких параметрах path или рекурсивном получении данных всегда null).
• uri — URI файла в зависимости от статуса публичного доступа:
  • Публичный доступ включён — прямая ссылка.
  • Публичный доступ отключён — защищённая ссылка (начинается с /~/secure/).

PUT /~/api/directory

Параметры в теле запроса:
multipart/form-data

• path — путь к новому каталогу.

Создаёт новый каталог по указанному пути.

POST /~/api/directory

Параметры в теле запроса:
multipart/form-data

• path — путь к каталогу, который нужно переименовать или переместить.
• dest — новый путь или название каталога (путь должен существовать).
• overwrite — режим перезаписи, если целевой каталог уже существует:
  • 0 — не перезаписывать и возвращать ошибку (значение по умолчанию).
  • 1 — заменять содержимое существующего каталога.

Переименовывает или перемещает указанный каталог.

DELETE /~/api/directory

Параметры запроса:

• path — путь к каталогу, который нужно удалить.

Удаляет указанный каталог со всем содержимым. Родительские каталоги не затрагиваются.

Методы для работы с файлами.

PUT /~/api/file

Параметры запроса:

• path — путь для загрузки с именем файла.
• overwrite — режим перезаписи, если целевой файл уже существует:
  • 0 — не перезаписывать и возвращать ошибку (значение по умолчанию).
  • 1 — заменять существующий файл.

Загружает файл по указанному пути (от корня хранилища).

Пример кода на PHP см. в начале статьи.

Команда для загрузки файла из консоли:

curl -X PUT 'https://example.cdn.express/~/api/file' --header 'Authorization: Bearer <token>' --data-binary '@/path/to/local/file.ext' --url-query 'path=/upload/dir/file.ext'

Для обеспечения максимальной скорости файлы скачиваются не через метод, а с помощью GET-запроса по прямой или защищённой ссылке на файл.

1. Получите список файлов каталога, в котором находится файл, который нужно скачать.
2. Из списка получите URI нужного файла.
3. Отправьте GET-запрос на адрес хранилища с полученным URI.

PUT /~/api/archive

Параметры в теле запроса:
application/json

• items — пути к файлам и каталогам, которые нужно скачать.

Скачивает перечисленные объекты в виде архива в формате .zip (все объекты должны существовать).

HEAD /~/api/file

Параметры запроса:

• path — путь к файлу или каталогу, существование которого нужно проверить.

Проверяет существование файла или каталога по указанному пути: ответ 200 — существует, ответ 404 — не существует.

POST /~/api/file

Параметры в теле запроса:
multipart/form-data

• path — путь к файлу, который нужно переименовать или переместить.
• dest — новый путь или имя файла (путь должен существовать).
• overwrite — режим перезаписи, если целевой файл уже существует:
  • 0 — не перезаписывать и возвращать ошибку (значение по умолчанию).
  • 1 — заменять существующий файл.

Переименовывает или перемещает указанный файл.

DELETE /~/api/file

Параметры запроса:

• path — путь к файлу, который нужно удалить.

Удаляет указанный файл. Родительские каталоги не затрагиваются.

Методы для работы с публичными ссылками.

PUT /~/api/share

Параметры запроса:

• path — путь к файлу или каталогу, для которого нужно создать публичную ссылку.
• write — статус доступа к изменению содержимого каталога: 1 (доступ разрешён) или 0 (доступ запрещён).
• deathtime (необязательный) — временная метка автоматического удаления ссылки (должна быть больше текущей даты, 0 — не удалять).

Создаёт публичную ссылку для указанного объекта.

Ответ:

• id — ID публичной ссылки.
• path — путь к объекту публичной ссылки.
• birthtime — временная метка создания публичной ссылки.
• isDirectory — тип объекта: каталог или нет.
• exists — существование объекта публичной ссылки (при создании всегда true).
• deathtime — временная метка автоматического удаления ссылки (если передавалась в запросе) или 0.
• writeAccess — статус доступа к изменению содержимого каталога (по умолчанию всегда false, настраивается отдельным методом),
• uri — URI публичной ссылки (начинается с /~/share/).

GET /~/api/share

Параметры запроса:

• id (необязательный) — ID публичной ссылки, по которой нужно получить данные.

Возвращает список публичных ссылок и их данные. Если указан ID публичной ссылки — возвращает данные только этой ссылки.

Ответ содержит список ссылок с информацией по каждой из них (или информацию по конкретной ссылке, если запрос был с указанием ID):

• id — ID публичной ссылки.
• path — путь к объекту публичной ссылки.
• isDirectory — тип объекта: каталог или нет.
• writeAccess — статус доступа к изменению содержимого каталога (по умолчанию всегда false, настраивается отдельным методом),
• birthtime — временная метка создания публичной ссылки.
• deathtime — временная метка автоматического удаления ссылки (если передавалась в запросе) или 0.
• exists — существование объекта публичной ссылки (если файл или каталог были переименованы, перемещены или удалены, будет false).
• uri — URI публичной ссылки (начинается с /~/share/).

POST /~/api/share

Параметры запроса:

• id — ID публичной ссылки, для которой нужно изменить права доступа (только для ссылок на каталоги).

Параметры в теле запроса:
multipart/form-data

• write — статус доступа к изменению содержимого каталога: 1 (доступ разрешён) или 0 (доступ запрещён).

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

Ответ аналогичен получению списка ссылок.

DELETE /~/api/share

Параметры запроса:

• id — ID публичной ссылки, которую нужно удалить.

Удаляет публичную ссылку с указанным ID. Объект, на который указывала ссылка, не затрагивается.

GET /~/api/link

Параметры запроса:

• path — путь к файлу от корня хранилища.
• time (необязательный) — временная метка окончания жизни ссылки (должна быть больше текущей даты).
• ip (необязательный) — IP-адрес, которому будет разрешён доступ к файлу по ссылке.

Генерирует и возвращает Secure Link для указанного файла с заданными параметрами.

Ответ:

• token — закодированный хеш совокупности данных секретного ключа, пути и параметров.
• uri — URI ссылки (начинается с /secure/).
• url — полная ссылка.
• params:
  • ip — IP-адрес, для которого разрешён доступ к файлу по ссылки (если передавался в запросе).
  • time — временная метка окончания жизни ссылки (если передавалась в запросе).
  • path — путь к файлу от корня хранилища.
• stat:
  • size — размер файла, на который указывает ссылка (в байтах).
  • atimeMs — временная метка последнего доступа к файлу (в миллисекундах).
  • mtimeMs — временная метка последнего изменения содержимого файла (в миллисекундах).
  • ctimeMs — временная метка последнего изменения метаданных файла (в миллисекундах).
  • birthtimeMs — временная метка создания файла (в миллисекундах).

• 200 — запрос выполнен успешно.
• 400 — ошибка при выполнении запроса.
  • В теле ответа будет описание ошибки, например «File exists», если загружаемый файл уже существует, или «Item not found», если не найден ID публичной ссылки.
• 401 — не выполнена авторизация.
  • В теле ответа будет либо «Invalid credential 'login' or 'password'», если ошибка возникла во время авторизации, либо «Unauthorized» во всех остальных случаях.
• 403 — доступ заблокирован.
• 404 — указанный в запросе файл или путь не существует.
• 429 — слишком много запросов.
• 502/503 — нужно подождать перед отправкой следующего запроса.
  • Например, запрос попал на момент перезапуска API или сервер был нагружен и не успел обработать запрос.

В зависимости от статуса авторизации и типа запроса ответы API содержат дополнительные заголовки.

Для всех запросов:

• x-storage-name — название или псевдоним хранилища (если установлен).
• x-storage-logo — логотип из настроек хранилища: если установлен — URL файла логотипа (домен cdn.adm.tools).
• x-storage-mode — статус вида при открытии в настройках хранилища: list (список) или table (галерея).

Для запросов с авторизацией:

• x-user-login — логин пользователя веб-доступа.
• x-user-write — право на запись пользователя веб-доступа: 1 (есть доступ) или 0 (нет доступа).
• x-user-till — временная метка окончания срока действия токена.

Для запросов проверки существования и скачивания:

• x-stat-directory — тип объекта: каталог или нет.
• x-stat-mtime — временная метка последнего изменения содержимого объекта.
• x-stat-ctime — временная метка последнего изменения метаданных объекта.
• x-stat-birthtime — временная метка создания или загрузки объекта.
• x-stat-size — размер файла в байтах (для каталогов всегда 4096).

Подготовка к работе с Postman:

1. Импорт файлов коллекции и окружения:
   1. Скачайте файлы:
      • cdn.express.json
      • cdn.express.env.json
   2. В главном меню выберите «File → Import» (или нажмите Ctrl+O), выберите скачанные файлы и импортируйте их.
2. Настройте окружение:
   1. В левой панели выберите «Environments».
   2. В списке окружений выберите «storage».
   3. В колонке «Current value» укажите свои данные и нажмите «Save»:
      • domain — адрес вашего хранилища.
      • username — имя пользователя хранилища.
      • password — пароль пользователя хранилища.
   4. В правом верхнем углу выберите «storage».

Авторизация:

1. В левой панели выберите «Collections».
2. В списке коллекций разверните «storage» и выберите метод «authorization».
3. Нажмите «Send» — метод вернёт токен и Postman автоматически подставит токен в окружение.

Далее можно выбирать любые методы, подставлять на вкладке «Body» свои данные и проверять их работу.

В правой панели кнопкой «</>» можно сгенерировать готовые примеры кода вызова метода на PHP, Python и других языках, команд cURL, wget, и др.