zm2gs_Import

KO | EN

gitlite — search

#react #ai #golang #go #macos #awesome #kubernetes #vue #pytorch #security #ios #mcp #openai #open-source

(★ 10)

Export and Import to Zen Money via Google Sheets

zm2gs_Import Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Работа с Дзен Мани через Google Таблицы

Данная серия скриптов предназначена для интеграции данных приложения Дзен Мани с Google Таблицами через экспорт и импорт транзакций, счетов и категорий.

# Как использовать
Возьмите готовый [шаблон настроек](https://docs.google.com/spreadsheets/d/1tSTjqCeHK3t6BUOEQUnOXYQhDoTdJQWTZmOCuL_A1v4/edit?usp=sharing):

На листе Settings выставьте токен API в ячейку B1 (можно получить, перейдя по [ссылке](https://zerro.app/token)), а также названия используемых листов.

Зайдите в меню Extensions -> Apps Script, и последовательно скопируйте нужные вам скрипты и HTML-файлы через Files (+ Add a file) -> Script/HTML. Рекомендую начать с Settings, Main, Logs, Dictionaries и Export - в таком порядке. Порядок имеет значение, **Settings должнен идти первым в списке, затем Main, затем остальные.**

ВАЖНО. Модули постоянно обновляются, когда у меня доходят руки что-то поменять. Выкачивайте модули одновременно. Иначе выкачав часть скриптов, а через неделю решив добавить к ним ещё пару модулей, вы обнаружите, что новые модули не работают, т.к. ссылаются на более современную версию предыдущих скриптов.

Обновите файл таблиц. Если появилось меню "Дзен Мани", поздравляю, у вас получилось. Запустите любой пункт меню, чтобы появился запрос на предоставление скриптам необходимых прав, и подтвердите его. Запустите Дзен Мани -> Полная Синхронизация, чтобы проверить работу скриптов по экспорту данных из Дзен Мани. Выберите пользователя и валюту по умолчанию на листе настроек. Выберите, как производить обработку нескольких категорий - перечислять их в одной строке с разделителями, или же выделять под каждую отдельный столбец. Вы готовы приступить к работе!

Для работы используются:
* Скрипт [Settings](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Settings.gs) с настройками остальных скриптов - **обязателен**
* Скрипт [Main](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Main.gs) с описанием основных функций по синхронизации данных - **обязателен**
* Скрипт [Dictionaries](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Dictionaries.gs) для операций со словарями - **обязателен**
* Скрипт [Logs](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Logs.gs) для логгирования - необязателен
* Скрипт [Export](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Export.gs) - для экспорта транзакций с сервера в Google Таблицы
* Скрипт [Import](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Import.gs) - для импорта транзакций на сервер из Google Таблиц
* Скрипт [Tracking](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Tracking.gs) - для автоматического отслеживания измененных транзакций на листе импорта
* Скрипт [Validation](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Validation.gs) - для валидации значений категорий и счетов на листе импорта
* Скрипт [Categories](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Categories.gs) - для импорта и экспорта данных по категориям
* Скрипт [Accounts](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Accounts.gs) - для импорта и экспорта данных по счетам
* Скрипт [Merchants](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/Merchants.gs) - для импорта и экспорта данных по местам
* HTML-файл [CategoryReplacementDialog](https://github.com/nevill-spb/zm2gs_Import/blob/main/Scripts/CategoryReplacementDialog.html) для обработки замены одной категории на другую

Экспорт данных в Google Таблицы относительно безопасен, скрипт просто забирает их с сервера и раскидывает по ячейкам. Запросы же на изменение данных выполняются уже на ваш страх и риск. Защита от дурака предусмотрена, но не покрывает все случаи, тем более, что полной документации на API я не видел.

Скрипт Main добавляет в Google Таблицы меню "Дзен Мани", которое содержит следующие кнопки, в зависимости от установленных вами скриптов:
* Полная Синхронизация: последовательно вызывает скрипты синхронизации и экспорта транзакций, словарей, категорий, счетов и мест на отдельные листы. Включает обновление словарей
* Обновить Словари: обновляет только данные словарей и записывает их на отдельный лист

Подменю "Экспорт" (скрипт Export):
* Полный Экспорт: скачивает все доступные на сервере транзакции и записывает их на лист экспорта
* Инкрементальный Экспорт: скачивает изменения на сервере с момента последнего экспорта данных и применяет их к листу экспорта
* Подготовить лист изменений: скачивает изменения на сервере с момента последнего экспорта данных и записывает их в отдельный лист изменений
* Применить изменения: применяет изменения с отдельного листа к листу экспорта

Подменю "Импорт" (скрипт Import):
* Полный Импорт: полный импорт передает на сервер все операции с листа импорта, как новые. На текущий момент деактивирован
* Частичный Импорт: передает на сервер только новые операции, а также операции, отмеченные соответствующим флажком
* Отслеживать изменения (скрипт Tracking): включает триггеры отслеживания изменений на листе импорта, выставляющие флажок при изменении существенных данных транзакции
* Снять отслеживание (скрипт Tracking): выключает триггеры отслеживания изменений на листе импорта
* Setup Validation (скрипт Validation): включает проверку данных на соответствие справочникам на листе импорта
* Clear All Validation (скрипт Validation): выключает проверку данных на листе импорта

Подменю "Категории" (скрипт Categories):
* Загрузить: экспорт категорий с сервера на отдельный лист
* Сохранить: импорт категорий с отдельного листа на сервер
* Частично: частичный импорт категорий, отмеченных соответствующим флажком
* Заменить: полная замена категорий на сервере категориями с листа
* Заменить в операциях: замещает одну категорию другой по аналогии с функционалом веб-версии. Исходная категория при этом не удаляется

Подменю "Счета" (скрипт Accounts):
* Загрузить: экспорт счетов с сервера на отдельный лист
* Сохранить: импорт счетов с отдельного листа на сервер
* Частично: частичный импорт счетов, отмеченных соответствующим флажком
* Заменить: полная замена счетов на сервере счетами с листа

Подменю "Места" (скрипт Merchants):
* Загрузить: экспорт мест с сервера на отдельный лист
* Сохранить: импорт мест с отдельного листа на сервер
* Частично: частичный импорт мест, отмеченных соответствующим флажком
* Заменить: полная замена мест на сервере местами с листа

# Скрипт настроек Settings.gs

В нём задаются ячейки и листы, которые используют остальные скрипты. Откуда брать токен, какой лист использовать для экспорта или импорта. Большинство данных берётся с листа настроек, но есть также и те, которые нужно менять вручную. К ним относится порядок колонок на листах, цвета для подсветки изменений при инкрементальном экспорте, размер пакета для импорта транзакций, и др.

Основное, что может вам понадобиться - это список валют, с которыми работает скрипт словарей. Всего в справочнике валют их 137, я не захотел иметь в словаре полторы сотни строк, из которых используется максимум три. Поэтому валюты задаются в скрипте вручную по коду. Просто допишите в ALLOWED_CURRENCY_CODES, например, GBP для работы с фунтами стерлингов.

Документация на остальное будет, когда я решу, что выносить в общие настройки, а что нет.

# Cкрипт базовый Main.gs
В этот скрипт вынесены функции для синхронизации с сервером, вызываемые в остальных скриптах.

"Полная синхронизация" получает с сервера информацию о всех хранящихся объектах, а затем последовательно отдаёт их для обработки и обновления данных на листах словарей, данных, счетов, категорий и мест.

"Обновление словарей" - т.е. таблиц, где зашифрованный id объекта сопоставляется с отображаемым именем, - необходимо для задания пользователя и валюты по умолчанию на листе настроек, а также для корректного импорта. Обновлять словари следует перед каждой попыткой записи на сервер (если что-то меняли), т.к. данные записываются на лист в читаемом формате, и для перевода их в формат Дзен Мани необходимо обратное шифрование. В дальнейшем я, вероятно, автоматизирую этот процесс, пусть он и отнимает секунд пять перед каждым импортом, ну а пока следует запомнить правило: перед тем, как что-либо импортировать, необходимо удостовериться, что вы разговариваете с сервером на одном языке.

# Скрипт экспорта Export.gs

Здесь всё относительно просто. Большинство потребностей удовлетворит кнопка Full Export. Транзакции стягиваются с сервера, и раскидываются по ячейкам листа экспорта, задаваемого в настройках. Перед этим данные конвертируется в понятный человеческому глазу формат через сопоставление id категорий, счетов и валют с их названиями. После успешного экспорта обновляется время последней синхронизации на листе настроек.

Инкрементальный экспорт забирает с сервера транзакции по методу DIFF, т.е. изменения за период, прошедший со времени последней синхронизации на листе настроек по текущий момент. Изменения выносятся на отдельный лист, откуда они затем применяются к документу. Обращаю внимание, что изменённые транзации уже находятся на сервере, и инкрементальный экспорт не сделает ничего, чего не мог бы сделать полный экспорт. Однако, он может быть полезен для отслеживания изменений, ведь "дату последней синхронизации" на листе настроек можно устанавливать вручную.

Возможно, более полезными будут отдельные функции, которые использует инкрементальный экспорт. "Подготовка листа изменений" записывает изменения на отдельный лист, и сравнивает их с листом данных. Удалённые транзакции помечаются красным; те, что удалены на сервере, но ещё не удалены на листе (т.е. недавно удалённые) - оранжевым; те, что есть на листе (существующие) - жёлтым, а те, что созданы на сервере, но ещё не получены - зелёным. Это поможет вам отследить, что поменяется при попытке синхронизации через Full Sync или Full Export. Подсветка изменений производится в зависимости от того, что у вас записано на листе данных. Если они получены не через экспорт транзакций с сервера, подсветка может ввести вас в заблуждение.

Функция "Применить изменения" делает то, что заявлено - переносит изменения в лист с экспортируемыми данными. Быстрее было бы воспользоваться полным экспортом, однако изменения можно модифицировать перед применением - например, для последующего импорта модификаций на сервер, если что-то в них вас не устраивает.

# Скрипт импорта Import.gs

Дзен Мани хранит данные в формате JSON, в виде нескольких словарей ('account', 'tag', 'merchant', 'transaction' для аккаунтов, категорий, мест и транзакций) с полями, описывающими объект. Все объекты используют UUID в качестве идентификатора. UUID уникальны, и не принимаются к повторному использованию. Это значит, что при удалении категории или счёта, состояние "как было" вернуть уже невозможно, а можно только завести новые объекты с теми же свойствами. Таким образом, даже если вы сохраните полный слепок данных на определённую дату, бэкап сопряжён с определёнными сложностями, если вы меняли и, в особенности, удаляли счета и категории. Самый простой способ восстановления - сбросить аккаунт до чистого состояния, и импортировать все объекты с чистого листа.

Скрипт импорта транзакций определяет транзакцию без UUID как новую, и автоматически помечает строку к импорту при наличии хотя бы трёх столбцов: даты, счёта расхода или дохода, и суммы расхода или дохода. Все остальные поля можно оставить пустыми - в этом случае они будут сгенерированы автоматически - или же заполнить данными в формате, принимаемом API.

Изменение существующих транзакций производится через установку флага "Изменить" в транзакции. Скрипт попытается передать ваши изменения на сервер. Какие-то из них принимаются без вопросов, какие-то нет. Я бы рекомендовал ограничиться изменением оригинальных полей (те, что доступны при экспорте из приложения или на сайте), но экспрериментировать не возбраняется. Только учтите, что некоторые изменения могут довести транзакцию до состояния, которое приложение прочитать уже не сможет.

Удаление существующих транзакций производится через установку обоих флагов "Удалить" и "Изменить". При этом у транзакции обязан быть ID, в противном случае флаг "Удалить" будет проигнорирован и снят, а транзакция обработается как новая. Удалённые транзакции не могут быть восстановлены через снятие флага "Удалено", их необходимо импортировать заново.

Во время импорта строка преобразовывает название счёта, категории и места в формат Дзен, которому нужны их UUID. Все они должны быть перечислены в листе словарей; если транзакцию не удаётся расшифровать, строчка не будет импортирована. Это оправдано в случае словарей счетов и категорий, которые представляют собой сложные объекты, но словарь мест практически не содержит данных, кроме id и названия места. Поэтому если строка ссылается на место, которого нет в словарях, это место импортируется в словарь "на ходу". Что удобно, но влечёт за собой появление дубликатов, если вы проводите импорт без предварительного обновления словарей.

Импорт производится кусками по 100 транзакций (задаётся в скрипте настроек) во избежание проблем с отправкой большого количества данных. При импорте большого количества транзакций логгирование рекомендуется отключать, т.к. оно существенно замедляет процесс. Время выполнения скрипта ограничено шестью минутами, примите это к сведению при единоразовом импорте огромных файлов. Есть успешный опыт импорта 8600 операций за раз (засекал, сколько операций обработается за 5 минут без логгирования), но в целом - проявляйте осторожность. Впрочем, даже если скрипт прервётся, ничего страшного не случится, все ранее импортированные операции останутся на сервере, и будут помечены как переданные. Проблема возникнет у последнего кусочка, который будет передан лишь частично, и никак не отразит это в таблице (т.к. эта часть выполняется после успешной передачи всего куска операций), но это решаемо.

Ошибки импорта, при наличии таковых, выносятся на отдельный лист, и не прерывают импорт. Постарался учесть наиболее частые, если импорт проваливается без видимых причин - опишите свой случай, буду расширять базу предупреждений. Все операции, импорт которых по какой-либо причине не удался, остаются отмеченными флагом "Изменить", и могут быть поправлены перед новой попыткой импорта. С операций, успешно прошедших импорт, флаг "Изменить" снимается.

После импорта транзакций на сервер рекомендуется сделать экспорт операций с сервера, чтобы убедиться, что операция прошла успешно. Автоматически этого не происходит потому, что вызов функции экспорта очищает поле "Изменено" и сбрасывает любые изменения в файле данных, которые не были переданы на сервер.

# Скрипт отслеживания Tracking.gs
Для удобства редактирования данных "на ходу" собрал скрипт, который отслеживает изменения в важных столбцах транзакции, и выставляет флаг "Изменить" для последующего импорта. Логика примитивная, реагирует на добавление и удаление данных; сработает даже если просто удалить "данные" из пустой ячейки. Скрипт не запоминает ваши данные; даже если вы вернёте в ячейку прежнее значение, строка всё равно будет помечена как изменённая - но вреда от этого нет, даже если вы импортируете строку без изменений. Отслеживание изменений включается и отключается через подменю импорта.

# Скрипт валидации Validation.gs
Позволяет валидировать данные в определённых столбцах листа импорта, и выбирать счета/категории из выпадающего списка. Логика валидации настраивается внутри скрипта. Сейчас предлагает выбрать из всех доступных счетов и категорий, но в теории, можно отсеять архивные счета, сделать отдельную логику для основных и дополнительных категорий (тегов) и т.д.

# Скрипт категорий Categories.gs
Вы можете выгружать категории с сервера и обрабатывать их прямо на листе. Скрипт отсортирует родительские категории по алфавиту и разместит подкатегории непосредственно под родительскими.

Скрипт определяет, является ли категория новой, по имени и ID. Если ID пустой или отсутствует в справочнике, будет присвоен новый и создана новая категория. При этом сохраняются связи между родительскими категориями и их подкатегориями, т.е. вы можете выгрузить структуру категорий из другого аккаунта или бэкапа, и скрипт воссоздаст её. Единственное обязательное поле при создании новой категории - её имя, оно не должно быть пустым. Также желательно, чтобы оно не содержало символа разделителя категорий, который в скриптах импорта и экспорта взят за " | ".

Функция "Сохранить" сохраняет изменения на листе целиком и отправляет на сервер полный список категорий независимо от того, вносились ли в них изменения.

Функция "Частично" отправляет на сервер только изменения в операциях, отмеченных флажком "Изменить".

Функция "Заменить" замещает категории на сервере категориями с листа.

Удаление категорий производится через выставление флажка "Удалить" и передачу изменений путём вызова Сохранить/Частично. По неизвестным мне причинам удаление категорий занимает очень много времени, и ответа от сервера вы, скорее всего, не дождётесь. Тем не менее, операция будет выполнена - но в случае с большим количеством категорий это может занять несколько минут или часов. В течение этого времени сервер не считает категории удалёнными; запаситесь терпением и не проводите операций с удаляемыми категориями. Проверить, выполнена ли операция корректно, можно, выгрузив категории с сервера - отправленные на удаление помечаются красным цветом.

Удаление родительской категории приводит также к удалению всех её дочерних категорий. Если в одном запросе с удалением родительских категорий поменять связи дочерних с удаляемыми родительскими, дочерние категории удалены не будут - даже если вы назначите им в родители другую удаляемую категорию.

При удалении категорий ведётся подсчёт удаляемых категорий (включая дочерние), а также затрагиваемых операций. Скрипт предупредит вас, если вы попытаетесь удалить "непустую" категорию.

# Скрипт счетов Accounts.gs
Всё то же самое, что для категорий, только объект другой.

Есть три режима работы - "Сохранить", "Частично" и "Заменить". "Сохранить" обрабатывает все строки на листе счетов (добавляет новые, если ID нет в списке текущих; меняет существующие; удаляет счета, отмеченные флагом "Удалить"), "Частично" - обрабатывает только строки, отмеченные флагом "Изменить". Функция "Заменить" пытается взять структуру с листа счетов, и привести счета на сервере в соответствие с ней, т.е. воссоздать счета с листа, которых нет на сервере, и удалить с сервера те счета, которых нет на листе. Функция "Заменить" определяет, существует счёт или нет, по его ID - т.е. счета с одинаковым названием, но с разными ID для неё разные.

Для переноса счетов из другого аккаунта или восстановления из бэкапа рекомендуется использовать функцию "Заменить".

Для депозитных счетов необходимо заполнить поля: "Вклад с даты", "Срок", "Ед. изм. срока", "Шаг погашения", "Ед. изм. погашения".

Счёт "Долги" является системным, у него своя логика обработки: он не может быть удалён или создан.

Удаление счетов производится через выставление флажка "Удалить" и передачу изменений путём вызова Сохранить/Частично. При удалении счетов ведётся подсчёт затрагиваемых операций. Скрипт предупредит вас, если вы попытаетесь удалить счёт с операциями. Будьте аккуратны, в отличие от обычного удаления операций (в приложении или через скрипт импорта) восстановление операций с удалённого счёта невозможно без бэкапа.

# Изменения
- 06.07.25. Выпущена версия 1.0. Умеет работать с операциями, категориями, счетами и местами.
- 09.07.25. Жаловались, что скрипт категорий зависает при попытке обработать 7000 категорий за раз. Оптимизировал, теперь не зависает. Тестируется режим параллельной отправки нескольких запросов на удаление.

В планах: 
* Добавить бэкапы остальных объектов JSON
* Разобраться с кредитными счетами, их принципом работы и отличиями от остальных
* Вынести больше настроек из скрипта Settings в лист настроек
* Дописать функциональную валидацию, научить её различать категории и теги
* Заменить инициализацию на ленивую в скриптах импорта, экспорта и словарей
* Вывести больше данных в читаемый формат
* Настроить автообновление справочников при импорте
* Настроить автосинхронизацию по расписанию

zm2gs_Import

zm2gs_Import Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

zm2gs_Import

zm2gs_Import Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README