Як підключити Google Sheets до застосунку

Щоб підключити Google Sheets до застосунку, увімкніть Google Sheets API у проєкті Google Cloud, створіть service account, надайте доступ до таблиці для email цього service account і збережіть його ключ як секрет на сервері. Далі ваш сервер читає рядки через spreadsheets.values.get і додає їх через spreadsheets.values.append. Якщо користувачам потрібно підключати власні таблиці, використовуйте OAuth; якщо таблиця повністю публічна, для читання достатньо простого API-ключа.

Цей гід пояснює, який метод підходить, які виклики вам знадобляться, квоти та підводні камені, а також промпти для конструктора застосунків на основі ШІ. Відомості Google взято з документації розробника Google станом на вересень 2026 року.

Навіщо підключати таблицю

Поширені причини:

• Збереження робочого процесу команди. Персонал і далі редагує прайс-лист чи розклад у Sheets, а застосунок їх показує.
• Збір даних там, де людям і так зручно дивитися. Нові реєстрації, замовлення або відповіді з форм потрапляють у рядки.
• Звітність. Експорт даних застосунку в таблицю для людей, які працюють у таблицях.
• Проміжний етап. Почніть з таблиці, а потім перейдіть на нормальну базу даних. Див. як перетворити таблицю на застосунок.

Оберіть спосіб входу застосунку в Google

Посібник Google з обліковий даних описує три типи:

Для більшості застосунків правильний вибір — service account: один набір облікових даних, що належить вам, із доступом лише до таблиць, якими ви явно поділилися.

Покроково з service account

1. Створіть або виберіть проєкт Google Cloud і увімкніть Google Sheets API.
2. Створіть service account і ключ для нього. Ключ — це JSON-файл; ставтеся до нього як до пароля.
3. Надайте доступ до таблиці email service account як Viewer для читання або Editor для запису. За посібником Google це робиться через звичайний екран спільного доступу.
4. Збережіть ключ як секрет на сервері, наприклад GOOGLE_SERVICE_ACCOUNT_JSON, а ID таблиці (довгий рядок з URL таблиці) — як SHEET_ID.
5. Викликайте API із сервера за допомогою клієнтської бібліотеки Google для вашої мови.
6. Кешуйте читання, якщо багато відвідувачів бачать ті самі дані, щоб не впиратися в квоту.

Виклики, які вам знадобляться

Із посібника Google з читання і запису значень:

Діапазони задаються у нотації A1. Google зазначає, що діапазон без назви аркуша, наприклад A1:B2, застосовується до першого аркуша, тож називайте вкладку явно, щоб уникнути несподіванок, коли хтось переставить вкладки.

RAW проти USER_ENTERED

Для запису потрібен valueInputOption:

• RAW зберігає саме те, що ви надіслали, як текст. =1+2 зберігається як текст =1+2.
• USER_ENTERED обробляє вхідні дані так, ніби їх ввели в Sheets: дати стають датами, а =1+2 стає формулою.

Якщо ви записуєте текст, який користувачі ввели у вашому застосунку, використовуйте RAW. З USER_ENTERED хтось може надіслати формулу, яка спрацює, коли колега відкриє таблицю.

Квоти і помилки

Станом на вересень 2026 року сторінка лімітів Google Sheets API містить такі значення:

Денного ліміту немає, доки ви в межах хвилинних квот. Перевищення повертає 429: Too many requests, і Google рекомендує експоненційну затримку з обрізанням: чекайте довше після кожної невдалої спроби, з випадковою затримкою, до певного максимуму. Один запит, що триває понад 180 секунд, завершується тайм-аутом.

На практиці: не викликайте API при кожному перегляді сторінки. Кешуйте дані таблиці хоча б на хвилину, групуйте читання через batchGet і групуйте записи, де це можливо.

Варіанти та компроміси

Для всього, де багато користувачів або чутливі дані, база даних — надійніше джерело істини. Див. що таке база даних.

Промпти для вашого ШІ-конструктора

Читання таблиці:

Покажи вкладку «Menu» нашої Google-таблиці на сторінці меню. Використовуй Google Sheets API із сервера з service account, JSON-ключ якого зберігається в секреті GOOGLE_SERVICE_ACCOUNT_JSON, а ID таблиці — у SHEET_ID. Читай діапазон Menu!A2:D (назва, опис, ціна, категорія). Кешуй результат на 5 хвилин. Якщо API не відповідає, показуй останню закешовану версію. Ніколи не надсилай ключ у браузер.

Запис рядків:

Коли хтось надсилає контактну форму, зберігай її в нашій базі даних і також додавай рядок у вкладку «Leads» (дата, ім'я, email, повідомлення) за допомогою spreadsheets.values.append з valueInputOption RAW. Якщо Google повертає 429, повторюй з експоненційною затримкою; якщо все одно не виходить, залиш лід у базі даних і повторі пізніше.

Поширені помилки

• Забути надати доступ до таблиці email service account. API тоді повертає помилку доступу, хоча ключ правильний.
• Ключ у фронтенді чи репозиторії. JSON-ключ дає доступ до кожної таблиці, якою з ним поділилися. Див. як зберігати ключі API в безпеці.
• Використання USER_ENTERED для введення користувачів, що дозволяє впровадження формул.
• Виклик API при кожному запиті і досягнення квоти на хвилину під час першого сплеску трафіку.
• Залежність від позицій стовпців. Хтось вставить стовпець, і застосунок читатиме не ті дані. Читайте рядок заголовків і зіставляйте за назвою або зафіксуйте заголовок.
• Надання доступу до таблиці ширше, ніж потрібно. «Будь-хто з посиланням» робить її публічною.
• Використання таблиці як багатокористувацької бази даних. Одночасні записи та відсутні права призводять до втрати або витоку даних.

Контрольний список

• Sheets API увімкнено; service account створено
• Таблиці надано доступ для email service account з мінімально потрібною роллю
• Ключ і ID таблиці збережено як секрети на сервері
• Усі виклики здійснюються з сервера
• У діапазонах використовуються назви вкладок
• Для тексту, введеного користувачами, використовується RAW
• Читання кешуються; 429 обробляється з затримкою
• Застосунок коректно працює, якщо Sheets недоступний
• Визначено, яка сторона є джерелом істини

Google Sheets у Mythex

У Mythex є два різні способи працювати з Sheets. Конектори пов'язують ваш обліковий запис Google з Mythex, щоб агент міг ним користуватися під час створення, наприклад, читати таблицю, щоб побудувати з неї дашборд. За документацією, облікові дані зберігаються у сервісі підключень Mythex і ніколи не потрапляють у ваш код (див. Connectors; схвалюйте кожен дозвіл, який запитує Google). Щоб опублікований застосунок сам читав чи записував таблицю, надійний шлях — той, що описано в цьому гіді: ключ service account, збережений як секрет проєкту, і виклики Sheets API з вашого сервера, як у Integrate any API. Якщо таблиця вже не справляється, попросіть агента перенести дані в базу даних проєкту та побудувати на ній дашборд.

Запитання