Песочницы по запросу

Песочница — это полностью изолированный арендатор Tango Vision: собственная база данных PostgreSQL, наполненный граф здания и выделенный стек tv-api — на собственном поддомене. Вы разрабатываете в ней вместо продакшена.

Зачем

• Изоляция. Данные вашей песочницы физически отделены от любого другого арендатора.
• Реалистичность. Она наполнена параметризованным зданием (торговый центр или офис) с помещениями, элементами и телеметрией — чтобы ваш модуль отрисовывался на данных реальной формы.
• Одноразовость. Сбросьте её, когда навели беспорядок; она истекает автоматически.

Создание — из панели управления

В консоли платформы есть страница Sandboxes (в админ-навигации). Вставьте ваш API-ключ, затем New sandbox:

Поле	Значение
Name	Отображаемое имя; поддомен выводится из него
Building type	mall или office
Storeys	1–50
Area (m²)	Общая площадь
TTL (days)	1–30; автоочистка после

Строка появляется в статусе provisioning и переходит в ready, когда база засеяна — от минуты на маленьком здании до нескольких минут на реалистичных параметрах — с URL вида:

https://acme-cafm-dev-x7k2.sandbox.k8s.tangovision.dev

Создание — через CLI

SDK покрывает весь жизненный цикл, так что писать curl руками не нужно. Войдите один раз (вход через CLI) — и каждая команда sandbox аутентифицируется сама, из системного хранилища ключей:

npx @tv/extension-sdk login

npx @tv/extension-sdk sandbox create \
  --name="acme-cafm-dev" \
  --type=mall \
  --storeys=3 \
  --area-sqm=20000 \
  --seed-telemetry-days=14

В CI и любой другой неинтерактивной среде вместо входа используйте API-ключ, выпущенный в портале — явные учётные данные всегда важнее сохранённой сессии:

export TV_API_TOKEN=$SANDBOX_API_KEY   # tvk_-ключ из портала
npx @tv/extension-sdk sandbox list

По умолчанию CLI обращается к https://sandbox-api.k8s.tangovision.dev; перенаправить его можно флагом --api=<url> (или переменной TV_SANDBOX_API_URL).

Подкоманда	Что делает
create	Создаёт песочницу. --dry-run генерирует наполнение локально, не обращаясь к сервису.
list	Список ваших песочниц
connect <id>	Печатает данные подключения и переменные окружения для модуля
extend <id> --days=N	Продлевает TTL
reset <id>	Очищает и заново наполняет, не удаляя
delete <id>	Удаляет немедленно

Дополнительные параметры наполнения: --spaces-min / --spaces-max (по умолчанию 10/30), --equipment-density=sparse|realistic|dense, --occupancy-profile=24x7|office-hours|peak-evenings, --ttl-days=N (1–30, по умолчанию 14) и --seed=<строка> для детерминированной генерации. Добавьте --format=json к любой подкоманде, чтобы использовать её в скриптах.

Создание — через API

curl -X POST https://sandbox-api.k8s.tangovision.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $SANDBOX_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "acme-cafm-dev",
    "buildingType": "mall",
    "storeys": 3,
    "areaSqm": 20000,
    "ttlDays": 14
  }'

Ответ — 202 Accepted. Развёртывание идёт в фоне (база данных, граф здания с данными и отдельный стек tv-api — на реалистичных параметрах это несколько минут), поэтому запись возвращается в статусе provisioning:

{
  "sandboxId": "sbx_...",
  "name": "acme-cafm-dev",
  "slug": "acme-cafm-dev-x7k2",
  "status": "provisioning",
  "apiUrl": "https://acme-cafm-dev-x7k2.sandbox.k8s.tangovision.dev",
  "expiresAt": "2026-06-13T...",
  "extensionsRemaining": 2
}

Опрашивайте эндпоинт детализации, пока status не выйдет из provisioning:

curl -H "Authorization: Bearer $SANDBOX_API_KEY" \
  https://sandbox-api.k8s.tangovision.dev/api/v1/sandboxes/sbx_...

ready — песочница готова (заполнены buildingId и итоговый apiUrl); failed — в failureReason записана причина. CLI (sandbox create) выполняет опрос сам и завершается, когда песочница готова.

Жизненный цикл

Действие	Эндпоинт
Список	GET /api/v1/sandboxes
Создать	POST /api/v1/sandboxes
Продлить TTL	POST /api/v1/sandboxes/:id/extend (тело { "days": 7 })
Сбросить (очистить + пересоздать)	POST /api/v1/sandboxes/:id/reset
Удалить	DELETE /api/v1/sandboxes/:id

Квоты

Чтобы общий кластер оставался здоровым:

• 3 одновременно активные песочницы на одного внешнего разработчика
• 2 продления TTL на песочницу
• 30 дней — максимальный TTL

Они обеспечиваются провижионером; при достижении лимита вы получите понятный 429/400.

Что внутри свежей песочницы

• Организация + площадка + здание, наполненные через @tv/sandbox-seed
• Этажи, помещения, элементы и точки, размер которых задан вашими параметрами
• До 30 дней дозаполненной телеметрии (настраивается через seedTelemetryDays)
• Стандартная схема tv-api, так что работают все эндпоинты платформы

Направьте PlatformContext вашего модуля на apiUrl песочницы и разрабатывайте так, как будто это продакшен — потому что структурно это он и есть.