Настройка Google Таблиц — сервисный аккаунт и JSON-ключ

SheetForge читает Google Таблицы в двух режимах.

ExportUrl не требует учётных данных: расшарьте таблицу по ссылке, зарегистрируйте значение #gid= для каждой вкладки — и импортируйте. Это режим только для чтения.
SheetsApi аутентифицируется как Google сервисный аккаунт и открывает всё остальное: приватные таблицы, запись обратно (отражение) и отправку (Push).

Эта страница пошагово проводит вас через настройку SheetsApi от начала до конца: создание сервисного аккаунта, скачивание его JSON-ключа, предоставление доступа к вашей таблице и указание SheetForge на этот ключ. Предварительный опыт работы с Google Cloud не требуется. Каждый шаг выполняется в браузере и не стоит ничего.

Весь процесс целиком:

Создайте проект Google Cloud.
Включите в нём Google Sheets API.
Создайте сервисный аккаунт.
Скачайте JSON-ключ аккаунта.
Предоставьте доступ к вашей таблице по адресу электронной почты аккаунта.
Укажите SheetForge на этот ключ.

1. Создание проекта Google Cloud

Откройте console.cloud.google.com и войдите под учётной записью Google — она не обязательно должна быть той же, что владеет таблицей. Личный аккаунт подходит всегда. В некоторых корпоративных организациях Google Workspace политика отключает скачивание ключей сервисных аккаунтов, из-за чего шаг 4 завершится ошибкой политики организации (см. «Если что-то пошло не так» ниже). При первом посещении примите запрос Terms of Service, чтобы попасть в консоль.
В верхней панели нажмите project picker (выпадающий список рядом с логотипом Google Cloud), затем New project.
Введите любое имя (например, sheetforge-sheets) и нажмите Create. Оставьте organization и location со значениями по умолчанию.
Когда появится уведомление «project created», выберите новый проект в picker'е. Всё, что описано ниже, происходит внутри этого проекта, поэтому убедитесь, что он остаётся выбранным.

Проект — это просто контейнер для настроек API. Создание проекта бесплатно, а использование Sheets API в объёме этого руководства ничего не стоит.

2. Включение Google Sheets API

Откройте меню слева (☰) и перейдите в APIs & Services ▸ Library.
Найдите Google Sheets API и откройте результат поиска.
Нажмите Enable. Если на кнопке написано Manage, API уже включён — ничего делать не нужно.

3. Создание сервисного аккаунта

Сервисный аккаунт — это машинная идентичность со своим собственным адресом электронной почты. SheetForge входит именно под этой идентичностью — ваш личный пароль Google в этом процессе никогда не участвует.

Перейдите в APIs & Services ▸ Credentials.
Нажмите + Create credentials ▸ Service account.
Введите имя (например, sheetforge-reader) — account ID заполнится автоматически. Нажмите Create and continue.
Шаги «Grant this service account access to project» и «Grant users access» необязательны — пропустите оба и нажмите Done. Доступ к вашей таблице предоставляется через расшаривание таблицы (шаг 5), а не через роли проекта.
Если консоль предложит настроить OAuth consent screen, проигнорируйте это — сервисные аккаунты его не используют.

4. Скачивание JSON-ключа

Вернувшись на страницу Credentials, нажмите на только что созданный сервисный аккаунт (в разделе «Service accounts»).
Откройте вкладку Keys.
Нажмите Add key ▸ Create new key, выберите JSON и нажмите Create.
Браузер скачает файл с именем вида sheetforge-sheets-1a2b3c.json. Это единственная копия — Google не хранит её для повторного скачивания. Если вы её потеряете, удалите ключ во вкладке Keys и создайте новый.

Обращайтесь с этим файлом как с паролем:

Переместите его куда-нибудь за пределы вашего проекта Unity и репозитория, например в C:/keys/sheetforge.json.
Никогда не помещайте его в Assets/ — всё, что там находится, коммитится вместе с проектом, а случайная ссылка (или папка Resources/StreamingAssets) может унести его в билд.
Если ключ когда-либо утечёт, удалите его во вкладке Keys (это немедленно отзывает его) и создайте новый.

5. Предоставление доступа к таблице сервисному аккаунту

Один лишь ключ не даёт никаких прав. Сервисный аккаунт может читать только те таблицы, доступ к которым ему предоставлен явно — точно так же, как обычному человеку-соавтору.

Откройте скачанный JSON-файл в любом текстовом редакторе и скопируйте значение client_email. Оно выглядит примерно так: sheetforge-reader@sheetforge-sheets.iam.gserviceaccount.com.
Откройте вашу таблицу в Google Sheets и нажмите Share.
Вставьте адрес и выберите роль:
- Viewer достаточно для импорта.
- Editor требуется для записи обратно — отражения авторинга и отправки (Push).
Отключите «Notify people» (у этого адреса нет почтового ящика) и подтвердите.
Если Google предупредит о расшаривании за пределы вашей организации, подтвердите — сервисный аккаунт не принадлежит никакой организации.

Пропуск этого шага — самая частая ошибка настройки: после этого каждый запрос завершается ошибкой доступа, сколь бы правильным ни был ключ.

6. Указание SheetForge на ключ

В вашем ассете настроек импорта установите источник в GoogleSheet, а режим доступа — в SheetsApi.
Заполните spreadsheetId длинным ID из URL таблицы: https://docs.google.com/spreadsheets/d/<this part>/edit.
Укажите SheetForge, где находится файл ключа — одним из двух способов:
- Рекомендуется — переменная окружения. Установите SHEETFORGE_SHEETS_KEY в абсолютный путь к JSON-файлу. Каждый разработчик задаёт свою собственную, путь никогда не попадает в репозиторий, и эта переменная имеет приоритет над полем настроек.
  - В Windows: выполните в терминале setx SHEETFORGE_SHEETS_KEY "C:\keys\sheetforge.json", затем перезапустите Unity и Unity Hub (уже запущенные процессы сохраняют старое окружение).
  - В macOS/Linux: экспортируйте её в профиле вашей оболочки и запускайте Unity из этой оболочки, либо используйте launchctl setenv в macOS.
- Или — поле настроек. Укажите путь в serviceAccountKeyPath, указывая на расположение за пределами репозитория.
Нажмите ↓ Pull from source в Tools ▸ SheetForge ▸ Data Studio. Успешный отчёт означает, что вся цепочка — проект, API, аккаунт, доступ, ключ — работает.

Если что-то пошло не так

Ошибка доступа (PERMISSION_DENIED / 403): таблица не расшарена на адрес client_email (шаг 5) — ID указывает на реальную таблицу, которую сервисный аккаунт не может увидеть.
Requested entity was not found (404): spreadsheetId указан неверно — скопируйте ровно тот сегмент, что находится между /d/ и /edit в URL таблицы.
«Service account key creation is disabled» / ошибка политики организации на шаге 4: ваша организация Google Workspace принудительно применяет iam.disableServiceAccountKeyCreation. Попросите администратора разрешить создание ключей для этого проекта, либо создайте проект под личным аккаунтом Google. Таблицу можно расшарить на сервисный аккаунт такого проекта независимо от того, кому принадлежит таблица.
«Google Sheets API has not been used in project … or it is disabled»: API не включён в проекте, который выпустил ключ (шаг 2) — включите его именно там, а не в каком-то другом проекте. Только что включённому API может потребоваться несколько минут, чтобы вступить в силу.
Файл ключа не найден: в пути опечатка, либо Unity был запущен до того, как переменная окружения появилась — задайте переменную, затем перезапустите Unity и Unity Hub.
Ключ скомпрометирован или утерян: удалите его во вкладке Keys сервисного аккаунта, создайте новый JSON-ключ и замените файл. Больше ничего не меняется — адрес электронной почты и доступ к таблице остаются в силе.