Различия

Здесь показаны различия между двумя версиями данной страницы.

--- info_api [2021/10/21 08:15]
phaust [Информационный Telegram бот]
+++ info_api [2026/09/20 07:03] (текущий)
@@ Строка 1: / Строка 1: @@
 {{indexmenu_n>40}}
-===== Информационная API домена =====
+===== Информационная API=====
-У доменов есть информационная API, с помощью которой можно полоучить инофрмацию обо всех активных и предстоящих играх на домене в формате JSON. Это полезно для разработки сторонних сервисов, дублирующих информацию о домене в другие места (Telegram, сайты и т.п.)
+У доменов есть информационная API, с помощью которой можно полоучить инофрмацию обо всех активных и предстоящих играх на домене в формате JSON. Это полезно для разработки сторонних сервисов, дублирующих информацию о домене в другие места (Telegram, сайты и т.п.), и для собственных [[admin_main:domain_pages|страниц домена]], которые рисуют свою афишу.
 ==== Точка входа ====
 **api_games_list.php**
-**В запрос надо добавлять GET параметр json=1. Тогда результат будет приходить в формате JSON.**
+Пример запроса:
+[[https://game.qeng.org/api_games_list.php?v=2]]
-Пример запроса:
+==== Версия ====
-[[https://game.qeng.org/api_games_list.php?json=1]]
+Набор полей в ответе задаёт GET-параметр **v**.
+  * **Без ''v''** — версия 1: ответ, который API отдавала всегда, вместе со списками команд (''teams'') и авторов (''authors''). Старые запросы с ''json=1'' — это она; менять её мы не будем, и параметр ''fields'' в ней не читается.
+  * **''v=2''** — всё, кроме ''teams'' и ''authors''. Эти два списка собираются отдельными запросами к базе на каждую игру, а нужны далеко не всем: если они вам не нужны, ответ так получается заметно дешевле и быстрее.
+Незнакомый номер версии считается последним известным, а не ошибкой.
+==== Выбор полей ====
+GET-параметр **fields** перечисляет через запятую, какие именно поля нужны. Работает начиная с ''v=2''.
+  * Список задаёт набор **целиком**, а не добавку к набору версии.
+  * Поле ''id'' есть в ответе всегда, просить его не нужно.
+  * Порядок в запросе не важен — поля в ответе идут в своём обычном порядке.
+  * Незнакомые имена просто пропускаются, ошибкой это не считается.
+Пример: афише домена хватает названия, времени и рейтинга.
+[[https://game.qeng.org/api_games_list.php?v=2&fields=name,start_time_f,end_time_f,rating,me]]
 ==== Формат результата ====
@@ Строка 18: / Строка 35: @@
 <code JavaScript>
 {
-        "id": "3287",
+        "id": 3287,
         /* ID игры */
         "start_time": "2022-07-25 15:00:00",
@@ Строка 24: / Строка 41: @@
         "end_time": "2022-07-27 15:00:00",
         /* Время окончания игры в читабельном формате */
-        "start_time_f": "1658750400",
+        "start_time_f": 1658750400,
         /* Время начала игры в формате unixtime*/
-        "end_time_f": "1658923200",
+        "end_time_f": 1658923200,
         /* Время окончания игры в формате unixtime */
         "name": "QD10:  Операция болт или другие приключения гаечки",
         /* Название игры. Спецсимволы в формате HTML entity, например &quot; */
-        "type": "1",
+        "type": 1,
-        /* Победитель определяется:
-        "0": Баллы
-        "1": Время
-        */
-        "kind": "1",
         /* Тип игры:
-        "0": other
+: Штурм
-        "1": green
+: Линейка
-        "2": yellow
+: Таймер
-        "3": red
+        */
-        "4": virtual
+        "kind": 1,
+        /* Вид игры:
+: other
+: green
+: yellow
+: red
+: virtual
         */
-        "single": "0",
+        "single": false,
         /* Одиночная или командная:
-        "0": Командная
+        false: Командная
-        "1": Одиночная
+        true: Одиночная
         */
         "description": "PS: следите за обновлениями.&lt;\/strong&gt;&lt;\/p&gt;\r\n",
          /* Описание игры*/
         "authors": [
-            /* Список авторов */
+            /* Список авторов. Только по запросу: fields=authors */
             {
                 "uid": "2130",
@@ Строка 60: / Строка 78: @@
         ],
         "teams": [
-            /* Список команд, подавших заявки на игру. Для одиночных игр - список игроков, подавших заявки*/
+            /* Список команд, подавших заявки на игру. Для одиночных игр - список игроков, подавших заявки.
+               Только по запросу: fields=teams */
             {
                 "id": "201",
@@ Строка 78: / Строка 97: @@
                 "status": "0"
             },
-        ]
+        ],
+        "rating": {
+            /* Оценка игры игроками - то же число, что на странице отзывов.
+               null, если игру ещё никто не оценил. Только по запросу: fields=rating */
+            "average": 4.5,
+            /* Средняя оценка в звёздах, от 0.5 до 5 */
+            "n": 12,
+            /* Сколько игроков оценило */
+            "n_reviews": 3
+            /* Сколько из них написало отзыв */
+        },
+        "me": {
+            /* Как дела в этой игре у того, кто спрашивает.
+               null, если он не вошёл на сайт или в этой игре не участвует.
+               Только по запросу: fields=me */
+            "team_id": 201,
+            /* Последняя активная команда: та, за которую он в этой игре играл
+               последний раз. В одиночной игре это сам игрок, и тут его ID */
+            "team_name": "911 Team",
+            /* Её название, а в одиночной игре - имя самого игрока */
+            "score": 340,
+            /* Баллы этой команды - та же сумма, что игрок видит у себя в игре:
+               с бонусами и штрафами. Может быть отрицательной */
+            "status": "playing"
+            /* Как далеко она в игре зашла:
+            "playing": есть задание в работе
+            "finished": в игре была, заданий в работе не осталось
+            "not_started": заявка есть, игру ещё не начинала
+            */
+        }
     }
 </code>
+Поле ''me'' считается для того, кто прислал запрос, поэтому со страницы домена его надо запрашивать обычным ''fetch()'' с того же домена — тогда браузер сам приложит к запросу куки, и движок узнает игрока. Ответ с этим полем кэшировать нельзя, и заголовки об этом движок ставит сам.
+Состояния ''"finished"'' по времени тут не бывает: список отдаёт только игры, которые ещё не кончились.
 ===== Информационный Telegram бот =====
 Получить информацию об изменениях на сайте также можно с помощью [[info_api:tg_bot|Информационного Telegram бота]]