Подключение внешней базы данных по API с помощью коннектора

На 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=... с названием таблицы, к которой нужно подключиться.

🔥
Кейс подключения MySQL к Creatium от пользователя:

Возможные проблемы

В редакторе все работает корректно, а в публикации возвращает 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);
	}
}

 

 

ТЕХНИЧЕСКАЯ ПОДДЕРЖКА

Не можете найти то, что ищете?

Напишите нам. на связи 24/7. Среднее время ожидания ответа: 10-15 минут. Также вы можете вступить в наш Телеграм-чат, где собралось много специалистов и пользователей.

Поддержка Creatium

Агенты ответят через 10 минут

Агенты ответят

Блог, курсы и полезные материалы 

Платформа сайтов любой сложности