رابط برنامهنویسی کاربردی گوگل شیت یک سرویس اشتراکی است و ما سهمیهها و محدودیتهایی را برای محافظت از عملکرد کلی سیستم گوگل ورکاسپیس برای همه کاربران اعمال میکنیم.
محدودیتهای سهمیه
اگرچه Sheets API هیچ محدودیت اندازهی مشخصی برای درخواست API ندارد، اما کاربران ممکن است با محدودیتهایی از جانب اجزای پردازشی مختلف که توسط Google Sheets کنترل نمیشوند، مواجه شوند. برای سرعت بخشیدن به درخواستها، حداکثر حجم مجاز ۲ مگابایت را توصیه میکنیم.
API صفحات سهمیهبندی دقیقهای دارد و هر دقیقه دوباره پر میشود. برای مثال، محدودیت درخواست خواندن ۳۰۰ درخواست در دقیقه برای هر پروژه وجود دارد. اگر برنامه شما ۳۵۰ درخواست در یک دقیقه ارسال کند، ۵۰ درخواست اضافی از سهمیه تجاوز کرده و پاسخ کد وضعیت HTTP با 429: Too many requests ایجاد میکند. اگر این اتفاق بیفتد، باید از یک الگوریتم backoff نمایی استفاده کنید. پس از ۱ دقیقه، میتوانید دوباره درخواستها را اجرا کنید.
جدول زیر جزئیات محدودیتهای درخواست را نشان میدهد:
| سهمیهها | |||||
|---|---|---|---|---|---|
| درخواستهای خواندن |
| ||||
| درخواستها را بنویسید |
| ||||
برای جزئیات بیشتر در مورد محدودیتهای فایل، به فایلهایی که میتوانید در گوگل درایو ذخیره کنید مراجعه کنید.
رفتار و محدودیتها
هنگام کار با ((sheets_api_short))، به رفتار و محدودیتهای زیر که بر سهمیههای شما تأثیر میگذارند، توجه کنید:
درخواستهای خواندن، فراخوانیهایی به هر متدی هستند که دادهها را از یک صفحه گسترده بازیابی میکند، مانند
getیاsearch. درخواستهای نوشتن، فراخوانیهایی به هر متدی هستند که یک صفحه گسترده را تغییر میدهد، مانندupdate،clearیاcopyTo.کاربران میتوانند چندین درخواست را همزمان ارسال کنند، البته تا زمانی که در محدوده سهمیه باشند. هر درخواست دستهای ، شامل هر زیر درخواست، به عنوان یک درخواست API در محدوده استفاده شما محاسبه میشود.
تمام درخواستهای Sheets به صورت اتمیک اعمال میشوند. یعنی اگر هر درخواستی معتبر نباشد، کل بهروزرسانی ناموفق است و هیچ یک از تغییرات (که به طور بالقوه وابسته هستند) اعمال نمیشوند.
حداکثر زمان پردازش یک درخواست API محدود است. وقتی Sheets یک درخواست را بیش از ۱۸۰ ثانیه پردازش کند، درخواست خطای timeout (پایان زمان) را برمیگرداند.
مشروط بر اینکه در محدوده سهمیه هر دقیقه بمانید، هیچ محدودیتی برای تعداد درخواستهایی که میتوانید در روز انجام دهید وجود ندارد.
خطاهای سهمیهبندی مبتنی بر زمان را برطرف کنید
برای همه خطاهای مبتنی بر زمان (حداکثر N درخواست در هر X دقیقه)، توصیه میکنیم کد شما استثنا را دریافت کند و از یک backoff نمایی کوتاه شده استفاده کند تا مطمئن شود دستگاههای شما بار اضافی تولید نمیکنند.
بازگشت نمایی یک استراتژی استاندارد مدیریت خطا برای برنامههای شبکه است. یک الگوریتم بازگشت نمایی، درخواستها را با استفاده از زمان انتظار بین درخواستها که به صورت نمایی افزایش مییابد، تا حداکثر زمان بازگشت، دوباره امتحان میکند. اگر درخواستها همچنان ناموفق باشند، مهم است که تأخیر بین درخواستها به مرور زمان افزایش یابد تا درخواست موفقیتآمیز شود.
الگوریتم مثال
یک الگوریتم بازگشت نمایی، درخواستها را به صورت نمایی دوباره امتحان میکند و زمان انتظار بین تلاشهای مجدد را تا حداکثر زمان بازگشت افزایش میدهد. برای مثال:
- یک درخواست به API گوگل شیت ارسال کنید.
- اگر درخواست با شکست مواجه شد، ۱ +
random_number_millisecondsصبر کنید و درخواست را دوباره امتحان کنید. - اگر درخواست با شکست مواجه شد، به مدت ۲ +
random_number_millisecondsصبر کنید و درخواست را دوباره امتحان کنید. - اگر درخواست با شکست مواجه شد، به مدت ۴ +
random_number_millisecondsصبر کنید و درخواست را دوباره امتحان کنید. - و به همین ترتیب، تا زمان
maximum_backoff. - تا حداکثر تعداد دفعات تلاش مجدد، به انتظار و تلاش مجدد ادامه دهید، اما مدت زمان انتظار بین تلاشها را افزایش ندهید.
کجا:
- زمان انتظار
min(((2^n)+random_number_milliseconds), maximum_backoff)است، که در آنnبرای هر تکرار (درخواست) 1 واحد افزایش مییابد. -
random_number_millisecondsیک عدد تصادفی میلیثانیه کمتر یا مساوی ۱۰۰۰ است. این به جلوگیری از مواردی که بسیاری از کلاینتها به دلیل برخی شرایط همگامسازی میشوند و همه به طور همزمان تلاش مجدد میکنند و درخواستها را در امواج هماهنگ ارسال میکنند، کمک میکند. مقدارrandom_number_millisecondsپس از هر درخواست تلاش مجدد دوباره محاسبه میشود. -
maximum_backoffمعمولاً ۳۲ یا ۶۴ ثانیه است. مقدار مناسب به مورد استفاده بستگی دارد.
کلاینت میتواند پس از رسیدن به زمان maximum_backoff به تلاش مجدد ادامه دهد. تلاشهای مجدد پس از این نقطه نیازی به افزایش مداوم زمان backoff ندارند. برای مثال، اگر یک کلاینت از زمان maximum_backoff برابر با ۶۴ ثانیه استفاده کند، پس از رسیدن به این مقدار، کلاینت میتواند هر ۶۴ ثانیه دوباره تلاش کند. در مقطعی، کلاینتها باید از تلاش مجدد نامحدود منع شوند.
زمان انتظار بین تلاشهای مجدد و تعداد تلاشهای مجدد به مورد استفاده شما و شرایط شبکه بستگی دارد.
قیمتگذاری
تمام استفاده از API گوگل شیت بدون هیچ هزینه اضافی در دسترس است. تجاوز از محدودیت درخواست سهمیه، هزینه اضافی ندارد و از حساب شما صورتحسابی کسر نمیشود.
درخواست افزایش سهمیه
بسته به میزان استفاده از منابع پروژهتان، ممکن است بخواهید درخواست تنظیم سهمیه بدهید. فراخوانیهای API توسط یک حساب کاربری سرویس، به عنوان استفاده از یک حساب کاربری واحد در نظر گرفته میشوند. درخواست برای سهمیه تنظیمشده، تضمینی برای تأیید نیست. درخواستهای تنظیم سهمیه که مقدار سهمیه را به میزان قابل توجهی افزایش میدهند، ممکن است مدت زمان بیشتری طول بکشد تا تأیید شوند.
همه پروژهها سهمیههای یکسانی ندارند. با گذشت زمان و افزایش استفاده از گوگل کلود، ممکن است لازم باشد مقادیر سهمیه شما افزایش یابد. اگر انتظار افزایش قابل توجه استفاده در آینده را دارید، میتوانید به صورت پیشگیرانه از صفحه سهمیهها در کنسول گوگل کلود، درخواست تنظیم سهمیه کنید .
برای مطالعه بیشتر، به منابع زیر مراجعه کنید:
- درباره تعدیل سهمیهها
- مشاهده میزان استفاده و محدودیتهای سهمیه فعلی شما
- درخواست محدودیت سهمیه بالاتر