En Ru

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

Ссылка на файл

Загруженный файл доступен по ссылке определённого формата:
http(s)://[domain]/cdn/files/{file_id}/{filename}.{extension}

Описание формата ссылки. 1. HTTP схема Вы можете использовать протокол по своему усмотрению: http или https
2. domain Домен по умолчанию cdn.tinycdn.cloud. Вы можете использовать CNAME запись для использования своего домена. Чтобы это сделать, необходимо:

3. 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
Группе можно назначать правила обработки.

Хранение модификаций файлов

Определение подходящей модификации

Первоначальная модификация (при загрузке файла)

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

Пример json кода для описания правилила, что загруженные файлы должны быть ограничены по размеру и переконвертированы в webp

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

WaterMark в модификациях файлов

Пример json кода для описания вортемарка

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

1. Ключ id - id файла на cdn с вотермарком. Должен быть типа image
2. Ключ position определяет смещение наложения вотермарка
3. Ключ orientation определяет откуда ведётся отсчёт. Может принимать следующие значения

Ключ 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
        }
    }
}

API

CDN имеет GraphQL API. Каждый клиент может его использовать для автоматизации своей работы или по иным причинам.

Мы подготовили документацию и composer пакет.

Ошибки при просмотре файлов

Ошибки отдаются через коды состояния HTTP