Опис роботи та документація

Посилання на файл

Завантажений файл доступний за посиланням певного формату:
https://tinycdn.cloud /cdn/files/{file_id}/{filename}.{extension}

file_id Це цілочисельний ID завантаженого файлу 4. filename Відображувана назва файлу, може бути будь-якою для ЧПУ 5. extension Відображуване розширення файлу, може бути будь-яким для ЧПУ
Заголовок Content-Type передається на основі розширення файлу під час його завантаження

Параметри у посиланні на файл

Посилання на файл можна, а іноді й потрібно, доповнювати query-параметрами (передаються після ? у посиланні)

Доступні query-параметри
1. token Цей параметр передає токен доступу до файлу, якщо файл доступний за токеном.
Необхідність його використання визначається під час завантаження файлу. Він може бути завантажений із прапором приватний — тоді без правильного токена сервер поверне помилку 403 (Forbidden).
Також приватність файлу може бути перевизначена для його модифікації — докладніше в розділі про правила обробки контенту.
2. format тільки для зображень Примусово конвертує формат зображення. Допустимі значення: png, gif, jpeg, webp, avif
3. download Передає браузеру заголовок Content-Disposition: attachment, що змушує браузер завантажувати файл, навіть якщо він може відображати цей тип контенту
4. width & height тільки для зображень Параметри задають необхідну ширину та висоту зображення відповідно.
Якщо вказати width і height — буде виконано ресайз до зазначених розмірів. Якщо вказати лише один параметр — другий буде розрахований зі збереженням пропорцій.
5. quality тільки для зображень Бажаний рівень якості під час стиснення, 0 — мінімальна, 100 — максимальна. Впливає на розмір файлу

Правила обробки контенту (модифікації файлів) тільки для зображень

Під час завантаження файлу йому призначається група. Для завантаження через віджет за замовчуванням це public_upload
Для групи можна призначати правила обробки.

Зберігання модифікацій файлів

• Зберігаються модифікації, для яких знайдено точний збіг за всіма параметрами: наразі це width і height, а параметр format не впливає на пошук правила для модифікації
• Наприклад, можна створити правило з ключем product_image і параметрами width: 100, height: 100. І ще одне правило з ключем product_image і параметрами width: 200, height: 200.
• Під час завантаження файлу через API йому можна призначити набір правил через аргумент rule_key. Наприклад: rule_key: product_image
• Тоді при запиті файлу 100x100 і 200x200 ці файли будуть збережені у файловій системі, що підвищить швидкість обробки наступних запитів цього ж файлу
• А при запиті довільного розміру зображення буде змінено на основі оригінального файлу і НЕ буде збережено у файловій системі
• Модифікації можуть змінювати метод доступу до файлу. Наприклад, оригінал доступний лише за токеном, а 100x100 доступний для всіх
• Зберігаються модифікації тільки для строгих правил. Для часткових правил результуючі зображення у файловій системі не зберігаються.

Визначення відповідної модифікації

• Перемагає перше правило, яке підходить під усі зазначені умови, а не те, яке підходить найкраще
• Порядок обробки правил (підходить / не підходить) задається вручну під час створення правил
• Спочатку обробляються всі правила, які потребують строгого відповідності
• Потім обробляються всі правила, яким достатньо часткового відповідності
• Можна створити правило з частковою відповідністю, у якому не буде додаткових умов — під нього потраплять усі запити (якщо це потрібно)
• для правил повної відповідності можна перевіряти відповідність width і height (можна вказати лише один ключ)
• для правил часткової відповідності можна перевіряти min_width, max_width, min_height і max_height (усі ключі необов’язкові)

Початкова модифікація (під час завантаження файлу)

Правильне налаштування початкових модифікацій допоможе оптимізувати розмір займаного місця на диску та зробити подальшу роботу з файлами зручнішою. Правила такої модифікації обгорнуті в ключ first. Якщо буде знайдено відповідне правило, під час завантаження зображення воно буде змінене.
Підтримуються такі налаштування:

• first.width: ширина зображення
• first.height: висота зображення
• first.max_width: максимальна ширина зображення
• first.max_height: максимальна висота зображення
• first.format: формат зображення

Приклад JSON-коду для опису правила, що завантажені файли повинні бути обмежені за розміром і переконвертовані у webp

{
    "first": {
        "max_width": 2000,
        "max_height": 2000,
        "format": "webp"
    }
}

Watermark у модифікаціях файлів

• якщо у правилах вказані налаштування водяного знака, він обов’язково накладається
• сам файл водяного знака повинен бути попередньо завантажений на CDN з типом файлу "image"

Приклад JSON-коду для опису водяного знака

"watermark": {
    "id": 10,
    "position": {
        "orientation": "right/bottom",
        "x": 10,
        "y": "20%"
    }
}

1. Ключ id — id файлу на CDN із водяним знаком. Повинен бути типу image
2. Ключ position визначає зміщення накладання водяного знака
3. Ключ orientation визначає, від якої точки ведеться відлік. Може приймати такі значення

• left/top
• left/center
• left/bottom
• center/top
• center/center
• center/bottom
• right/top
• right/center
• right/bottom

Ключ x — додаткове зміщення по горизонталі. При орієнтації left або center зміщення йде вліво. При орієнтації right зміщення йде вправо.
Ключ y — додаткове зміщення по вертикалі. При орієнтації top або center зміщення йде вниз. При орієнтації bottom зміщення йде вгору.
Значення ключів x і y можуть бути від’ємними. Вказується або число (пікселі), або рядок виду "5%" — у відсотках від розміру вихідного зображення. За замовчуванням 0. Приклади значень: 10, -20, "5%"

Приклади обробки position для зображення 200x200 і водяного знака 40x40

{
    // відступ справа = 10px, знизу = 20% = 40px
    "watermark": {
        "id": 10,
        "position": {
            "orientation": "right/bottom",
            "x": 10,
            "y": "20%"
        }
    }
}

{
    // відступ справа = 10px
    // відступ зверху = (200 - 40) / 2 = 80px
    "watermark": {
        "id": 10,
        "position": {
            "orientation": "right/center",
            "x": 10
        }
    }
}

{
    // відступ зліва = по центру і зміщення на -10px = ((200 - 40) / 2) -10 = 70px
    // відступ зверху = 0
    "watermark": {
        "id": 10,
        "position": {
            "orientation": "center/top",
            "x": -10
        }
    }
}

Помилки під час перегляду файлів

Помилки передаються через коди стану HTTP

• Перегляд захищеного файлу без правильного токена = 403 (Forbidden)
• Перегляд файлу за ID, який не знайдено = 404 (Not Found)