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 тощо.