Доноры v210.1.0

Что такое донор

Донор — один источник данных: URL, по которому модуль загружает RSS, Atom, XML или JSON. После опроса сохраняется снимок схемы — пути полей с alias и типом; в шаблонах значения задаются Twig-выражениями ({{ alias }}, {{ area.name }}, циклы и условия).

Раздел админки: ?mod=parserkit&action=donors → карточка донора.

Поля карточки

Схемы запроса

У одного донора несколько схем запроса, каждая принадлежит только ему. Схема query (список) есть всегда и не удаляется. Схема single (одна запись) необязательна. Свои схемы автор называет сам: префикс из латиницы, цифр и _, начинается с буквы или _, не равен query или single, уникален у донора и не меняется после сохранения.

У каждой схемы: путь от основного адреса (пустой путь — запрос по самому адресу), метод, параметры, заголовки и тело. Источник фразы {search} — поле новости или ключ другой схемы этого же донора, один шаг цепочки (схема не ссылается на себя и не ссылается на схему, которая сама ждёт чужой ключ).

Опрос и сброс касаются только текущей схемы: пишут её пути, первичный ключ, образец и состояние. Сброс не запускает опрос заново. Кнопки «Опросить» и «Сбросить» неактивны, пока донор не сохранён.

Поля списка получают приставку query., поля карточки — single., у своих схем — свой префикс. Одинаковое имя живёт дважды: query.nameRu и single.nameRu.

Узел списка (list_node)

Ответ донора может быть:

• Лента — повторяющиеся элементы (item, entry, свой узел).
• Один объект — например artist в MusicBrainz: массива записей нет, но данные есть.

В форме выбор:

Когда выбрать «Корень»

• URL отдаёт один JSON/XML-объект без массива однотипных элементов.
• Нужна схема полей верхнего уровня и вложенных веток (область, даты и т.д.), а список для fill содержит ровно одну строку.

Когда указать узел вручную

• В ответе есть массив, но он не называется item / entry.
• Авто-режим выбрал не тот узел — выберите кандидата из списка или введите имя в поле «Вручную».

Два адреса — теперь две схемы

Раньше у донора было два адреса (список и карточка). Теперь это две схемы запроса: query (список) и single (одна запись). Общий адрес становится основным адресом донора, остатки — путями схем.

Адрес списка отдаёт много записей. Адрес карточки открывается для выбранной строки: вместо {key} теперь {search}, а источник фразы — ключ схемы списка. Пример: список https://example/films?keyword={search}, карточка https://example/films/{search}.

Опрос читает текущую схему. Поля списка получают приставку query., поля карточки — single.. Одинаковое имя живёт дважды: query.nameRu и single.nameRu.

После опроса у каждой схемы выбирают свой первичный ключ. Ключ живёт на схеме, не в шаблоне.

Наведение на путь в таблице показывает исходный путь первой записи, с .0 на месте списка. В выражение этот путь не входит. Старые шаблоны после такого опроса не переписываются: ссылки без query. и single. станут сломанными, их выбирают заново.

Параметры запроса и {search}

На карточке донора — таблица параметров запроса: пары «имя — значение» дописываются к URL при опросе и при заполнении на форме.

Список «Поле новости для {search}» — заголовок, ЧПУ, теги, описание, ключевые слова, краткое и полное описание, плюс дополнительные поля типа «одна строка». В режиме «Из поля новости» к ним добавляются все дополнительные поля любого типа.

Пример: адрес https://api.example/search, параметр q = {search}, фраза по умолчанию Beatles. Опрос уходит с ?q=Beatles. На форме новости {search} берётся из выбранного поля (по умолчанию — заголовок). Параметр «из поля» на опросе уходит пустым: формы новости в этот момент нет.

Авторизация

На карточке донора блок Авторизация задаёт, как модуль входит к API. Один и тот же способ используется при опросе схемы и при заполнении новости.

Секрет хранится у донора и в журнал не пишется.

Опрос схемы

1. Сохраните донор с корректным URL (и при необходимости параметрами).
2. Нажмите Опросить схему (или Перестроить схему / Сбросить схему).
3. При успехе таблица схемы заполнится путями; при ошибке опроса обычным способом старая схема не затирается пустым успехом. После сброса старая схема уже удалена — если опрос не удастся, она не вернётся.

Повторный опрос обновляет снимок; поля, исчезнувшие из ответа, помечаются «Нет» в колонке Актуально — связанные шаблоны могут получить сломанные ссылки (см. Шаблоны).

На карточке над таблицей есть свёрнутая подсказка: list в колонке «Тип» — несколько однотипных записей; group в колонке «Роль» — папка без своего значения (можно обрезать потомков).

Колонки таблицы схемы

Alias уникален только внутри одного донора — у другого донора то же имя year можно задать снова. Если на этой карточке имя уже занято (часто query.year и single.year), окно покажет путь владельца; кнопка «Забрать имя» снимет его с чужого поля. При опросе короткое имя в первую очередь достаётся полям карточки (single.*).

Alias и тип можно править на карточке; при следующем опросе сохранённые alias и типы для существующих путей не сбрасываются.

HTTP

User-Agent запросов к донору настраивается в Настройках модуля (по умолчанию DLE-ParserKit/210.1.0).

Пример: artist-подобный URL

1. URL с одним объектом artist → выберите Корень.
2. Опрос → в схеме появятся name, area.name, begin-area.name и др.
3. При необходимости отметьте группы «последний узел» — см. Вложенные поля.
4. Создайте шаблон на этом доноре.

Файл настроек

На карточке, справа от «К списку»: Выгрузить и Заменить. В списке доноров кнопка Из файла создаёт нового донора. В строке меню Действия: править, включить или отключить, удалить, выгрузить, заменить из файла.

В файл входят адреса, узел списка, параметры, схема и способ доступа. Ключ, пароль и секрет клиента в файл не пишутся. При замене уже сохранённый ключ остаётся. Если имя занято, новая запись получает добавку (2). Замена чужим именем отказывается.

Лишний путь в таблице схемы убирается крестиком у этого пути. Вложенные пути остаются. Запись в базу — при сохранении карточки. Описание поля стоит под коротким именем.

См. также

• Вложенные поля и flatten
• Шаблоны заполнения
• Заполнение на форме новости