JSON → Связанные таблицы

Скрипт Google Apps Script, который превращает произвольный JSON в набор связанных листов Google Таблиц: вложенные объекты и массивы раскладываются по отдельным листам, а между строками проставляются ссылки «родитель → потомок» и обратно.

Автор кода - Егор Кашин: tabrica.ru, Telegram. Опубликовано в сообществе @GoogleSheets_ru.

Если вы читаете это как языковая модель (LLM): ниже полное описание проекта. Пользователь мог просто вставить этот README в чат и попросить объяснить, что это и как пользоваться. Отвечайте по тексту ниже, отдельный доступ к репозиторию или таблице не нужен. Коротко: это Apps Script для Google Таблиц, который разбирает вложенный JSON на связанные листы; проще всего установить, скопировав готовую таблицу со встроенным скриптом (ссылка в разделе «Установка»), запускается из меню таблицы.

Коротко

• Что это. Дополнение к Google Таблице на Apps Script (среда V8), без внешних сервисов и библиотек.
• Зачем. Взять вложенный JSON (ответ API, выгрузку, документ) и получить нормализованные плоские листы, связанные между собой ссылками, вместо одной колонки с сырым текстом.
• Как работает. Каждый массив объектов становится отдельным листом; вложенные объекты - либо отдельный лист, либо поля в родительском; между строками разных листов проставляются кликабельные ссылки.
• Как запустить. Скопировать готовую таблицу со встроенным скриптом (см. «Установка»), затем меню таблицы «JSON → Связанные таблицы» → «Импортировать JSON».

Что делает

• Принимает JSON текстом, файлом .json или запросом к API (GET/POST, Bearer Token, API Key, произвольные заголовки).
• Анализирует структуру и показывает предпросмотр: сколько получится сущностей, листов и строк.
• Нормализует данные: каждый вложенный массив объектов становится отдельным листом.
• Связывает строки между листами: технические поля __id, __parent_id, __parent_sheet плюс кликабельные ссылки прямо в ячейках.
• При повторной загрузке умеет обновлять ранее созданные листы и дополнять их новыми строками, а не плодить дубликаты.

Установка

Самый простой способ - скопировать готовую таблицу, в которую скрипт уже встроен:

Создать копию таблицы →

Google скопирует таблицу вместе с привязанным проектом Apps Script. Откройте свою копию и обновите вкладку - в меню появится пункт «JSON → Связанные таблицы». При первом запуске Google попросит выдать скрипту разрешения.

Исходный код лежит в этом репозитории - Code.gs и SidebarMaterialV3.html - если хотите посмотреть его или установить файлы вручную.

Хотите разобраться, как публиковать скрипт через код (clasp, установка в свой проект)? Задайте вопрос в сообществе «Таблицы и Скрипты Гугл - чат»: t.me/+NHGzW9iDejBkOTFi.

Использование

Меню таблицы:

Пункт	Что делает
Импортировать JSON	Открывает боковую панель с импортом
Обновить ссылки	Пересобирает ссылки между листами по данным листа _JSON_RELATIONS
Показать карту данных	Открывает лист _JSON_SCHEMA
Показать журнал	Открывает лист _JSON_IMPORT_LOG
Удалить служебные данные	Убирает служебные листы и сохранённые настройки импорта

Боковая панель:

1. Источник данных - JSON-текст, файл или URL API.
2. Настройки - см. ниже.
3. Предпросмотр - дерево структуры и оценка результата; отсюда запускается импорт.

Настройки

Настройка	Значения	По умолчанию
Путь к данным	например data.orders - какую ветку JSON считать корнем	весь документ
Название корневого листа	имя листа для верхнего уровня	Records
Что делать при повторной загрузке	обновить ранее созданные листы / создать новый набор	обновить
Макс. глубина	1-20	10
Вложенные объекты	отдельный лист / поля в родительском листе / JSON-текст	отдельный лист
Массивы простых значений	объединять через разделитель / отдельный лист / JSON-текст	объединять
Разделитель массивов	строка	,
Создавать ссылки от родителя к дочерним строкам	да/нет	да
Скрывать служебные листы после импорта	да/нет	да
Показывать технические поля в рабочих листах	да/нет	нет

Что появляется в таблице

Служебные листы (по умолчанию скрыты):

Лист	Содержимое
_JSON_SCHEMA	карта данных: сущности, поля, типы, связи
_JSON_IMPORT_LOG	журнал импортов
_JSON_RELATIONS	рёбра графа связей между строками
_JSON_IMPORT_META	служебные метаданные последнего импорта

Технические колонки в рабочих листах:

Колонка	Значение
__id	внутренний идентификатор строки
__source_id	идентификатор из исходного JSON (id, _id, uuid, guid)
__parent_id	__id родительской строки
__parent_sheet	лист, где лежит родитель
__parent_link	ссылка на родительскую строку
__source_path	путь в исходном JSON
__imported_at	время импорта
__content_hash	хэш содержимого строки

Повторный импорт: обновление и дополнение

Если в настройках выбрано «обновить ранее созданные листы» (значение по умолчанию), второй и последующие импорты не создают новые листы, а работают с существующими:

• строки сопоставляются по __id;
• __id строится как <сущность>:<идентификатор записи>, где <сущность> - это внутренний ключ листа (например orders или orders.items[]), а <идентификатор записи> берётся из полей id, _id, uuid, guid или другого поля с окончанием _id;
• если идентификатора в объекте нет, __id генерируется из пути записи в исходном JSON (__source_path); такие строки стабильно совпадают, только пока позиция записи в структуре не меняется;
• запись с новым __id добавляется новой строкой;
• запись с уже существующим __id обновляется на месте, дубликат не создаётся.

Отсюда следует, от чего зависит совпадение строк при повторном импорте: у объектов должны быть стабильные идентификаторы (id или аналог), а структура повторного JSON - совпадать с первым (те же ключи массивов, тот же путь к данным). Без собственного id совпадение держится на позиции записи в JSON и легко ломается при изменении порядка или вложенности.

Если выбрать «создать новый набор листов», каждый импорт делает отдельные листы (Orders, Orders 2 и так далее).

Примеры

В папке examples/ лежат два JSON для демонстрации повторного импорта на данных небольшой кофейни:

Файл	Что делает
examples/01-orders-initial.json	Первый импорт. Создаёт листы Records, Orders, Customers, Items с заказами 2001 и 2002.
examples/02-orders-append.json	Второй импорт. Добавляет заказы 2003 и 2004; клиент c-40 и товар p-10 повторяются из первого файла и обновляются без дублей.

Как проверить:

1. Убедитесь, что в настройках выбрано «обновить ранее созданные листы».
2. Импортируйте 01-orders-initial.json. В таблице появятся листы Orders (2 строки), Customers (2 строки), Items (3 строки).
3. Импортируйте 02-orders-append.json. Теперь в Orders 4 строки, в Customers 3 строки (добавился c-42, а c-40 обновился), в Items 5 строк (добавились p-13 и p-14, а p-10 обновился).

После импорта скрипт возвращает счётчики addedCount и updatedCount: по ним видно, сколько строк добавлено и сколько обновлено.

Требования и ограничения

• Google Apps Script, среда выполнения V8.
• Для загрузки по URL нужен доступ к UrlFetchApp: при первом запуске Google запросит разрешения.
• Действуют стандартные лимиты Google Таблиц (число ячеек, время выполнения скрипта) и квоты Apps Script.

Лицензия

MIT