На Creatium есть механизм, позволяющий подключить любой внешний источник данных через прослойку-коннектор, который преобразует данные в формат, который мы понимаем.
Данные при этом нигде не кэшируются, и каждый раз при открытии страницы запрашиваются свежие.
Содержание
Как это работает
При создании таблицы нужно указать “Импорт таблицы по API”.
Скриншот
В настройках указать URL-ендпоинт коннектора, который все запросы будет обрабатывать, и при необходимости, HTTP-заголовки. Их можно не указывать, они не обязательные.
Ендпоинт должен работать только с одной таблицей. Если нужно подключить несколько таблиц, значит нужно создать несколько ендпоинтов с разными URL, и подключить их.
Формат запроса
Обращение к ендпоинту происходит методом POST. Формат запроса application/json.
Пример, в котором запрашивается просто первые 10 строк таблицы, без фильтров и сортировки:
{
"properties": {},
"sort": [],
"limit": 10,
"skip": 0
}Более сложный пример, с фильтрами и сортировкой, и запросом вторых 10 строк таблицы:
{
"properties": {
"name": "Евгений"
},
"sort": [
{
"column": "age",
"direction": "desc"
},
{
"column": "rating",
"direction": "asc"
}
],
"limit": 10,
"skip": 10
}Фильтры (properties)
properties - это ключ-значение, в котором как ключи так и значения всегда являются строками. Ключи и значения могут быть произвольными строками.
При подключении таблицы к шаблонной странице Creatium использует именно это поле, чтобы получить данные одной конкретной строки.
Сортировка (sort)
Объект, в котором в порядке важности перечислены поля, по которым нужно отсортировать, и направление сортировки (desc или asc).
Количество (limit)
Просто число. Если передается 0, значит количество не задано, и вывести нужно вообще все (для карты сайта, например).
Пропуск (skip)
Тоже просто число, которое используется для пагинации. Аналог OFFSET из MySQL.
Формат ответа
В ответе обязательно нужно прислать columns (список колонок), rows (найденные строки) и totalCount (общее количество найденных строк).
{
"columns": [
{
"id": "name",
"name": "Имя",
"type": "string"
},
{
"id": "email",
"name": "Почта",
"type": "string"
},
{
"id": "age",
"name": "Возраст",
"type": "number"
},
{
"id": "photo",
"name": "Фото",
"type": "string"
}
],
"rows": [
{
"name": "Иван Иванов",
"email": "ivan@example.com",
"age": 37,
"photo": "https://.../001_1.jpg"
},
{
"name": "Петр Петров",
"email": "petr@example.com",
"age": 22,
"photo": "https://.../001_2.jpg"
}
],
"totalCount": 122
}Типы данных
Сейчас поддерживается только 2 типа данных: string и number.
Пагинация
Если база данных не поддерживает ни в каком виде аналог totalCount, можно прибегнуть к следующему варианту. Если количество записей в результате равняется limit, тогда считаем, что totalCount равен offset + limit * 2, то есть делаем вид, будто есть еще одна страница, и тогда в пагинации будет доступен переход вперед. С первой страницы на вторую, со второй на третью, с третьей на четвертую, и тд, по одной странице за один раз.
Коды ошибок
Решение о том, какую ошибку выкидывать, и выкидывать ли ее вообще, остается на стороне API. То есть мы можем порекомендовать, что в случае сортировки по несуществующему полю, стоит бросать ошибку 422, но автор API может пренебречь этим. Тем не менее, мы должны быть готовы к следующим кодам ошибок:
400 - Bad Request
Неправильный запрос. Например, не удалось считать параметры.
401 - Unauthorized
Не удалось авторизоваться по указанным реквизитам, или реквизиты вообще не указаны.
403 - Forbidden
Нет доступа к этому ендпоинту. Например, реквизиты авторизации верны, но у пользователя недостаточно прав.
404 - Not Found
Ендпоинт не найден.
408 - Request Timeout
Таймаут. Например, из базы вернулся, и эта ошибка нам передается.
413 - Request Entity Too Large
Слишком большой запрос. Пока не представляю, что это может быть, но например в properties передана строка размером в 10 мб.
422 - Invalid Request
Ошибка в запросе, или его не получается выполнить. Примером могут быть неправильные properties, сортировка по несуществующему полю и т.д.
5** - Любые ошибки сервера
Значит неизвестно что случилось, просто тоже нужно не забывать про эти коды, которые часто возникают.
Пример коннектора 1: Таблица с курсом валют
Этот код можно “форкнуть” прямо в сервисе Napkin и подключить к своему сайту.
Это максимально простой пример. В нем мы берем JSON из https://www.cbr-xml-daily.ru/daily_json.js, применяем к нему properties, sort, limit, skip и возвращаем в нужном формате.
Наглядно демонстрирует, что ожидается от коннектора, как он должен преобразовывать данные.
Пример коннектора 2: Подключение MySQL
Этот коде тоже можно “форкнуть” прямо в сервисе Napkin и подключить к своему сайту.
Это более сложный пример, в котором все разнообразие типов поле MySQL приводится к двум поддерживаемым: string и number.
Параметры properties, sort, limit, skip преобразуются в SQL-запрос, а для того, чтобы посчитать totalCount используется связка SQL_CALC_FOUND_ROWS и FOUND_ROWS().
При подключении к Creatium нужно в ссылке указывать параметр ?table=... с названием таблицы, к которой нужно подключиться.
Возможные проблемы
В редакторе все работает корректно, а в публикации возвращает 404
Скорее всего вы не обрабатываете параметр properties. Именно в этом параметре указывается идентификатор записи, которую Creatium ожидает получить.
Если value пустое, то ничего не найдено
Решается добавлением кода в обработчик:
const whereParts = [];
for (const key in query.properties) {
const value = query.properties[key];
if (value !== undefined && value !== null && value !== '') {
whereParts.push(`${cleanEntityName(key)} = ?`);
placeholders.push(value);
}
}
