Создание XML файлов серверов

Содержание

Введение
Быстрый старт
Структура XML файла
Узел Server
Узел SupportedFormats
Узел Actions
Узел Result
Система переменных
Регулярные выражения
Полные примеры
Отладка и тестирование
Создание скриптов
FAQ

Введение

Image Uploader позволяет добавлять поддержку новых серверов через XML файлы конфигурации. Эта документация поможет вам создать собственные серверы для загрузки изображений и файлов.

Где размещать файлы

Портативная версия: Data\Servers\
Установленная версия: %appdata%\Image Uploader\Servers\

⚠️ Важно: Не редактируйте файл servers.xml напрямую - он перезаписывается при обновлениях.

Быстрый старт

Минимальный пример

Создайте файл myserver.xml с базовой структурой:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Servers>
    <Server Name="Мой Сервер">
        <Actions>
            <Action Type="upload" 
                    Url="https://api.example.com/upload" 
                    PostParams="file=%filename%"
                    RegExp='"url":"([^"]+)"'
                    AssignVars="ImageUrl:0"/>
        </Actions>
        <Result ImageUrlTemplate="$(ImageUrl)"/>
    </Server>
</Servers>

Пошаговое создание

Изучите API целевого сервера
Определите тип сервера (изображения/файлы/URL)
Создайте действия для загрузки
Настройте обработку ответов
Протестируйте с параметром Debug="1"

Структура XML файла

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Servers>
    <Server Name="название_сервера" [атрибуты]>
        <SupportedFormats>
            <!-- Поддерживаемые форматы файлов -->
        </SupportedFormats>
        <Actions>
            <!-- Действия для загрузки -->
        </Actions>
        <Result ImageUrlTemplate="..." ThumbUrlTemplate="..." DownloadUrlTemplate="..."/>
    </Server>
</Servers>

📝 Примечание: Файл должен быть сохранен в кодировке UTF-8.

Узел Server

Обязательные атрибуты

Name - отображаемое название сервера

Основные атрибуты

Атрибут	Значения	Описание
`Type`	`image`, `file`, `urlshortening`, `searchbyimage`	Тип сервера
`FileHost`	`0`, `1`	0 - хостинг картинок, 1 - файловый хостинг (устаревший, используйте Type)
`Types`	`file image urlshortening`	Список типов через пробел (версия ≥ 1.3.2)
`Authorize`	`0`, `1`, `2`	0 - без авторизации, 1 - поддерживает, 2 - обязательна
`MaxFileSize`	число в байтах	Максимальный размер файла (0 = без ограничений)
`Debug`	`0`, `1`	Включить отладочную информацию
`MinVersion`	`x.x.x` или `x.x.x.xxxx`	Минимальная версия программы (версия ≥ 1.3.1)

Атрибуты авторизации

Атрибут	Значения	Описание
`NeedPassword`	`0`, `1`	1 - нужен пароль, 0 - не нужен
`LoginLabel`	текст	Подпись поля логина ("E-mail", "Login", "Username")
`PasswordLabel`	текст	Подпись поля пароля ("Password", "API Key", "Token")
`RegistrationUrl`	URL	Ссылка на страницу регистрации
`WebsiteUrl`	URL	Адрес веб-сайта сервера (версия ≥ 1.4.1)

Технические атрибуты

Атрибут	Значения	Описание
`Plugin`	имя файла	Имя скрипта (.nut файл) без расширения. Скрипт должен быть расположен в каталоге Data\Scripts, и иметь расширение .nut. Если данный атрибут не пустой, весь узел <Actions> игнорируется, и всё взаимодействие с серверами перекладывается на скрипт. Однако, узел Actions всё равно должен быть задан.
`Engine`	`MegaNz` и др.	Встроенный движок загрузки (версия ≥ 1.3.2)
`UserAgent`	строка	Пользовательский User-Agent (версия ≥ 1.3.2.4432)
`MaxThreads`	число	Ограничение одновременных соединений (версия ≥ 1.3.2)
`SupportsFolders`	`0`, `1`	Поддержка альбомов скриптом загрузки
`DefaultForTypes`	`file image`	Типы серверов, для которых этот сервер по умолчанию (версия ≥ 1.3.3)
`UploadToTempServer`	`0`, `1`	Загружать на промежуточный сервер для поиска по изображению (версия ≥ 1.4.1)

Пример с атрибутами

<Server Name="Imgur" 
        Type="image" 
        Authorize="1" 
        MaxFileSize="10485760"
        RegistrationUrl="https://imgur.com/register"
        LoginLabel="Username"
        PasswordLabel="Password">

Узел SupportedFormats

Определяет поддерживаемые форматы файлов (версия ≥ 1.4.1).

<SupportedFormats>
    <FormatGroup MaxFileSize="10485760" Authorized="0">
        <Format MimeType="image/jpeg,image/jpg">*.jpg,*.jpeg</Format>
        <Format MimeType="image/png">*.png</Format>
        <Format MimeType="image/gif">*.gif</Format>
    </FormatGroup>
    <FormatGroup MaxFileSize="52428800" Authorized="1">
        <Format MimeType="video/*">*.mp4,*.avi,*.mov</Format>
    </FormatGroup>
</SupportedFormats>

В атрибуте MimeType перечисляются (через запятую) разрешенные MIME-типы файлов, которые могут содержать подстановочные символы - wildcards, а в тексте узла перечисляются расширения файлов (через запятую), которые также могут содержать подстановочные символы. Если в одном узле Format указан только MIME-тип(ы), или только расширение(-ия), то проверка файлов будет производиться только по одному признаку.

Атрибуты FormatGroup

MaxFileSize - максимальный размер файлов в группе (в байтах)
Authorized - доступно только авторизованным пользователям (0 или 1)

Пример с условиями

<SupportedFormats>
    <!-- Для всех пользователей -->
    <FormatGroup MaxFileSize="5242880">
        <Format MimeType="image/jpeg,image/jpg">*.jpg,*.jpeg</Format>
        <Format MimeType="image/png">*.png</Format>
        <Format MimeType="image/gif">*.gif</Format>
    </FormatGroup>
    
    <!-- Только для авторизованных -->
    <FormatGroup MaxFileSize="52428800" Authorized="1">
        <Format MimeType="video/mp4">*.mp4</Format>
        <Format MimeType="video/avi">*.avi</Format>
        <Format MimeType="application/*">*.zip,*.rar</Format>
    </FormatGroup>

</SupportedFormats>

Узел Actions

Содержит последовательность действий для загрузки файла.

Типы действий

Type	Описание	Использование
`get`	HTTP GET запрос	Получение токенов, страниц
`post`	HTTP POST запрос	Отправка данных
`login`	POST для авторизации	Вход в систему
`upload`	Multipart форма	Загрузка файлов
`put`	HTTP PUT / FTP	Прямая загрузка
`openurl`	Открыть URL	Переход на страницу в браузере по-умолчанию

Полный список атрибутов Action

Атрибут	Обязательность	Описание
`Url`	Обязательный	HTTP/HTTPS/FTP адрес, может содержать переменные
`Type`	Обязательный	Тип запроса (`get`, `post`, `login`, `upload`, `put`, `openurl`)
`PostParams`	Опциональный	Параметры POST через `;` (`param1=value1;param2=value2`)
`RegExp`	Опциональный	Регулярное выражение в формате PCRE
`AssignVars`	Опциональный	Присвоение переменных (`VarName:GroupNum;...`)
`OnlyOnce`	Опциональный	Выполнить только раз за сессию (`0` или `1`)
`Referer`	Опциональный	Заголовок Referer
`Description`	Опциональный	Описание действия для отображения
`CustomHeaders`	Опциональный	Дополнительные заголовки (`Header1:Value1;Header2:Value2`)

Примечания по атрибутам

PostParams:

Разделитель параметров: ;
Экранирование точки с запятой: \;
Специальное значение %filename% = содержимое файла
Поддерживает переменные: file=%filename%;token=$(token)

CustomHeaders (версия ≥ 1.3.2.4432):

Формат: Header1:Value1;Header2:Value2
Для удаления стандартного заголовка передайте пустое значение
Поддерживает переменные: Authorization:Bearer $(token)

RegExp:

Использует синтаксис PCRE
Подмаски нумеруются с 0
При неудаче генерирует предупреждение и повторяет запрос

Пример последовательности действий

<Actions>
    <!-- 1. Получение токена -->
    <Action Type="get" 
            Url="https://api.example.com/token"
            RegExp='"token":"([^"]+)"'
            AssignVars="token:0"
            OnlyOnce="1"
            Description="Получение токена авторизации"/>
    
    <!-- 2. Загрузка файла -->
    <Action Type="upload"
            Url="https://api.example.com/upload"
            PostParams="file=%filename%;token=$(token)"
            RegExp='"url":"([^"]+)","thumb":"([^"]+)"'
            AssignVars="ImageUrl:0;ThumbUrl:1"
            Description="Загрузка файла"/>
</Actions>

Вложенные узлы Action

RegExp узел

Дополнительные регулярные выражения для обработки ответа:

<Action ...>
    <RegExp Pattern='"delete_url":"([^"]+)"' AssignVars="DeleteUrl:0" Required="1"/>
    <RegExp Pattern='"edit_url":"([^"]+)"' AssignVars="EditUrl:0" Data="$(CustomData)"/>
</Action>

Атрибуты RegExp:

Pattern - регулярное выражение (аналог атрибута RegExp у Action)
AssignVars - присвоение переменных
Required - генерировать ошибку при неудаче (по умолчанию 0)
Data - текст для поиска, может содержать переменные (по умолчанию - ответ сервера)

Call узел (версия ≥ 1.4.0)

Используется для вызова встроенных функций:

<Action ...>
    <Call Function="json" Arg1="data.files[0].url" AssignVars="ImageUrl:0" Required="1"/>
    <Call Function="regexp" Arg1='"url":"([^"]+)"' AssignVars="ImageUrl:0"/>
</Action>

Атрибуты Call:

Function - название функции (json, regexp)
Arg0, Arg1, Arg2 - аргументы функции (Arg0 по умолчанию = тело ответа)
AssignVars - присвоение переменных (как в Action)
Required - генерировать ошибку при неудаче (по умолчанию 0)

Функция json:

Извлекает данные из JSON по JSON Path
Примеры путей: data.url, files[0].thumbnail, response.data[0].link

Функция regexp:

Применяет регулярное выражение к данным
Аналогично атрибуту RegExp в Action

Узел Result

Определяет шаблоны для генерации ссылок.

<Result ImageUrlTemplate="$(ImageUrl)" 
        ThumbUrlTemplate="$(ThumbUrl)" 
        DownloadUrlTemplate="$(ViewUrl)"
        DeleteUrl="$(DeleteUrl)"
        EditUrl="$(EditUrl)"/>

Атрибуты Result

Атрибут	Описание
`ImageUrlTemplate`	Прямая ссылка на файл
`ThumbUrlTemplate`	Ссылка на миниатюру
`DownloadUrlTemplate`	Ссылка на страницу просмотра
`DeleteUrl`	Ссылка для удаления
`EditUrl`	Ссылка для редактирования

⚠️ Важно: Обязательно должен быть указан ImageUrlTemplate или DownloadUrlTemplate. Программа использует тот или иной атрибут в зависимости от настроек, и в зависимости от того, какой из атрибутов задан, а какой нет. По-умолчанию предпочтение отдается прямой ссылке. В случае использования скрипта (плагина - атрибут Plugin узла Server), все атрибуты всё равно должны иметь непустые значения.

Система переменных

Название переменной может содержать алфавитно-цифровые символы (A-z, 0-9) и символ подчеркивания. Имена переменных чувствительны к регистру. Если название переменной начинается с символа подчеркивания, это означает, что данная переменная не будет удалена после загрузки файла, и она останется в памяти на всю сессию загрузки. Однако это не означает, что её значение не может быть перезаписано.

Встроенные переменные

Переменная	Описание	Пример
`_FILENAME`	Имя файла с расширением	`photo.jpg`
`_FILENAMEWITHOUTEXT`	Имя без расширения	`photo`
`_FILEEXT`	Расширение файла	`jpg`
`_FILESIZE`	Размер файла в байтах (версия ≥ 1.4.3)	`1048576`
`_THUMBWIDTH`	Ширина миниатюры	`150`
`_THUMBHEIGHT`	Высота миниатюры	`150`
`_THUMBCREATE`	Создавать миниатюру (версия ≥ 1.4.2)	`0` или `1`
`_THUMBADDTEXT`	Добавлять текст на миниатюру (версия ≥ 1.4.2)	`0` или `1`
`_THUMBUSESERVER`	Использовать серверные миниатюры (версия ≥ 1.4.2)	`0` или `1`
`_RAND16BITS`	Случайное число (генерируется один раз на файл)	`0-65535`
`_LOGIN`	Имя пользователя	`user123`
`_PASSWORD`	Пароль пользователя	`secretpass`
`_THREADID`	ID потока (версия ≥ 1.3.2)	`1`
`_ORIGINALURL`	Ссылка для сокращения (только для urlshortening)	`https://example.com`
`_IMAGEURL`	Прямая ссылка на изображение для поиска (версия ≥ 1.4.1)	`https://temp.host/img.jpg`

Использование переменных

<!-- Подстановка в URL -->
<Action Url="https://api.example.com/upload?user=$(_LOGIN)&amp;file=$(_FILENAME)"/>

<!-- Подстановка в параметры -->
<Action PostParams="filename=$(_FILENAME);size=$(_FILESIZE)"/>

<!-- В шаблонах результата -->
<Result ImageUrlTemplate="https://cdn.example.com/$(ImageId).$(_FILEEXT)"/>

Пользовательские переменные

<!-- Создание переменной -->
<Action RegExp='"id":(\d+)' AssignVars="ImageId:0"/>

<!-- Использование -->
<Action Url="https://api.example.com/info/$(ImageId)"/>

Глобальные переменные

Переменные, начинающиеся с _, сохраняются на всю сессию:

<Action RegExp='"session":"([^"]+)"' AssignVars="_session:0" OnlyOnce="1"/>

Фильтры переменных

Фильтр	Описание	Пример
`urlencode`	Процентное кодирование URL	$(_FILENAME\|urlencode)
`htmldecode`	Декодирование HTML сущностей (версия ≥ 1.3.2)	$(ImageUrl\|htmldecode)

<!-- URL кодирование -->
<Action Url="https://api.example.com/search?q=$(_FILENAME|urlencode)"/>

<!-- HTML декодирование -->
<Result ImageUrlTemplate="$(ImageUrl|htmldecode)"/>

Специальные значения

Значение	Описание
`%filename%`	Загружаемый файл (не путать с `_FILENAME`)
`\;`	Экранированная точка с запятой в PostParams

Регулярные выражения

Основы RegExp для извлечения данных

Простое извлечение

<!-- Извлечение ID из JSON -->
RegExp='"id":(\d+)'
AssignVars="ImageId:0"

<!-- Извлечение URL -->
RegExp='"url":"([^"]+)"'
AssignVars="ImageUrl:0"

Множественное извлечение

<!-- Извлечение нескольких значений -->
RegExp='"url":"([^"]+)","thumb":"([^"]+)","view":"([^"]+)"'
AssignVars="ImageUrl:0;ThumbUrl:1;ViewUrl:2"

Работа с HTML

<!-- Извлечение из HTML атрибутов -->
RegExp='src="([^"]+)"[^>]+class="image"'
AssignVars="ImageUrl:0"

<!-- Извлечение текста между тегами -->
RegExp='&lt;title&gt;([^&lt;]+)&lt;/title&gt;'
AssignVars="Title:0"

Частые паттерны

Задача	Паттерн	Описание
Число	`(\d+)`	Любое число
URL	`(https?://[^\s"']+)`	HTTP/HTTPS ссылка
Текст в кавычках	`"([^"]+)"`	Текст в двойных кавычках
Текст между тегами	`<tag>([^<]+)</tag>`	Содержимое тега
Опциональный текст	`([^"]*)"`	Может быть пустым

⚠️ Важно: Символы < и > в паттернах при вставке в XML должны быть экранированы: < и > соответственно.

Советы по RegExp

Тестируйте выражения на сайтах вроде regex101.com
Используйте неадаптивные группы (?:...) для группировки без захвата
Экранируйте специальные символы: \., \?, \+
Будьте аккуратны с жадными квантификаторами .*

Полные примеры

Пример 1: Простой хостинг изображений

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Servers>
    <Server Name="SimpleHost" Type="image">
        <Actions>
            <Action Type="upload"
                    Url="https://simplehost.com/api/upload"
                    PostParams="image=%filename%"
                    RegExp='"success":true,"data":{"url":"([^"]+)","delete_hash":"([^"]+)"}'
                    AssignVars="ImageUrl:0;DeleteHash:1"/>
        </Actions>
        <Result ImageUrlTemplate="$(ImageUrl)" 
                DeleteUrl="https://simplehost.com/delete/$(DeleteHash)"/>
    </Server>
</Servers>

Пример 2: Сервер с авторизацией

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Servers>
    <Server Name="AuthHost" Type="image" Authorize="1" 
            LoginLabel="Username" PasswordLabel="Password">
        <Actions>
            <!-- Авторизация -->
            <Action Type="login"
                    Url="https://authhost.com/api/login"
                    PostParams="username=$(_LOGIN);password=$(_PASSWORD)"
                    RegExp='"token":"([^"]+)"'
                    AssignVars="_token:0"
                    OnlyOnce="1"
                    Description="Авторизация"/>
            
            <!-- Загрузка -->
            <Action Type="upload"
                    Url="https://authhost.com/api/upload"
                    PostParams="file=%filename%;token=$(_token)"
                    CustomHeaders="Authorization:Bearer $(_token)"
                    RegExp='"url":"([^"]+)","thumb":"([^"]+)"'
                    AssignVars="ImageUrl:0;ThumbUrl:1"/>
        </Actions>
        <Result ImageUrlTemplate="$(ImageUrl)" ThumbUrlTemplate="$(ThumbUrl)"/>
    </Server>
</Servers>

Пример 3: Файловый хостинг

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Servers>
    <Server Name="FileHost" Type="file" FileHost="1" MaxFileSize="104857600">
        <SupportedFormats>
            <FormatGroup>
                <Format MimeType="*/*">*.*</Format>
            </FormatGroup>
        </SupportedFormats>
        <Actions>
            <Action Type="upload"
                    Url="https://filehost.com/upload"
                    PostParams="file=%filename%;public=1"
                    RegExp='"file_url":"([^"]+)","download_url":"([^"]+)"'
                    AssignVars="FileUrl:0;DownloadUrl:1"/>
        </Actions>
        <Result ImageUrlTemplate="$(FileUrl)" DownloadUrlTemplate="$(DownloadUrl)"/>
    </Server>
</Servers>

Пример 4: Сокращение URL

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Servers>
    <Server Name="ShortURL" Type="urlshortening">
        <Actions>
            <Action Type="post"
                    Url="https://short.ly/api/shorten"
                    PostParams="url=$(_ORIGINALURL)"
                    RegExp='"short_url":"([^"]+)"'
                    AssignVars="ShortUrl:0"/>
        </Actions>
        <Result DownloadUrlTemplate="$(ShortUrl)"/>
    </Server>
</Servers>

Отладка и тестирование

Включение отладки

<Server Name="TestServer" Debug="1">

При включенной отладке программа покажет:

Отправляемые запросы
Полученные ответы
Результаты RegExp
Значения переменных

Пошаговое тестирование

Создайте минимальный XML с одним действием
Включите Debug="1"
Загрузите тестовый файл
Изучите лог в окне программы
Исправьте ошибки и повторите

Частые проблемы

Проблема	Причина	Решение
"RegExp не найден"	Неверное регулярное выражение	Проверьте паттерн на тестовых данных
"Переменная пуста"	Неверный номер группы	Проверьте номера в AssignVars
"Файл не загружен"	Неверные параметры POST	Изучите документацию API
"Ошибка авторизации"	Неверный URL или параметры	Проверьте процесс авторизации

Инструменты для отладки

RegExr.com - тестирование регулярных выражений
Browser DevTools - анализ сетевого трафика в браузере
Fiddler Classic - анализ сетевого трафика с помощью прокси
Postman - тестирование API запросов

Создание скриптов (плагинов)

Для расширенной поддержки серверов в программе используются скрипты на языке Squirrel 3 (до версии 1.3.2 использовался Squirrel 2).

Они должны быть сохранены в кодировке utf-8 в файлах с расширением .nut.

Scripting API reference

Документация языка Squirrel
Документация стандартной библиотеки языка Squirrel (PDF)

FAQ

Общие вопросы

Q: Где найти документацию API сервера? A: Обычно на сайте сервера в разделе "API", "Developers" или "Documentation".

Q: Как узнать формат запроса? A: Используйте инструменты разработчика браузера для анализа запросов при загрузке через веб-интерфейс.

Q: Можно ли использовать один XML для нескольких серверов? A: Да, один файл может содержать несколько узлов <Server>.

Q: Поддерживается ли HTTPS? A: Да, Image Uploader поддерживает HTTPS полностью.

Технические вопросы

Q: Как передать файл в POST запросе? A: Используйте %filename% в параметре PostParams:

PostParams="file=%filename%;key=value"

Q: Как работать с cookies? A: Cookies автоматически сохраняются и передаются между запросами в рамках одной сессии.

Q: Можно ли изменить User-Agent? A: Да, используйте атрибут UserAgent в узле Server.

Q: Как передать дополнительные заголовки? A: Используйте атрибут CustomHeaders:

CustomHeaders="X-API-Key:mykey;Content-Type:application/json"

Регулярные выражения

Q: Как извлечь данные из JSON? A: Используйте узел <Call Function="json"> (версия ≥ 1.4.0) или RegExp:

<!-- Через Call -->
<Call Function="json" Arg1="data.url" AssignVars="ImageUrl:0"/>

<!-- Через RegExp -->
RegExp='"url":"([^"]+)"'

Q: Как работать с многострочными ответами? A: Используйте флаг [\s\S]*? для захвата переносов строк:

RegExp='&lt;script&gt;([\s\S]*?)&lt;/script&gt;'

Q: RegExp не находит совпадения A: Проверьте:

Правильность экранирования символов
Соответствие паттерна реальному ответу
Используйте инструменты тестирования регулярных выражений

Переменные

Q: Переменная не сохраняется между запросами A: Используйте префикс _ для глобальных переменных:

AssignVars="_token:0"

Q: Как использовать переменную в URL? A: Заключите в $():

Url="https://api.example.com/user/$(UserId)/upload"

Q: Можно ли использовать переменные в RegExp? A: Нет, RegExp не поддерживает переменные. Используйте фиксированные паттерны.

Заключение

Создание XML файлов для Image Uploader требует понимания API целевого сервера и базовых принципов HTTP. Следуйте этой документации, тестируйте каждый шаг и не бойтесь экспериментировать с отладкой.

Для получения дополнительной помощи:

Изучите существующие XML файлы в папке серверов
Используйте режим отладки для анализа запросов
Обращайтесь к документации API серверов

Удачи в создании поддержки новых серверов! 🚀