چطور Google Sheets را به اپلیکیشنتان وصل کنیم
برای وصل کردن Google Sheets به اپتان، Google Sheets API را در یک پروژه Google Cloud فعال کنید، یک سرویس اکانت بسازید، اسپریدشیت را با نشانی ایمیل سرویس اکانت به اشتراک بگذارید، و کلیدش را به‌عنوان یک secret سمت سرور ذخیره کنید. سپس سرور شما ردیف‌ها را با spreadsheets.values.get می‌خواند و با spreadsheets.values.append ردیف اضافه می‌کند. اگر کاربران باید شیت‌های خودشان را وصل کنند، از OAuth استفاده کنید؛ و اگر شیت کاملاً عمومی است، برای خواندن یک کلید API ساده کافی است.
این راهنما مشخص می‌کند کدام روش مناسب است، فراخوانی‌هایی که لازم دارید، سهمیه‌ها و نکات مهم، و پرامپت‌هایی برای ابزار ساخت اپ با هوش مصنوعی. جزئیات گوگل از مستندات توسعه‌دهنده گوگل تا سپتامبر ۲۰۲۶ گرفته شده‌اند.
چرا اصلاً یک شیت را وصل کنیم
دلایل رایج:
- حفظ روال کار تیم. کارکنان به ویرایش فهرست قیمت یا برنامه در Sheets ادامه می‌دهند؛ اپ آن را نشان می‌دهد.
- جمع‌آوری داده در جایی که مردم از قبل نگاه می‌کنند. ثبت‌نام‌های جدید، سفارش‌ها یا پاسخ‌های فرم به‌صورت ردیف وارد می‌شوند.
- گزارش‌گیری. داده اپ را برای افرادی که با اسپریدشیت کار می‌کنند به یک شیت خروجی بگیرید.
- یک مرحله میانی. از شیت شروع کنید، سپس به یک پایگاه داده درست منتقل شوید. چطور یک اسپریدشیت را به اپ تبدیل کنیم را ببینید.
انتخاب روش ورود اپ به Google
راهنمای اعتبارنامه‌های Google سه نوع را شرح می‌دهد:
| اعتبارنامه | به چه چیزی دسترسی دارد | بهترین کاربرد |
|---|---|---|
| کلید API | فقط داده‌های عمومی، مثل فایل‌هایی که با «هر کسی که لینک را دارد» به اشتراک گذاشته شده‌اند | خواندن یک شیت عمومی |
| سرویس اکانت | داده‌ای که متعلق به اپ شماست، یا فایل‌های مشخصی که با ایمیل سرویس اکانت به اشتراک گذاشته شده‌اند | اپ شما که شیت‌های خودتان را می‌خواند و می‌نویسد |
| OAuth client ID | فایل‌های شخصی کاربر، پس از رضایت او | اجازه دادن به هر کاربر برای وصل کردن شیت‌های خودش |
برای بیشتر اپ‌ها، سرویس اکانت انتخاب درستی است: یک مجموعه اعتبارنامه که متعلق به خودتان است و فقط به شیت‌هایی دسترسی دارد که صریحاً با آن به اشتراک گذاشته‌اید.
راهنمای گام‌به‌گام با سرویس اکانت
- یک پروژه Google Cloud بسازید یا انتخاب کنید و Google Sheets API را فعال کنید.
- یک سرویس اکانت و کلید برای آن بسازید. کلید یک فایل JSON است؛ آن را مثل رمز عبور نگه دارید.
- اسپریدشیت را با نشانی ایمیل سرویس اکانت به اشتراک بگذارید، به‌صورت Viewer برای فقط‌خواندن یا Editor برای نوشتن. راهنمای گوگل می‌گوید این کار از طریق صفحه معمول اشتراک‌گذاری انجام می‌شود.
- کلید را به‌عنوان secret روی سرور ذخیره کنید، مثلاً
GOOGLE_SERVICE_ACCOUNT_JSON، همراه با شناسه اسپریدشیت (رشته بلندی که در نشانی شیت است) به‌عنوانSHEET_ID. - API را از سرور با کتابخانه کلاینت گوگل برای زبان برنامه‌نویسی‌تان فراخوانی کنید.
- خواندن‌ها را کَش کنید اگر بازدیدکنندگان زیادی داده یکسان را می‌بینند، تا به سهمیه نخورید.
فراخوانی‌هایی که استفاده می‌کنید
از راهنمای گوگل برای خواندن و نوشتن مقادیر:
| متد | کاری که انجام می‌دهد |
|---|---|
spreadsheets.values.get | یک محدوده را می‌خواند، مثل Leads!A1:E |
spreadsheets.values.batchGet | چند محدوده را در یک درخواست می‌خواند |
spreadsheets.values.update | در یک محدوده مشخص می‌نویسد |
spreadsheets.values.append | ردیف‌ها را بعد از داده‌های موجود در یک جدول اضافه می‌کند |
محدوده‌ها با نماد A1 نوشته می‌شوند. گوگل اشاره می‌کند که محدوده‌ای بدون نام شیت، مثل A1:B2، روی اولین شیت اعمال می‌شود، پس نام برگه را صریحاً بنویسید تا وقتی کسی ترتیب برگه‌ها را عوض می‌کند غافلگیر نشوید.
RAW در برابر USER_ENTERED
نوشتن‌ها به valueInputOption نیاز دارند:
- RAW دقیقاً همان چیزی را که می‌فرستید، به‌صورت متن ذخیره می‌کند.
=1+2به‌صورت متن=1+2ذخیره می‌شود. - USER_ENTERED ورودی را طوری در نظر می‌گیرد که انگار در Sheets تایپ شده: تاریخ‌ها تاریخ می‌شوند و
=1+2یک فرمول می‌شود.
اگر متنی را می‌نویسید که کاربران در اپ تایپ کرده‌اند، از RAW استفاده کنید. با USER_ENTERED، کسی می‌تواند یک فرمول بفرستد که وقتی همکارش شیت را باز می‌کند اجرا شود.
سهمیه‌ها و خطاها
از سپتامبر ۲۰۲۶، صفحه محدودیت‌های Sheets API گوگل این‌ها را فهرست کرده است:
| محدودیت | درخواست‌های خواندن | درخواست‌های نوشتن |
|---|---|---|
| در دقیقه برای هر پروژه | ۳۰۰ | ۳۰۰ |
| در دقیقه برای هر کاربر در هر پروژه | ۶۰ | ۶۰ |
تا وقتی در سهمیه‌های دقیقه‌ای بمانید، محدودیت روزانه‌ای وجود ندارد. عبور از آن خطای 429: Too many requests برمی‌گرداند، و گوگل تأخیر نمایی کوتاه‌شده را توصیه می‌کند: بعد از هر تلاش ناموفق بیشتر صبر کنید، با یک تأخیر تصادفی، تا یک حد بیشینه. یک درخواست منفرد که بیش از ۱۸۰ ثانیه طول بکشد timeout می‌شود.
در عمل: هر بار صفحه‌ای باز می‌شود API را صدا نزنید. داده شیت را یک دقیقه یا بیشتر کَش کنید، خواندن‌ها را با batchGet دسته‌ای کنید، و جایی که ممکن است نوشتن‌ها را دسته‌ای کنید.
گزینه‌ها و مبادلات
| روش | مزایا | معایب |
|---|---|---|
| شیت به‌عنوان منبع زنده داده | کارکنان در ابزار آشنا ویرایش می‌کنند؛ صفحه مدیریتی لازم نیست ساخته شود | سهمیه‌ها، نبود دسترسی جداگانه برای هر ردیف، و خراب شدن آسان با تغییر نام یک ستون |
| همگام‌سازی شیت با پایگاه داده | خواندن سریع و قابل‌اعتماد؛ اگر Sheets خراب شود اپ کار می‌کند | به یک کار همگام‌سازی و یک قانون برای اینکه کدام طرف برنده است نیاز دارید |
| پایگاه داده اول، خروجی به شیت | اپ داده را مالک است؛ شیت یک گزارش است | ویرایش‌های داخل شیت به اپ برنمی‌گردد |
| ابزار اتوماسیون میانی | برای جریان‌های ساده بدون کد | یک اشتراک دیگر؛ اشکال‌زدایی سخت‌تر |
برای هر چیزی با کاربران زیاد یا داده حساس، پایگاه داده منبع قابل‌اعتمادتر است. پایگاه داده چیست را ببینید.
پرامپت‌هایی برای ابزار ساخت با هوش مصنوعی
خواندن یک شیت:
تب «Menu» شیت گوگلمان را در صفحه منو نمایش بده. Google Sheets API را از سرور با یک سرویس اکانت استفاده کن که کلید JSON آن در secret با نام GOOGLE_SERVICE_ACCOUNT_JSON است، و شناسه اسپریدشیت در SHEET_ID. محدوده Menu!A2:D را بخوان (نام، توضیح، قیمت، دسته). نتیجه را ۵ دقیقه کَش کن. اگر API خطا داد، آخرین نسخه کَش‌شده را نشان بده. هرگز کلید را به مرورگر نفرست.
نوشتن ردیف‌ها:
وقتی کسی فرم تماس را ارسال می‌کند، آن را در پایگاه داده ذخیره کن و همچنین با spreadsheets.values.append با valueInputOption برابر RAW یک ردیف به تب «Leads» اضافه کن (تاریخ، نام، ایمیل، پیام). اگر گوگل 429 برگرداند، با تأخیر نمایی دوباره تلاش کن؛ اگر باز هم شکست خورد، سرنخ را در پایگاه داده نگه دار و بعداً دوباره تلاش کن.
اشتباه‌های رایج
- فراموش کردن اشتراک شیت با ایمیل سرویس اکانت. در این صورت API خطای دسترسی می‌دهد، حتی اگر کلید درست باشد.
- کلید در فرانت‌اند یا مخزن کد. کلید JSON به هر شیتی که با آن به اشتراک گذاشته شده دسترسی می‌دهد. چطور کلیدهای API را ایمن نگه داریم را ببینید.
- استفاده از USER_ENTERED برای ورودی کاربر، که تزریق فرمول را ممکن می‌کند.
- صدا زدن API در هر درخواست و رسیدن به سهمیه دقیقه‌ای در اولین اوج ترافیک.
- وابسته بودن به موقعیت ستون‌ها. کسی یک ستون اضافه می‌کند و اپ داده اشتباه را می‌خواند. ردیف سرصفحه را بخوانید و بر اساس نام نگاشت کنید، یا سرصفحه را قفل کنید.
- اشتراک‌گذاری شیت گسترده‌تر از نیاز. «هر کسی که لینک را دارد» آن را عمومی می‌کند.
- استفاده از شیت به‌عنوان پایگاه داده چندکاربره. نوشتن‌های همزمان و نبود دسترسی باعث از دست رفتن یا نشت داده می‌شود.
چک‌لیست
- Sheets API فعال و سرویس اکانت ساخته شده است
- شیت با ایمیل سرویس اکانت و با پایین‌ترین نقش لازم به اشتراک گذاشته شده
- کلید و شناسه شیت به‌عنوان secret سمت سرور ذخیره شده‌اند
- همه فراخوانی‌ها از سرور انجام می‌شوند
- نام برگه‌ها در محدوده‌ها استفاده شده‌اند
- برای متن ارسالی کاربر از RAW استفاده شده
- خواندن‌ها کَش شده‌اند و 429 با تأخیر مدیریت می‌شود
- اپ اگر Sheets در دسترس نباشد به‌درستی کار می‌کند
- تصمیم گرفته شده کدام طرف منبع حقیقت است
Google Sheets در Mythex
Mythex دو راه متفاوت برای کار با Sheets دارد. Connectors حساب Google شما را به Mythex وصل می‌کنند تا عامل هنگام ساخت بتواند از آن استفاده کند، مثلاً خواندن یک شیت برای ساختن داشبورد از روی آن. مستندات می‌گویند اعتبارنامه نزد سرویس اتصال Mythex می‌ماند و هرگز وارد کد شما نمی‌شود (بخش Connectors را ببینید، و هر دسترسی‌ای را که گوگل می‌خواهد تأیید کنید). برای اینکه اپ منتشرشده خودش بتواند شیتی را بخواند یا بنویسد، روش قابل‌اعتماد همان چیزی است که در این راهنما آمده: یک کلید سرویس اکانت به‌عنوان secret پروژه ذخیره می‌شود و فراخوانی‌های Sheets API از سرور شما انجام می‌شوند، مثل ادغام هر API. اگر از شیت فراتر رفته‌اید، از عامل بخواهید داده را به پایگاه داده پروژه منتقل کند و یک داشبورد روی آن بسازد.
پرسش‌ها
اپ من چطور می‌تواند یک Google Sheet خصوصی را بخواند؟
روش معمول استفاده از سرویس اکانت Google Cloud است: Sheets API را فعال کنید، سرویس اکانت و کلیدش را بسازید، و سپس اسپریدشیت را با نشانی ایمیل سرویس اکانت به‌عنوان Viewer یا Editor به اشتراک بگذارید. سرور شما با استفاده از کلید، که به‌عنوان secret ذخیره شده، Sheets API را فراخوانی می‌کند.
آیا می‌توانم برای دسترسی به یک اسپریدشیت از کلید API گوگل استفاده کنم؟
فقط برای داده‌های عمومی. راهنمای اعتبارنامه‌های Google می‌گوید کلیدهای API برای دسترسی ناشناس به داده‌های عمومی‌اند، مثل فایل‌هایی که با هر کسی که لینک را دارد به اشتراک گذاشته شده‌اند. شیت‌های خصوصی به سرویس اکانت یا OAuth نیاز دارند.
محدودیت‌های Google Sheets API چیست؟
از سپتامبر ۲۰۲۶، گوگل ۳۰۰ درخواست خواندن و ۳۰۰ درخواست نوشتن در دقیقه برای هر پروژه، و ۶۰ مورد از هرکدام در دقیقه برای هر کاربر در هر پروژه را اعلام می‌کند، بدون محدودیت روزانه. عبور از این حدود خطای 429 برمی‌گرداند؛ گوگل تأخیر نمایی کوتاه‌شده (truncated exponential backoff) را توصیه می‌کند.
آیا باید از Google Sheets به‌عنوان پایگاه داده اپم استفاده کنم؟
برای اپ‌های کوچک و کم‌ترافیک که افراد داده را در خود شیت هم ویرایش می‌کنند، کار می‌کند. برای کاربران زیاد، نوشتن‌های مکرر، ارتباط بین رکوردها یا دسترسی‌های جداگانه برای هر کاربر، یک پایگاه داده واقعی قابل‌اعتمادتر است، و همچنان می‌توانید داده را به یک شیت خروجی بگیرید.