Встраиваемые карты

Как карта выглядит и ведёт себя на чужом сайте, какие слои и поля в ней есть и как сайт управляет ею из своего кода — на странице Встраиваемая карта. Здесь — выдача и отзыв ключей.

Возможности

• Выдать ключ встраивания: для кого он, на каких сайтах карту можно показывать, какие слои и фрагменты открыты, показывать ли зоны отключений, начальный вид и срок действия.
• Сразу после выдачи — готовый код для сайта: iframe и SDK (события и команды карте), кнопки «Скопировать» и «Открыть карту» для проверки.
• Список ключей: начало ключа, сайты, слои, фрагменты, срок, когда карту последний раз открывали, когда ключ отозвали.
• «Отозвать» — с подтверждением; карта на сайтах ключа перестаёт открываться.

Как это работает

Ключ показывается один раз. Сервер создаёт ключ tge_… и хранит только его хеш SHA-256 и первые 10 знаков — по ним ключ узнают в списке. После «Готово» сам ключ больше не увидеть: потерянный ключ отзовите и выдайте новый.

Что записано в ключе.

• Сайты — от 1 до 20 адресов. Сервер оставляет от адреса только схему, хост и порт: https://akimat.kz/map/page станет https://akimat.kz.
• Слои — из пяти: участки, узлы, задвижки, потребители, источники тепла. По умолчанию отмечены участки и источники.
• Фрагменты — номера через запятую, до 200; пусто — вся сеть города.
• Зоны отключений — флажок есть всегда, но зоны появятся на карте, только если на сервере включена публичная лента отключений (PUBLIC_OUTAGES_ENABLED).
• Начальный вид — центр и зум карты в момент выдачи; без него карта открывается на всю сеть города.
• Срок — 90 дней, год или без срока.

Где действует. Ключ хранится в базе города (таблица tgid_embed_key) и открывает только этот город: ключ Алматы на карте Астаны получит «Ключ встраивания не принят: отозван, истёк или из другого города».

Кто проверяет сайт. Сайт-родителя проверяет сама страница карты в браузере. Сервер тайлов сайт не проверяет: ему хватает действующего ключа. Поэтому ключ не секрет — он защищает от чужой витрины на чужом сайте, но не от того, кто возьмёт ключ из кода страницы и запросит тайлы сам. Через ключ видно только то, что в нём открыто, и без персональных данных.

Отзыв. Ключ не удаляется: в списке у него появляется отметка «отозван» с датой (автора сервер тоже записывает), и он уходит вниз. Процесс сервера, принявший отзыв, перестаёт принимать ключ сразу; остальные помнят проверенный ключ до 60 секунд. Поэтому карта на сайтах гаснет в течение минуты. Повторный отзыв ничего не меняет. Ключ с истёкшим сроком перестаёт работать сам, его отметка в списке — «истёк».

«Открывали». Время последнего открытия карты по ключу сервер записывает не чаще раза в 10 минут.

Что нужно для работы

• Права: роль «Администратор».
• База: таблица tgid_embed_key в базе города; её создаёт API при подготовке базы.
• Сайт: адрес ТГИД должен быть доступен посетителям сайта (страница /itwin-map/embed и API тайлов).

Шаги

1. Откройте «Инструменты» и наберите в поиске «Встраиваемые карты» — пункт выделен рамкой.

   

2. Нажмите пункт — откроется окно.

   

3. «Новый ключ встраивания»: для кого ключ, сайты, где можно показывать карту (по одному на строку, без пути), слои (участки, узлы, задвижки, потребители, источники), зоны отключений (видны, только если на сервере включена публичная лента), номера фрагментов, срок действия и начальный вид. «Выдать ключ» создаёт ключ, он появляется в списке ниже: начало ключа, сайты, слои, когда карту открывали последний раз; отозванный ключ перестаёт работать в течение минуты.

   

Примеры

Карта на своём сайте и на чужом. Так проверено на копии Алматы (almatygid_copy): выдан ключ с сайтами http://127.0.0.1:5599/portal/page и https://example.invalid, фрагментом 1 и слоями по умолчанию. В списке ключ сохранился с сайтами http://127.0.0.1:5599 и https://example.invalid (путь отброшен), слоями «участки» и «источники». Во фрейме на http://127.0.0.1:5599 карта открылась; на http://127.0.0.1:5598 вместо карты — «Эта карта не разрешена для сайта http://127.0.0.1:5598». Без ключа сервер ответил «Нужен ключ встраивания (параметр key)», тайл неоткрытого слоя — отказом 403. После «Отозвать» сервер сразу перестал принимать ключ.

Если не получается

• На сайте вместо карты «Эта карта не разрешена для сайта …» — адреса сайта нет в ключе. Сравните схему (http или https), хост с www или без и порт: это разные сайты. Список сайтов у выданного ключа не меняется — выдайте новый ключ.
• «Ключ встраивания не принят: отозван, истёк или из другого города» — проверьте строку ключа в списке; если он активен, на сайте вставлен ключ другого города.
• Зон отключений нет, хотя флажок стоит — на сервере выключена публичная лента отключений.

Для администратора

• Выдача и отзыв ключа пишутся в журнал действий кодами EMBED_KEY_CREATE и EMBED_KEY_REVOKE (русской подписи у них нет).
• Ключи хранятся в базе каждого города отдельно; при переносе базы города ключи переезжают вместе с ней.
• Нагрузка: тайлы обзорных зумов (до 12) сервер держит в памяти 10 минут; участки на обзорных зумах прорежены по диаметру.

Для разработчика

• API: GET|POST /api/v1/embed/keys, DELETE /api/v1/embed/keys/{id} (отзыв) — администратор; GET /api/v1/embed/config?key=…, GET /api/v1/embed/tiles/{слой}/{z}/{x}/{y}?key=… — без входа. Код — routers/embed.py, database/embed.py (LAYERS, KEY_TTL_S, TOUCH_EVERY_S, MAX_ORIGINS).
• Веб: components/EmbedKeysDialog.vue (выдача, код iframe и SDK — utils/embedProtocol.ts), страница карты — pages/embed.vue, проверка сайта — frameAllowed и parentOrigin в utils/embedProtocol.ts.
• Тесты: e2e — e2e/functions/admin.spec.ts (страницы-родители на двух локальных портах).