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 интерфейс:
Ещё примеры использования CometQL в реальных проектах
Примеры использования CometQL есть в статье как сделать чат на сайте и в статье про интеграцию приватного чат на сайт
