Как сэкономить 90% времени на обновлении данных в «Техзор» через API и Python

Заметка вокруг языка программирования python и tehzor - веб сервиса для операционного и приемочного контроля при строительстве и эксплуатации зданий

⌘ Задача:

В базу данных веб приложения tehzor, для жилого квартала из 1 536 квартир, необходимо вставить сведения для каждой квартиры (площади, гарантийные сроки, типы отделок, контакты собственников...) и такой жилой квартал далеко не один.

⌘ Решение:

Направить табличные сведения в техподдержку, и они все сделают.

Рис 1. Парам-парам-пам!

Но этот путь слишком прост... Я решил написать и впервые попробовать опубликовать python пакет в PyPI (хранилище программного обеспечения для языка python)

Бремя первого пакета легло на python обертку над API tehzor:

Ключевая задача, которую я для себя ставил - пакет должен был асинхронным, чтобы автоматизированным способом иметь возможности обновить сведения для более чем 1000 элементов не за 20 минут, а за 1-ну.

Вау! Теперь код, который я писал, может установить любой желающий ?

pip install -U tehzor

Рис 2. 😊

Оговорюсь сразу, что в python пакете tehzor пока доступны не все методы, которые предоставляет API и добавляются по мере необходимости, но благодаря open-source решению, пакет открыт для редактирования всем желающим.

Рассмотрим пример:

Внесем сведения о типах отделки для 332 квартир из 1 536 для жилого комплекса из четырех секций.

𝟙 этап. Сбор данных

Подготовим файл space_table.xlsx (он же в дальнейшем будет отправной точкой для обновления прочих других сведений для квартир). Cтолбцы в файле:

1. Дом/Корпус
2. номер квартиры
3. тип отделки

4. идентификатор помещения (квартиры) - spaces_id

5. идентификатор типа отделки - decor_id

6... и прочие любые другие столбики (этаж, сроки, ФИО, телефоны ...)

Рис 3. Содержание excel файла space_table.xlsx

Идентификаторы (UUID) помещений (space_id) и типов отделки (decor_id) конечно же возможно запросить у техподдержки, но Вы, как уже успели заметить, здесь легких путей не ищут, поэтому раздобудем сведения сами:

И тут могу предложить три варианта:

① вариант

http запросом прямо в excel через Power query

Этот вариант скорее более простой и понятней. Детали в коротком видео:

② вариант

Через веб-браузер в режим разработчика достать JSON файл и обработать данные, например, тем же PowerQuery:

Рис 4. Режим разработчика в веб-браузере

Но так как эта публикация больше про Python, то раскрою здесь немного детальней третий вариант:

③ вариант

С использованием методов python пакета tehzor: get_spaces, get_space_types_decorations и библиотекой pandas для импорта полученных сведений в excel файл.

pip install "pandas[excel]"

Как оказалось dzen Не лучшее место для размещения программного кода, поэтому ссылка на код здесь, ниже картинка и пояснения (интересно, как эта фраза повлияет на выдачу этой публикации ? 😂):

Рис 5. Код получения идентификаторов помещений в excel файл spaces.xlsx

В начале файла подключаются библиотеки asyncio, tehzor, pandas. Ключ API импортируется из config модуля, а там подключается из .env

Рис 6. Адресная строка веб браузера

construction_site - словарь dict, значения для которого я взял из браузерной строки (рис 6.) - это идентификаторы тех самых четырех секций жилого комплекса.

Основная функция main() асинхронная. Ее запускаю в основном цикле событий, который открывается и закрывается методом asyncio.run() строка 40

thz - инициализация экземпляра класса TehzorAPI методом create(). Объект при инициализации по умолчанию открывает aiohttp сессию, которую необходимо закрывать ручками, вызывая метод session_close() - строка 37

space_list - список всех помещений, который получаю методом get_spaces() TehzorAPI.

data - список конкретно необходимых мне помещений: секции которые находятся в словаре construction_site и тип у которых равен 'Квартиры'.

Из полученного списка создаю pandas DataFrame df для сортировки по двум столбикам: id здания/секции и по номерам квартир (они в моем случае числовые, поэтому смело переопределяю тип на Int) для возможности отсортировать квартиры по возрастанию.

Рис 7. Cодержание excel файла space.xlsx

На выходе готовый файл space.xlsx: здесь id это наши space_id, которые перенесены в основной файл space_table.xlsx (рис. 3)

Идентификаторы типов отделки также возможно достать любым из 3 способов:

• Power Query: метод API GET /space-types-decorations (как выше в видео)
• Посмотреть в браузере в файлике space-type-decoration-set (рис. 4)
• Методом python пакета tehzor: get_space_types_decorations, пример

𝟚 этап. Обновляем данные по квартирам

На сегодня API версии 1.23.5 позволяет обновить такие свойства помещения:

Рис 8. Схема EditingSpace из tehzor API

В python пакете tehzor за эту схему отвечает pydantic модель SpaceUpdate, в ней нас интересует свойство type_decoration

Ниже сам код вставки типов отделки для всех квартир. Ссылка на код для копирования

Рис 9. Код вставки типов отделки для квартир указанных в файле space_table.xlsx

Библиотекой pandas определяем DataFrame df из подготовленного excel файла space_table.xlsx (Рис. 3)

Забираем из DataFrame столбцы с UUID помещений и типов отделки, игнорируя строки в которых не указан UUID типа отделки.

Затем, используя асинхронные задачи, отправляем обновления для каждого помещения через TehzorAPI.update_space(), добавляя или изменяя данные о типе отделки.

Результат

Рис 10. Шахматка из веб приложения «Техзор» с установленным фильтром по квартирам с финишной типовой отделкой

Вывод

Имея исходный excel файл с идентификаторами, можно легко и в считанные секунды обновить сведения по всем помещениям.

PS

Кстати, о считанных секундах: чтобы сервер Tehzor не отклонил массовые одновременные запросы на обновление, для метода TehzorAPI.update_space() по умолчанию установлено ограничение на 25 одновременных вызовов. Это значение регулируется параметром limit_threads в методе TehzorAPI.create(). Для других методов ограничения не установлены.

Ссылка на python обертку (Github)

Ссылка на официальное API Tehzor (https://api.tehzor.ru/docs)