Различия
Здесь показаны различия между двумя версиями данной страницы.
comet:cometql [2018/02/24 12:01] anastation468 [Описание таблиц] |
comet:cometql [2019/12/18 01:58] |
||
---|---|---|---|
Строка 1: | Строка 1: | ||
- | <rst>RU::002-API::002-CometQL</rst> | ||
- | <rst>Header: CometQL API</rst> | ||
- | ====== CometQL ====== | ||
- | |||
- | **CometQL** - это api для работы с комет сервером по протоколу MySQL. | ||
- | |||
- | Преимущества CometQL | ||
- | |||
- | - Единый api для более чем 12 языков программирования | ||
- | - Простой и понятный вид запросов | ||
- | - В php есть средства поддержания постоянных соединений с MySQL и теперь их можно также использовать для работы с comet сервером. | ||
- | |||
- | В данном представлении данные лежат в таблицах а команды на выборку или вставку совершают какие-то действия. | ||
- | Например, для получения информации о том, когда пользователь был online достаточно выполнить следующий запрос: | ||
- | <code sql>select * from users_time where id = 2;</code> | ||
- | Вот что мы увидим | ||
- | <code sql> | ||
- | 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) | ||
- | </code> | ||
- | Здесь пользователь с id = 2 в данный момент на сайте, пользователь с id = 3 был online 30 июля, а для пользователя с id = 145 нет данных. | ||
- | ===== Как подключится и попробовать самостоятельно ===== | ||
- | Вы можете сами подключится с демо данными и попробовать. Но подключатся рекомендуется через консоль, так как не все графические MySQL клиенты нормально работают с comet сервером. | ||
- | <code bash> | ||
- | # Сервер app.comet-server.ru | ||
- | # Логин 15 | ||
- | # Пароль lPXBFPqNg3f661JcegBY0N0dPXqUBdHXqj2cHf04PZgLHxT6z55e20ozojvMRvB8 | ||
- | # База данных CometQL_v1 | ||
- | |||
- | # Строка для подключения из консоли | ||
- | mysql -h app.comet-server.ru -u15 -plPXBFPqNg3f661JcegBY0N0dPXqUBdHXqj2cHf04PZgLHxT6z55e20ozojvMRvB8 -DCometQL_v1 --skip-ssl | ||
- | </code> | ||
- | |||
- | Или ещё можете использовать [[comet:cometql:cli|онлайн командную строку]]. Она расположена в правом нижнем углу экрана на всех старицах. | ||
- | |||
- | <note tip>Есть [[comet:cometql:cli|пример исходных кодов на PHP с использованием CometQL]] для реализации онлайн командной строки</note> | ||
- | |||
- | <note important>Есть случаи когда нет возможности использовать протокол MySQL для соединения с комет сервером. Для таких случаев можно отправлять команды комет серверу по HTTP/HTTPS. Смотрите статью [[comet:cometql:HTTP|отправка CometQL запросов по HTTP]]</note> | ||
- | |||
- | Пример подключения к комет серверу из php. | ||
- | <code php> | ||
- | $dev_id = "15"; // Используется как логин | ||
- | $dev_key = "lPXBFPqNg3f661JcegBY0N0dPXqUBdHXqj2cHf04PZgLHxT6z55e20ozojvMRvB8"; // Используется как пароль | ||
- | |||
- | // Подключение выглядит как будто мы подключились к бд. Можно использовать функции для работы с mysql | ||
- | // Но на самом деле вы подключаетесь к комет серверу. | ||
- | $link = mysqli_connect("app.comet-server.ru", $dev_id, $dev_key, "CometQL_v1"); | ||
- | if(!$link) | ||
- | { | ||
- | die("Не удалось создать соединение c CometQL"); | ||
- | } | ||
- | |||
- | $result = mysqli_query ( $link, "show status" ); | ||
- | if(mysqli_errno($link) != 0) | ||
- | { | ||
- | echo "Error code:<a href='https://comet-server.com/wiki/doku.php/comet:cometql:error' target='_blank' >".mysqli_errno($link)."</a>"; | ||
- | echo "Error text:<a href='https://comet-server.com/wiki/doku.php/comet:cometql:error' target='_blank' >".mysqli_error($link)."</a>"; | ||
- | exit; | ||
- | } | ||
- | |||
- | while($row = mysqli_fetch_assoc($result)) | ||
- | { | ||
- | echo "<pre>"; | ||
- | var_dump($row); | ||
- | echo "</pre><br>"; | ||
- | } | ||
- | |||
- | </code> | ||
- | ====== Описание таблиц ====== | ||
- | |||
- | <note important>Имена таблиц и колонок регистрозависимы и всегда пишутся в нижнем регистре.</note> | ||
- | |||
- | Замечания по реализации текущей версии CometQL: | ||
- | * В CometQL реализовано не всё, что доступно в sql. Часть функционала планируется реализовать позже. Но некоторые ограничения наложены специально в целях оптимизации внутренней структуры Comet сервера. | ||
- | * В целях [[comet:cometql:optimization_for_the_cluster|оптимизации внутренней логики]] операции delete и insert не возвращают количество затронутых строк, по крайней мере так будет в CometQL версии 1.0 | ||
- | * Поддержка в запросах операторов OR, AND и ORDER BY будет реализована позже. | ||
- | |||
- | <note warning>У некоторых хостинг провайдеров установлен запрет на внешние соединения, это достаточно часто встречается на бесплатных или очень очень дешёвых хостингах. Для того, чтобы проверить возможность использования CometQL воспользуйтесь [[comet:testhosting|скриптом проверки хостинга]]. </note> | ||
- | ===== Таблица pipes_messages ===== | ||
- | |||
- | Таблица pipes_messages содержит сообщения передаваемые через каналы. Для отправки сообщения в канал надо выполнить запрос вставки ( insert ) в эту таблицу. | ||
- | <code sql> | ||
- | mysql> insert into pipes_messages (name, event, message)values("pipe_name", "event_in_pipe", "text message"); | ||
- | Query OK, 0 rows affected (0.13 sec) | ||
- | </code> | ||
- | |||
- | Поля "name" и "event" должны соответствовать следующему <abbr>Цифры от 0 до 9 буквы английского алфавита и знаки = + / _ и длиной от 3 до 64 символов(регулярному выражению ^[0-9A-z=+/_]{3,64}$)</abbr> | ||
- | |||
- | <note tip>Узнать количество людей в канале можно сделав запрос к таблице "pipes" так как сообщение отправляется всем кто подписался на канал то таким образом можно узнать число людей которые получили это сообщение.</note> | ||
- | |||
- | Запрос выборки из pipes_messages вернёт историю сообщений в канале если функция сохранения истории включена для этого канала. | ||
- | <code sql> | ||
- | 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) | ||
- | </code> | ||
- | |||
- | Очищает историю сообщений в канале. | ||
- | <code sql> | ||
- | mysql> delete from pipes_messages where name = 'p10'; | ||
- | Query OK, 0 rows affected (0.13 sec) | ||
- | </code> | ||
- | |||
- | === Online пример === | ||
- | Введите имя канала "pipe_name" и нажмите подписаться. | ||
- | <html> | ||
- | <iframe src="//comet-server.com/doc/example/7/subscriptionTest.php" width="910px"></iframe> | ||
- | </html> | ||
- | А теперь с помощью online командной строки расположенной в углу экрана выполните запрос вставки в pipes_messages и увидите что сообщение дошло. | ||
- | <code sql> | ||
- | mysql> insert into pipes_messages (name, event, message)values("pipe_name", "event_in_pipe", "text message"); | ||
- | </code> | ||
- | ===== Таблица pipes ===== | ||
- | Таблица pipes содержит информацию о том сколько человек подписались на сообщения из каналов. Таблица доступна только для чтения. | ||
- | <code sql> | ||
- | mysql> select * from pipes where name in( "web_admins", "web_php_chat"); | ||
- | +--------------+-------+ | ||
- | | name | users | | ||
- | +--------------+-------+ | ||
- | | web_admins | 0 | | ||
- | | web_php_chat | 0 | | ||
- | +--------------+-------+ | ||
- | 2 rows in set (0.30 sec) | ||
- | </code> | ||
- | |||
- | === Online пример === | ||
- | |||
- | Выполните запрос | ||
- | <code sql> | ||
- | mysql> select * from pipes where name in( "web_admins", "web_php_chat"); | ||
- | </code> | ||
- | Теперь введите имя канала "web_admins" и нажмите подписаться. | ||
- | <html> | ||
- | <iframe src="//comet-server.com/doc/example/7/subscriptionTest.php" width="910px"></iframe> | ||
- | </html> | ||
- | А теперь выполните запрос ещё раз и увидите что подписчиков в канале стало больше. | ||
- | ===== Таблица users_in_pipes ===== | ||
- | Таблица users_in_pipes содержит данные о том кто из пользователей подписался на канал. Таблица доступна только для чтения. | ||
- | <code sql> | ||
- | mysql> select * from users_in_pipes where name = "web_admins"; | ||
- | +------------+---------+-----------+-----------------+-------------------------------------+ | ||
- | | name | user_id | ip | origin | language | | ||
- | +------------+---------+-----------+-----------------+-------------------------------------+ | ||
- | | web_admins | 0 | 127.0.0.1 | https://site.ru | ru-RU,ru;q=0.8,en-US;q=0.6,en;q=0.4 | | ||
- | | web_admins | 364 | 127.0.0.1 | https://site.ru | ru-RU,ru;q=0.8,en-US;q=0.6,en;q=0.4 | | ||
- | +------------+---------+-----------+-----------------+-------------------------------------+ | ||
- | 4 row in set (0.32 sec) | ||
- | </code> | ||
- | Таблица имеет следующие поля: name, user_id, user_uuid, ip, origin, user_agent, language. | ||
- | ===== Таблица pipes_settings ===== | ||
- | Таблица pipes_settings содержит настройки логирования каналов. По умолчанию сообщения проходящие через канал не запоминаются. Но если включить механизм логирования для канала то в комет сервере будет хранится n последних сообщений прошедших через этот канал. | ||
- | Для включения механизма логирования в канале надо выполнить следующий запрос. | ||
- | <code sql> | ||
- | mysql> insert into pipes_settings ("name", "length") values ('p10', 10); | ||
- | Query OK, 1 row affected (0.00 sec) | ||
- | </code> | ||
- | Здесь параметр length это то сколько последних сообщений будет запомнено. Принимает значения от 0 до 99. | ||
- | |||
- | Для того чтобы получить значения настроек канала нужно выполнить запрос выборки из pipes_settings. | ||
- | <code sql> | ||
- | mysql> select * from pipes_settings where name = 'p10'; | ||
- | +------+--------+ | ||
- | | name | length | | ||
- | +------+--------+ | ||
- | | p10 | 10 | | ||
- | +------+--------+ | ||
- | 1 row in set (0.00 sec) | ||
- | </code> | ||
- | |||
- | Для того чтобы отключить механизм логирования надо удалить из pipes_settings запись настроек. | ||
- | <code sql> | ||
- | mysql> delete from pipes_settings where name = 'p10'; | ||
- | Query OK, 0 rows affected (0.00 sec) | ||
- | </code> | ||
- | |||
- | ===== Таблица users_messages ===== | ||
- | Таблица users_messages предназначена для отправки сообщений [[comet:authentication|авторизованным пользователям]] по их идентификатору. | ||
- | <note tip>Отправка личных сообщений пользователям по их идентификаторам, а не в канал предоставляет более надёжную защиту передаваемых данных. А также повышает вероятность доставки сообщения пользователю.</note> | ||
- | Например для отправки сообщения пользователю с id = 2 и текстом сообщения 'message' надо выполнить следующий запрос | ||
- | <code sql> | ||
- | mysql> insert into users_messages (id, event, message)values (2, 'event', 'message'); | ||
- | Query OK, 0 row affected (0.00 sec) | ||
- | </code> | ||
- | Сообщение либо отправлено пользователю сразу либо помещено в очередь для отправки пользователю позже. | ||
- | |||
- | Для того чтобы получить все те сообщения которые ещё не доставлены пользователю и находятся в очереди надо выполнить запрос select | ||
- | <code sql> | ||
- | 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) | ||
- | </code> | ||
- | Здесь видно что отправки ожидает 2 сообщения. Они будут отправлены сразу как пользователь появится online. | ||
- | Таблица содержит 4 колонки. | ||
- | - id - Идентификатор пользователя | ||
- | - index - Номер сообщения в очереди | ||
- | - event - Имя события | ||
- | - message - Тело сообщения | ||
- | |||
- | Для очистки очереди используйте запрос удаления. | ||
- | <code sql> | ||
- | mysql> delete from users_messages where id = 2; | ||
- | Query OK, 0 rows affected (0.08 sec) | ||
- | </code> | ||
- | <note>После того как сообщение будет доставлено пользователю оно автоматически удалится из очереди сообщений.</note> | ||
- | |||
- | ===== Таблица users_time ===== | ||
- | Таблица users_time содержит данные о том когда были пользователи online. Таблица доступна только для чтения. Данные о времени хранятся в [[https://ru.wikipedia.org/wiki/UNIX-%D0%B2%D1%80%D0%B5%D0%BC%D1%8F|UNIX-time]] | ||
- | <code sql> | ||
- | 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) | ||
- | </code> | ||
- | Здесь пользователь с id = 2 в данный момент на сайте, пользователь с id = 3 был online 30 июля, а для пользователя с id = 145 нет данных. | ||
- | |||
- | <note>Есть пример использования данных из этой таблицы для того чтобы [[http://dimasudarkin.ru/%D0%BE%D0%BD%D0%BB%D0%B0%D0%B9%D0%BD-%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8C-%D0%B8%D0%BB%D0%B8-%D0%BD%D0%B5%D1%82-php/|определить, онлайн пользователь или нет]]</note> | ||
- | ===== Таблица users_auth ===== | ||
- | |||
- | Таблица <abbr>Таблица содержит данные для авторизации пользователей на комет сервере(users_auth)</abbr> содержит данные для [[comet:authentication|авторизации пользователей]] на комет сервере. | ||
- | |||
- | <code sql> | ||
- | 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) | ||
- | </code> | ||
- | Здесь для пользователя с id = 3 нет данных, а для пользователей 2 и 12 данные присутствуют. | ||
- | <note important>В поле hash можно передавать только строки длиной не более 32 символов и соответствующие <abbr>Цифры от 0 до 9 буквы английского алфавита и знаки = + / _ (регулярному выражению [0-9A-z=+/_])</abbr>.</note> | ||
- | Для удаления данных [[comet:authentication|авторизации пользователей]] используйте запрос delete | ||
- | <code sql> | ||
- | delete from users_auth where id = 12; | ||
- | Query OK, 0 rows affected (0.00 sec) | ||
- | </code> | ||
- | <note>В целях [[comet:cometql:optimization_for_the_cluster|оптимизации внутренней логики операции]] delete и insert не возвращают количество затронутых строк, по крайней мере так будет в QometQL версии 1.0</note> | ||
- | |||
- | ===== Дополнительная информация ===== | ||
- | |||
- | * [[comet:cometql:cli|Пример использования CometQL на php]] | ||
- | * [[comet:cometql-bash-example|Пример отправки сообщения из bash]] | ||
- | * [[comet:cometql:error|Коды ошибок CometQL]] | ||
- | * [[comet:javascript_api:pipe-types|Зарезервированные имена каналов]] | ||
- | * [[comet:javascript_api|JavaScript API]] | ||
- | * [[comet:testhosting|Почему скрипт работает на локальной машине и не работает на хостинге? ]] | ||
- | * [[comet:dev_id|Что такое и зачем нужен "Публичный идентификатор разработчика" и "Секретный ключ разработчика"?]] | ||
- | * [[comet:faq:send-message-to-pipe|Как отправить сообщение в произвольный канал и как его потом получить на другой странице?]] | ||
- | * [[comet:faq:realtime-users-list|Как реализовать механизм отслеживания вхождения пользователей на сайт. То есть список посетителей обновляющийся на "лету"?]] | ||
- | * [[comet:saas|Могут ли влиять одни пользователи сервиса на других пользователей?]] * | ||
- | * [[comet:faq:access-to-channels-for-outsiders|Может ли кто то посторонний получать сообщение из каналов]] | ||
- | |||
- | ====== Зарезервированные имена каналов ====== | ||
- | |||
- | Основная статья [[comet:javascript_api:pipe-types|зарезервированные имена каналов]] | ||
- | <note warning>Не рекомендуется использовать в своих проектах имена каналов вида "bin_*", "big_*", "push_*", "comet_*", "self_*", "trust_*" и "sys_*" эти имена возможно будут использованы для дальнейшего расширения функционала. И будут иметь какие ни будь не обычные свойства по сравнению с другими именами каналов.</note> | ||
- | |||
- | |||
- | Так же есть каналы с особыми свойствами, о всех них ниже по тексту. | ||
- | * msg - Для доставки личных сообщений в соответствии с данными авторизации | ||
- | * user_status_* - для автоматического уведомления JS api о статусе пользователей | ||
- | * web_* - Каналы в которые можно отправлять сообщения как из CometQL так и из JS api | ||
- | * track_* - для автоматического уведомления JS api о том что кто то подписался или отписался от этого канала | ||
- | |||
- | ====== Обёртки над CometQL api ====== | ||
- | |||
- | Если вы написали обёртку для работы с CometQL api для какого нибудь фреймворка то будет здорово если вы поделитесь своей наработкой с другими пользователями. Присылайте ссылки на репозиторий с вашей обёрткой на support@comet-server.com |