Практика: разработчик
Восемь заданий с запросами к API: описание OpenAPI, запуск расчёта и ожидание задачи, результаты в GeoJSON, OGC API Features и Processes, подпись вебхука, MCP и API v2. Числа получены на учебном стенде — копии базы Алматы 09.11.2026 (http://127.0.0.1:8090, вход выключен), фрагмент 74 «Маг. сети для расчета НС», расчёт №68. На вашем стенде номера и часть чисел будут свои; на сервере со входом добавьте заголовок Authorization: Bearer <токен>.
Практика: разработчик
Кратко. Восемь заданий с запросами к API: описание OpenAPI, запуск расчёта и ожидание задачи, результаты в GeoJSON, OGC API Features и Processes, подпись вебхука, MCP и API v2. Числа получены на учебном стенде — копии базы Алматы 09.11.2026 (
http://127.0.0.1:8090, вход выключен), фрагмент 74 «Маг. сети для расчета НС», расчёт №68. На вашем стенде номера и часть чисел будут свои; на сервере со входом добавьте заголовокAuthorization: Bearer <токен>.
Задания
1. Что в OpenAPI
Скачайте /openapi.json и посчитайте версию спецификации, число адресов и операций, схем, адресов
/api/v1/…, /api/v2… и /api/ogc… (API v1 и OpenAPI,
урок 31).
Ответ
OpenAPI 3.1.0: 510 адресов, 573 операции, 178 схем. С префиксом /api/v1/ — 299 адресов, /api/v2 — 9,
/api/ogc — 11. Больше всего операций с тегами topology (52), analysis (30) и calculations (28). Многие
адреса продублированы прежними путями без /v1 (/api/calculations/…, /piezometer/…), поэтому адресов больше,
чем функций. Внешнему клиенту генерируйте код по
/api/v2/openapi.json, а не по общему описанию. Стенд, 09.11.2026.
2. Запуск расчёта и ожидание
Запустите плановый расчёт фрагмента 74 по температурному графику с потерями при −25 °C через
POST /api/v1/calculations/run и дождитесь конца через GET /api/v1/task/{task_id}
(Расчёт режима, раздел «Для разработчика»). Какое тело запроса, что
приходит в ответ и в итоге задачи?
Ответ
Тело: {"mode":"plan","fragment_ids":[74],"tn":-25,"tg":true,"teplopoter":true,"name":"…"} (схема
SetyRunRequest, fragment_ids — до 50). Ответ сразу: task_id, request_id и строка ключей движка
-Tn -25 -sopr 0 -roP 0.975 -roO 0.975 -iter 20 -tp_metod 0 -trtp 0 -tg -user_gid dev. Задача идёт стадиями
PROGRESS («Расчет подсети 1 из 1», «Запись результатов») и кончается SUCCESS с protocol_id 40 и HTML
протокола. Номер расчёта — из GET /api/v1/calculations?file_id=74: 68. Шёл 23 с; опрашивайте не чаще раза
в 5 с. Стенд, 09.11.2026; у вас будут свои номера.
3. Протокол как данные
Получите протокол GET /api/v1/calculations/protocols/{id} и найдите число ошибок и предупреждений по
категориям (Протокол расчёта).
Ответ
Протокол 40 (расчёт 68): errors: 2, warnings: 7, duration_s: 23.07. summary.by_category:
fixed_head — 1 ошибка (два узла заданного напора в подсети), rs — 1 ошибка (код источника в расчётных
схемах), regulator — 6 предупреждений, subnetwork — 1 (подсети без узла ЗН). У каждой записи entries
есть code и fix — по ним веб строит кнопки «Исправить». Стенд, 09.11.2026.
4. Результаты в GeoJSON
Получите GET /api/calculations/{id}/results/geojson и прочитайте summary. Найдите участок 325610
(мтк9-6 — МТК-9-9) и проверьте его скорость по формуле v = 353,86·G/d²
(Шпаргалка формул).
Ответ
Расчёт 68: lines_count 1686, nodes_count 1643, high_velocity_count 174, over_resistance_count 62.
Участок 325610: diameter_mm 796, flow 2767,89, velocity 1,55, velocity_status high, spec_loss_mm_m 2,93,
pressure_drop 1,492. 353,86·2767,89/796² = 1,546 — совпадает. Ответ около 1,8 МБ: для карты берите его,
для таблиц — отчёты Excel. Стенд, 09.11.2026.
5. OGC API Features
Посмотрите /api/ogc/conformance и /api/ogc/collections, затем выгрузите участки фрагмента 74:
/api/ogc/collections/pipes/items?fileid=74&limit=10000 (OGC API,
урок 32). Сколько классов соответствия, коллекций и участков? Как узнать общее число
объектов?
Ответ
Классов соответствия 9: Features core, geojson, oas30, запись (create-replace-delete, update,
optimistic-locking-etags) и Processes core, ogc-process-description, json. Коллекций 5: pipes, nodes,
consumers, heat_sources, valves. Участков фрагмента 74 — numberReturned: 3625. numberMatched сервер
не отдаёт: выбирайте с limit до 10 000 и идите по ссылке next, пока она есть. Участок 325610 в коллекции —
diameter_internal_mm 796, length_m 396,5, узлы 536000 и 536053. Стенд, 09.11.2026.
6. OGC API Processes
Получите /api/ogc/processes и выполните network-statistics с входами
{"query":"length","fragment_ids":[74]}. Сколько процессов и какой из них асинхронный?
Ответ
Процессов 9: восемь синхронных (network-trace, valve-isolation, network-select, network-statistics,
regime-analysis, thematic-summary, wear-priorities, data-quality) и один асинхронный — heat-hydraulic,
настоящий расчёт: 201 и Location на /jobs/{id}. Длина сети фрагмента 74: подача 197 263,2 м, обратка
197 576,4 м, всего 394 839,6 м. Стенд, 09.11.2026.
7. Подпись вебхука
Сколько типов событий отдаёт GET /api/v1/webhooks/event-types? Посчитайте подпись запроса: секрет подписки —
whsec_ и base64 от байтов строки practice-secret-0123456789abcdef, webhook-id = evt_test1,
webhook-timestamp = 1794200000, тело {"type":"outage.created","data":{"id":1}}
(Вебхуки).
Ответ
Типов событий 11: дефект, 2 наряда, 2 отключения, 3 телеметрии (sensor.*) и 3 баланса (balance.*).
Ключ HMAC — байты после декодирования base64 из секрета, то есть сама строка practice-secret-0123456789abcdef.
Подписываемое: evt_test1.1794200000.{"type":"outage.created","data":{"id":1}}; HMAC-SHA256 в base64 даёт
webhook-signature: v1,7roeO57ffuwOYxXh5w8IV6pcBCzmU4+f1caB6BmkgU0=. Проверяйте байты тела как пришли, время —
в пределах 5 минут, сравнение — постоянного времени. Тип событий — стенд 09.11.2026; подпись от стенда
не зависит.
8. MCP и API v2
Получите /api/v1/mcp/info и /api/v2. Сколько инструментов у MCP, какие пишут в базу и какие ограничения
частоты? Сколько адресов у API v2 и сколько живёт ключ? См. MCP,
API v2.
Ответ
MCP: 19 инструментов, путь /mcp, токен на 30 дней. Пишет только run_calculation (право «Запуск расчётов»,
5 запусков за 10 минут); всего — 60 вызовов в минуту на пользователя. API v2: 9 адресов (корень, дефекты, события,
отключения, наряды с созданием заявки, приём показаний телеметрии), корень /api/v2 перечисляет те же 11 типов
событий и ссылку на /api/v2/openapi.json. Ключ живёт API_TOKEN_DAYS = 365 дней по умолчанию (не больше 730),
отозвать его можно только сменой пароля или блокировкой владельца. Стенд, 09.11.2026.