API جیمیل مشمول محدودیتهای استفاده است که میزان فراخوانی متدهای API را محدود میکند. این محدودیتها بر اساس واحدهای سهمیهبندی تعریف میشوند، یک واحد انتزاعی اندازهگیری که نشاندهنده میزان استفاده از منابع جیمیل است.
سهمیههای API جیمیل
دو نوع سهمیه اعمال میشود:
در هر دقیقه به ازای هر پروژه: این تعداد واحدهای سهمیهای است که پروژه Google Cloud شما میتواند در یک دقیقه استفاده کند.
در هر دقیقه به ازای هر کاربر در هر پروژه: این تعداد واحدهای سهمیهای است که هر کاربر خاص میتواند در پروژه ابری شما استفاده کند. هدف این محدودیت کمک به شما در اطمینان از توزیع عادلانه استفاده بین کاربرانتان است.
جدول زیر جزئیات این محدودیتها را نشان میدهد:
| نوع محدودیت استفاده | حد |
|---|---|
| به ازای هر دقیقه برای هر پروژه | ۱،۲۰۰،۰۰۰ واحد سهمیهای |
| به ازای هر دقیقه به ازای هر کاربر در هر پروژه | ۶۰۰۰ واحد سهمیهای |
برای اطلاعات در مورد مدیریت خطاهای محدود، به رفع خطاها مراجعه کنید.
آستانه صورتحساب روزانه
این محدودیت در هر روز به ازای هر پروژه، حداکثر تعداد واحدهای سهمیهای را که پروژه Google Cloud شما میتواند در یک دوره 24 ساعته قبل از اعمال هزینهها استفاده کند، تعریف میکند.
استفاده کمتر از این حد مجاز، هزینه اضافی ندارد و از حساب گوگل کلود شما صورتحسابی دریافت نمیشود. جزئیات کامل صورتحساب در اواخر سال ۲۰۲۶ با حداقل ۹۰ روز اطلاعرسانی قبل از اعمال هرگونه تغییر، به اشتراک گذاشته خواهد شد.
شما نمیتوانید درخواست افزایش این محدودیت آستانه روزانه را بدهید.
جدول زیر جزئیات این محدودیت را نشان میدهد:
| نوع محدودیت آستانه | حد |
|---|---|
| به ازای هر روز برای هر پروژه | ۸۰،۰۰۰،۰۰۰ واحد سهمیهای |
برای اطلاعات بیشتر، به مدل استاندارد شدهی ابزارهای عامل و APIها در Google Workspace مراجعه کنید.
سهمیه استفاده به ازای هر متد
تعداد واحدهای سهمیه مصرف شده در هر درخواست بسته به متد فراخوانی شده متفاوت است. جدول زیر میزان استفاده از واحد سهمیه در هر متد را نشان میدهد:
| روش | واحدهای سهمیهای |
|---|---|
drafts.create | ۱۰ |
drafts.delete | ۱۰ |
drafts.get | ۲۰ |
drafts.list | ۵ |
drafts.send | ۱۰۰ |
drafts.update | ۱۵ |
getProfile | ۱ |
history.list | ۲ |
labels.create | ۵ |
labels.delete | ۵ |
labels.get | ۱ |
labels.list | ۱ |
labels.update | ۵ |
messages.attachments.get | ۲۰ |
messages.batchDelete | ۵۰ |
messages.batchModify | ۵۰ |
messages.delete | ۱۰ |
messages.get | ۲۰ |
messages.import | ۲۵ |
messages.insert | ۲۵ |
messages.list | ۵ |
messages.modify | ۵ |
messages.send | ۱۰۰ |
messages.trash | ۲۰ |
messages.untrash | ۵ |
settings.delegates.create | ۱۰۰ |
settings.delegates.delete | ۵ |
settings.delegates.get | ۱ |
settings.delegates.list | ۱ |
settings.filters.create | ۵ |
settings.filters.delete | ۵ |
settings.filters.get | ۱ |
settings.filters.list | ۱ |
settings.forwardingAddresses.create | ۱۰۰ |
settings.forwardingAddresses.delete | ۵ |
settings.forwardingAddresses.get | ۱ |
settings.forwardingAddresses.list | ۱ |
settings.getAutoForwarding | ۱ |
settings.getImap | ۱ |
settings.getPop | ۱ |
settings.getVacation | ۱ |
settings.sendAs.create | ۱۰۰ |
settings.sendAs.delete | ۵ |
settings.sendAs.get | ۱ |
settings.sendAs.list | ۱ |
settings.sendAs.update | ۱۰۰ |
settings.sendAs.verify | ۱۰۰ |
settings.updateAutoForwarding | ۵ |
settings.updateImap | ۵ |
settings.updatePop | ۱۰۰ |
settings.updateVacation | ۵ |
stop | ۵۰ |
threads.delete | ۲۰ |
threads.get | ۴۰ |
threads.list | ۱۰ |
threads.modify | ۱۰ |
threads.trash | ۲۰ |
threads.untrash | ۱۰ |
watch | ۱۰۰ |
هنگام استفاده از Gmail API، محدودیت ۵۰۰ گیرنده برای هر پیام ایمیل نیز وجود دارد.
خطاهای سهمیهبندی مبتنی بر زمان را برطرف کنید
برای همه خطاهای مبتنی بر زمان (حداکثر N درخواست در هر X دقیقه)، توصیه میکنیم کد شما استثنا را دریافت کند و از یک backoff نمایی کوتاه شده استفاده کند تا مطمئن شود دستگاههای شما بار اضافی تولید نمیکنند.
بازگشت نمایی یک استراتژی استاندارد مدیریت خطا برای برنامههای شبکه است. یک الگوریتم بازگشت نمایی، درخواستها را با استفاده از زمان انتظار بین درخواستها که به صورت نمایی افزایش مییابد، تا حداکثر زمان بازگشت، دوباره امتحان میکند. اگر درخواستها همچنان ناموفق باشند، مهم است که تأخیر بین درخواستها به مرور زمان افزایش یابد تا درخواست موفقیتآمیز شود.
الگوریتم مثال
یک الگوریتم بازگشت نمایی، درخواستها را به صورت نمایی دوباره امتحان میکند و زمان انتظار بین تلاشهای مجدد را تا حداکثر زمان بازگشت افزایش میدهد. برای مثال:
- یک درخواست به Gmail 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 برابر با ۶۴ ثانیه استفاده کند، پس از رسیدن به این مقدار، کلاینت میتواند هر ۶۴ ثانیه دوباره تلاش کند. در مقطعی، کلاینتها باید از تلاش مجدد نامحدود منع شوند.
زمان انتظار بین تلاشهای مجدد و تعداد تلاشهای مجدد به مورد استفاده شما و شرایط شبکه بستگی دارد.
قیمتگذاری
تمام استفادههای استاندارد از Gmail API بدون هیچ هزینه اضافی در دسترس است. تجاوز از محدودیتهای درخواست سهمیه، هزینههایی را برای حساب صورتحساب Google Cloud شما در اواخر سال 2026 به همراه خواهد داشت. برای اطلاعات بیشتر، به مدل استاندارد Google Workspace برای ابزارها و APIهای عامل مراجعه کنید.
درخواست افزایش سهمیه
بسته به میزان استفاده از منابع پروژهتان، ممکن است بخواهید درخواست تنظیم سهمیه بدهید. فراخوانیهای API توسط یک حساب کاربری سرویس، به عنوان استفاده از یک حساب کاربری واحد در نظر گرفته میشوند. درخواست برای سهمیه تنظیمشده، تضمینی برای تأیید نیست. درخواستهای تنظیم سهمیه که مقدار سهمیه را به میزان قابل توجهی افزایش میدهند، ممکن است مدت زمان بیشتری طول بکشد تا تأیید شوند.
همه پروژهها سهمیههای یکسانی ندارند. با گذشت زمان و افزایش استفاده از گوگل کلود، ممکن است لازم باشد مقادیر سهمیه شما افزایش یابد. اگر انتظار افزایش قابل توجه استفاده در آینده را دارید، میتوانید به صورت پیشگیرانه از صفحه سهمیهها و محدودیتهای سیستم در کنسول گوگل کلود، درخواست تنظیم سهمیه کنید .
برای مطالعه بیشتر، به منابع زیر مراجعه کنید: