CometQL — api роботи з комет сервером за допомогою протоколу MySQL


CometQL — це api для роботи з saas комет серверисом по протоколу MySQL.

Чому це круто

  • Єдиний api для більш ніж 12 мов програмування
  • Простий і зрозумілий вид запитів
  • php є засоби підтримання постійних з'єднань з MySQL і тепер їх можна так само використовувати для роботи з comet сервером.
Наприклад для отримання інформації про те, коли користувач був online досить виконати наступний запит:
select id, time from users_time where id = 2;

А от запит для відправки повідомлення у канал:
INSERT INTO pipes_messages (name, event, message)VALUES("pipe_name", "event_in_pipe", "text message");

Як підключиться і спробувати самостійно

Ви можете самі підключиться з демо даними і спробувати.
# Сервер app.comet-server.ru
# Логін 15
# Пароль lPXBFPqNg3f661JcegBY0N0dPXqUBdHXqj2chf04pzglhxt6z55e20ozojvmrvb8
# База даних CometQL_v1

# Рядок для підключення консолі
mysql-h app.comet-server.ru -u15-plPXBFPqNg3f661JcegBY0N0dPXqUBdHxqj2chf04pzglhxt6z55e20ozojvmrvb8-DCometQL_v1


Для тих хто хоче спробувати підключиться але немає під рукою консольного mysql клієнтаВи можете випробувати роботу CometQL за допомогою online CometQL командного рядка (розташована у правому нижньому кутку на будь-якій сторінці)

Загальні відомості про CometQL

CometQL зовні представляє з себе якусь подобу бази даних. При чому коли ми при підключенні вибираємо базу даних CometQL_v1 це фактично інструкція вказує з якою версією api ми хочемо взаємодіяти.
Треба розуміти що не якогось MySQL сервера на бекэнде немає, запити парсятся та виконуються безпосередньо comet сервером. А представлення всіх можливих дій у вигляді таблиць і запитів до них просто зручно і звично для багатьох вебмастерів.

Таблиця pipes_messages

Таблиця pipes_messages містить повідомлення передаються через канали. Для відправки повідомлення у канал треба виконати запит вставки ( insert ) у цю таблицю.
mysql> insert into pipes_messages (name, event, message)values("pipe_name", "event_in_pipe", "text message");
Query OK, 0 rows affected (0.13 sec)

Поля «name» і «event» повинні відповідати наступним регулярному виразу[0-9A-z=+/_]
Запит вибірки з pipes_messages поверне історію повідомлень в каналі якщо функція збереження історії включена для цього каналу (про те як цю функцію включити написано нижче).
mysql> select * from pipes_messages where name = "p10";
+------+-------+-------+--------------+
| name | index | event | message |
+------+-------+-------+--------------+
| p10 | 0 | event | msgData |
| p10 | 1 | event | msgqqrrata |
| p10 | 2 | evt3 | msgqqrrata |
+------+-------+-------+--------------+
3 rows in set (0.00 sec)

Очищає історію повідомлень в каналі.
mysql> delete from pipes_messages where name = 'p10';
Query OK, 0 rows affected (0.13 sec)

Online приклад відправки повідомлень

Таблиця pipes

Таблиця pipes містить інформацію про те, скільки осіб підписалися на повідомлення з каналів. Таблиця доступна тільки для читання.
mysql> select * from pipes where name in( "web_admins", "web_php_chat");
+--------------+-------+
| name | users |
+--------------+-------+
| web_admins | 3 |
| web_php_chat | 2 |
+--------------+-------+
2 rows in set (0.30 sec)

Online приклад підписок на канали

Таблиця users_in_pipes

Таблиця users_in_pipes містить дані про те, хто з авторизованих користувачів підписався на канал. Таблиця доступна тільки для читання.
mysql> select * from users_in_pipes where name = "web_admins";
+------------+---------+
| name | user_id |
+------------+---------+
| web_admins | 2 |
| web_admins | 4 |
| web_admins | 14 |
| web_admins | 9 |
+------------+---------+
4 row in set (0.32 sec)

Примітно що поле users містить сумарна кількість передплатників як авторизованих так і не авторизованих в той час як таблиця users_in_pipes містить список лише для авторизованих передплатників.

Таблиця pipes_settings

Таблиця pipes_settings містить налаштування логування каналів. За замовчуванням повідомлення проходять через канал не запам'ятовуються. Але якщо включити механізм логування для каналу у комет сервері буде зберігається n останніх повідомлень пройшли через цей канал.
Для включення механізму логування в каналі треба виконати наступний запит.
mysql> insert into pipes_settings (name, length) values ('p10', 10);
Query OK, 1 row affected (0.00 sec)

Тут параметр length це те скільки останніх повідомлень запомнено. Приймає значення від 0 до 99.
Для того щоб отримати значення параметрів каналу потрібно виконати запит вибірки з pipes_settings.
mysql> select * from pipes_settings where name = 'p10';
+------+--------+
| name | length |
+------+--------+
| p10 | 10 |
+------+--------+
1 row in set (0.00 sec)

Для того щоб відключити механізм логування треба видалити з pipes_settings запис налаштувань.
mysql> delete from pipes_settings where name = 'p10';
Query OK, 0 rows affected (0.00 sec)

Механізм авторизації користувачів на комет сервері


Крім каналів де кожен хто знає ім'я каналу може підписатися на нього, є можливість авторизації користувачів на комет сервері і відправки особистих повідомлень користувачам по їх ідентифікаторів. Авторизація користувача відбувається в 2 етапи. Перший етап надсилання ідентифікатора користувача в вашій системі і випадкового хешу у комет сервер.

mysql> INSERT INTO users_auth (id, hash )VALUES (1, 'auth_hash1');

  • Тут рядок auth_hash1 — це текстовий ключ авторизації. Ви генеруєте на своєму сервері і відправляєте спочатку в комет за коштами insert запиту в таблицю users_auth, а потім передаєте у JavaScript для авторизації конкретного користувача на комет сервері.
  • id користувача на вашому сайті, будь-яке ціле позитивне число не більш ніж з 9 цифр.
На другому етапі ці відомості (ім'я користувача і хеш) треба передати в JavaScript Api
$(document).ready(function()
{
CometServer().start({dev_id:1, user_key:"auth_hash1", user_id:"Числовой_Идентификатор_пользователя" })
});

Тут dev_id це публічний ідентифікатор розробника.
І тепер користувач буде авторизований на комет сервері.

Доставка повідомлень для авторизованих користувачів


При відправці повідомлень авторизованим користувачам за їх ідентифікатору (insert запит в таблицю users_messages) повідомлення доставляються користувачеві на всі пристрої (До 16 пристроїв) на яких він пройшов авторизацію в даний момент. Це дуже зручно у тому випадку, якщо людина зайшла на ваш сайт і авторизувався на ньому більш ніж з одного пристрою (наприклад телефон і комп'ютер або просто в двох різних браузерах сидить одночасно).

Якщо людина в даний момент ofline повідомлення поміщається в чергу повідомлень і буде доставлено коли людина з'явиться online. В даний момент для кожного користувача максимальний розмір черги обмежений.

Основне призначення черги повідомлень доставка повідомлень після короткочасного переходу людини в ofline. Наприклад, у тих випадках коли людина оновлює сторінку сайту на якій було відкрито з'єднання він йде в ofline приблизно на 1 секунду.

Таблиця users_messages

Таблиця users_messages призначена для відправки повідомлень авторизованим користувачам за їх кодом.
Наприклад, для надсилання повідомлення користувача з id = 2 і текстом повідомлення 'message' треба виконати наступний запит
mysql> insert into users_messages (id, event, message)values (2, 'event', 'message');
Query OK, 0 row affected (0.00 sec)

Повідомлення або надіслано користувачеві відразу або поміщено в чергу для надсилання пізніше.
Для того щоб отримати всі ті повідомлення які ще не доставлені користувачеві і перебувають у черзі треба виконати запит select
mysql> select * from users_messages where id = 2;
+----+-------+-------+---------+
| id | index | event | message |
+----+-------+-------+---------+
| 2 | 0 | evnt1 | message |
| 2 | 1 | evnt2 | messag2 |
+----+-------+-------+---------+
2 rows in set (0.00 sec)

Тут видно що відправки очікує 2 повідомлення. Вони будуть відправлені відразу як користувач з'явиться online.
Таблиця містить колонки:
  • id — Ідентифікатор користувача
  • index — Номер повідомлення в черзі
  • event — Ім'я події
  • message — Тіло повідомлення
Для очищення черги використовувати запит на видалення.
mysql> delete from users_messages where id = 2;
Query OK, 0 rows affected (0.08 sec)

Після того як повідомлення буде доставлено користувачеві воно автоматично вийде з черги повідомлень.

Таблиця users_time

Таблиця users_time містить дані про те, коли були користувачі online. Таблиця доступна тільки для читання. Дані про час зберігаються в UNIX-time
mysql> select * from users_time where id in( 2, 3, 145);
+-----+------------+
| id | time |
+-----+------------+
| 2 | 0 |
| 3 | 1438245468 |
| 145 | -1 |
+-----+------------+
3 rows in set (0.31 sec)

Тут користувач з id = 2 у даний момент на сайті, користувач з id = 3 був online 30 липня, а для користувача з id = 145 немає даних.

Таблиця users_auth

Таблиця users_auth містить дані для авторизації користувачів на комет сервері.
mysql> insert into users_auth (id, hash )values (12, 'hash1');
Query OK, 1 row affected (0.13 sec)

mysql> select * from users_auth where id in(2, 3, 12);
+----+----------------------------+
| id | hash |
+----+----------------------------+
| 2 | bjl6knotdb2t1oov958mhuian7 |
| 12 | hash1 |
+----+----------------------------+
2 rows in set (0.32 sec)

Тут для користувача з id = 3 немає даних, а для користувачів 2 і 12 дані присутні.

Важливо зазначити, що в полі hash можна передавати тільки рядки довжиною не більше 32 символів і відповідні регулярному виразу[0-9A-z=+/_].
Для видалення даних авторизації користувачів використовуйте запит delete
delete from users_auth where id = 12;
Query OK, 0 rows affected (0.00 sec)

Поради тим хто робить своє публічне api


Ось, на мій погляд, 3 найбільш корисні статті для будь-якого хто збирається робити публічний api інтерфейс:

Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.