Gmail API مشمول محدودیت‌های استفاده است که نرخ فراخوانی روش‌های API را محدود می‌کند. محدودیت‌ها براساس واحدهای سهمیه تعریف می‌شوند که واحد اندازه‌گیری انتزاعی نشان‌دهنده استفاده از منابع Gmail است.
سهمیه‌های Gmail API
Gmail API دو نوع سهمیه را اعمال می‌کند:
در دقیقه برای هر پروژه: این تعداد واحدهای سهمیه‌ای است که پروژه Google Cloud شما می‌تواند در یک دقیقه استفاده کند.
در دقیقه برای هر کاربر برای هر پروژه: این تعداد واحدهای سهمیه‌ای است که هر کاربر خاص می‌تواند در پروژه Cloud شما استفاده کند. این محدودیت کمک می‌کند توزیع عادلانه‌ای از استفاده بین کاربران شما تضمین شود.
جدول زیر جزئیات این محدودیت‌ها را نشان می‌دهد:
| نوع حد استفاده | حد |
|---|---|
| در دقیقه برای هر پروژه | ۱٬۲۰۰٬۰۰۰ واحد سهمیه |
| در دقیقه برای هر کاربر برای هر پروژه | ۶٬۰۰۰ واحد سهمیه |
برای اطلاعات درباره رسیدگی به خطاهای محدودیت، به حل کردن خطاها مراجعه کنید.
آستانه صورت‌حساب روزانه
این حد روزانه برای هر پروژه حداکثر تعداد واحدهای سهمیه‌ای را که پروژه Google Cloud شما می‌تواند در یک دوره ۲۴ ساعته قبل‌از اعمال هزینه‌ها استفاده کند تعریف می‌کند.
استفاده کمتر از این آستانه هزینه اضافی ندارد و برای حساب Google Cloud شما صورت‌حساب صادر نمی‌شود. Google جزئیات کامل صورت‌حساب را در اواخر سال ۲۰۲۶ و حداقل ۹۰ روز قبل‌از اعمال هرگونه تغییر اعلام خواهد کرد.
نمی‌توانید برای این حد آستانه روزانه درخواست افزایش دهید.
جدول زیر جزئیات این محدودیت را نشان می‌دهد:
| نوع حد آستانه | حد |
|---|---|
| در روز برای هر پروژه | ۸۰٬۰۰۰٬۰۰۰ واحد سهمیه |
برای اطلاعات بیشتر، مدل استانداردشده Google Workspace برای ابزارها و میاناهای برنامه‌سازی کاربردی نماینده را ببینید.
مصرف سهمیه به‌ازای هر روش
تعداد واحدهای سهمیه‌ای که هر درخواست مصرف می‌کند بسته به روشی که فراخوانی می‌کنید و پارامترهای پُرسمان متفاوت است. جدول زیر میزان استفاده از واحد سهمیه را برای هر روش نشان می‌دهد:
| روش | واحدهای سهمیه |
|---|---|
drafts.create |
10 |
drafts.delete |
10 |
drafts.get |
۲۰ (۶۰ وقتی format برابر با full، raw، یا html باشد) |
drafts.list |
5 |
drafts.send |
100 |
drafts.update |
15 |
getProfile |
1 |
history.list |
2 |
labels.create |
۵ |
labels.delete |
5 |
labels.get |
1 |
labels.list |
1 |
labels.update |
5 |
messages.attachments.get |
20 |
messages.batchDelete |
50 |
messages.batchModify |
50 |
messages.delete |
10 |
messages.get |
۲۰ (۶۰ وقتی format برابر با full، raw، یا html باشد) |
messages.import |
25 |
messages.insert |
25 |
messages.list |
5 |
messages.modify |
5 |
messages.send |
100 |
messages.trash |
20 |
messages.untrash |
5 |
settings.delegates.create |
100 |
settings.delegates.delete |
5 |
settings.delegates.get |
1 |
settings.delegates.list |
1 |
settings.filters.create |
5 |
settings.filters.delete |
5 |
settings.filters.get |
1 |
settings.filters.list |
1 |
settings.forwardingAddresses.create |
100 |
settings.forwardingAddresses.delete |
5 |
settings.forwardingAddresses.get |
1 |
settings.forwardingAddresses.list |
1 |
settings.getAutoForwarding |
1 |
settings.getImap |
1 |
settings.getPop |
1 |
settings.getVacation |
1 |
settings.sendAs.create |
100 |
settings.sendAs.delete |
5 |
settings.sendAs.get |
1 |
settings.sendAs.list |
1 |
settings.sendAs.update |
100 |
settings.sendAs.verify |
100 |
settings.updateAutoForwarding |
5 |
settings.updateImap |
5 |
settings.updatePop |
100 |
settings.updateVacation |
5 |
stop |
50 |
threads.delete |
20 |
threads.get |
۴۰ (۱۲۰ وقتی format full است) |
threads.list |
10 |
threads.modify |
10 |
threads.trash |
20 |
threads.untrash |
10 |
watch |
100 |
هنگام استفاده از Gmail API، حد مجاز ۵۰۰ گیرنده برای هر پیام ایمیل نیز وجود دارد.
حل کردن خطاهای سهمیه مبتنی بر زمان
برای همه خطاهای مبتنی بر زمان (حداکثر N درخواست در هر X دقیقه)، توصیه می‌کنیم کد شما استثنا را بگیرد و از عقب‌نشینی نمایی کوتاه استفاده کند تا مطمئن شوید دستگاه‌هایتان بار اضافی تولید نمی‌کنند.
عقب‌نشینی نمایی یک استراتژی استاندارد مدیریت خطا برای برنامه‌های شبکه است. الگوریتم عقب‌گرد نمایی درخواست‌ها را بااستفاده از زمان‌های انتظار افزایشی نمایی بین درخواست‌ها، تا حداکثر زمان عقب‌گرد، دوباره امتحان می‌کند. اگر درخواست‌ها همچنان ناموفق بود، مهم است که تأخیر بین درخواست‌ها به‌مرور زمان افزایش یابد تا درخواست موفق شود.
الگوریتم نمونه
الگوریتم عقب‌گرد نمایی درخواست‌ها را به‌صورت نمایی امتحان مجدد می‌کند و زمان انتظار بین امتحان‌های مجدد را تا حداکثر زمان عقب‌گرد افزایش می‌دهد. برای مثال:
- درخواستی به Gmail API ارسال کنید.
- اگر درخواست ناموفق بود،
random_number_milliseconds+ ۱ صبر کنید و درخواست را دوباره امتحان کنید. - اگر درخواست ناموفق بود،
random_number_milliseconds+ ۲ صبر کنید و درخواست را دوباره امتحان کنید. - اگر درخواست ناموفق بود،
random_number_milliseconds+ ۴ صبر کنید و درخواست را دوباره امتحان کنید. - و به همین ترتیب، تا
maximum_backoffبار. - به منتظر ماندن و امتحان مجدد تا حداکثر تعداد دفعات امتحان مجاز ادامه دهید، اما دوره انتظار بین دفعات امتحان مجدد را افزایش ندهید.
مکان:
- زمان انتظار
min(((2^n)+random_number_milliseconds), maximum_backoff)است، وnبرای هر تکرار (درخواست) ۱ عدد افزایش می‌یابد. -
random_number_millisecondsعدد تصادفی از میلی‌ثانیه‌های کمتر یا مساوی با ۱۰۰۰ است. این کار کمک می‌کند از مواردی که در آن بسیاری از کارخواه‌ها به‌دلیل شرایطی همگام‌سازی می‌شوند و همه به‌طور هم‌زمان دوباره امتحان می‌کنند و درخواست‌ها را در موج‌های همگام‌سازی‌شده ارسال می‌کنند، جلوگیری شود. مقدارrandom_number_millisecondsپس‌از هر درخواست تکرار مجدد دوباره محاسبه می‌شود. maximum_backoffمعمولاً ۳۲ یا ۶۴ ثانیه است. مقدار مناسب به مورد استفاده بستگی دارد.
کارخواه می‌تواند پس‌از رسیدن به زمان maximum_backoff، به تلاش مجدد ادامه دهد.
تلاش‌های مجدد پس‌از این نقطه نیازی به ادامه افزایش زمان عقب‌نشینی ندارند. برای
مثال، اگر مشتری از زمان maximum_backoff ۶۴ ثانیه استفاده کند، پس‌از رسیدن به
این مقدار، مشتری می‌تواند هر ۶۴ ثانیه دوباره امتحان کند. در برخی‌از موارد،
باید از تلاش مجدد نامحدود کارخواه‌ها جلوگیری شود.
زمان انتظار بین تلاش‌های مجدد و تعداد تلاش‌های مجدد به مورد استفاده شما و شرایط شبکه بستگی دارد.
قیمت‌گذاری
همه استفاده‌های استاندارد از Gmail API بدون هزینه اضافی دردسترس است. فراتر رفتن از حدود درخواست سهمیه قرار است در اواخر سال ۲۰۲۶ برای حساب صورت‌حساب Google Cloud شما هزینه داشته باشد. برای اطلاعات بیشتر، مدل استانداردشده Google Workspace برای ابزارها و میاناهای برنامه‌سازی کاربردی نماینده را ببینید.
درخواست افزایش سهمیه
بسته به میزان استفاده از منابع پروژه‌تان، ممکن است بخواهید درخواست اصلاح سهمیه کنید. فراخوانی‌های API توسط حساب سرویس به‌عنوان استفاده از یک حساب واحد درنظر گرفته می‌شود. درخواست برای سهمیه اصلاح‌شده تضمینی برای تأیید نیست. درخواست‌های تعدیل سهمیه که مقدار سهمیه را به‌طور قابل‌توجهی افزایش می‌دهند ممکن است برای تأیید شدن به زمان بیشتری نیاز داشته باشند.
همه پروژه‌ها سهمیه‌های یکسانی ندارند. با گذشت زمان و افزایش استفاده شما از Google Cloud، ممکن است لازم باشد مقادیر سهمیه شما افزایش یابد. اگر انتظار دارید در آینده استفاده شما به‌طور قابل‌توجهی افزایش یابد، می‌توانید به‌طور پیش‌گیرانه از صفحه سهمیه‌ها و حدود سیستم در کنسول Google Cloud درخواست اصلاح سهمیه کنید.
برای اطلاعات بیشتر، منابع زیر را ببینید:
سهمیه‌های سرور MCP در Gmail
سرور MCP در Gmail از سنجه تخصیص هزینه پُرسمان استفاده می‌کند. جدول‌های زیر جزئیات هزینه پُرسمان را برای هر روش سرور «پروتکل زمینه مدل» Gmail براساس بخش نشان می‌دهد:
سهمیه‌های MCP در Gmail
سرور دو نوع سهمیه را اعمال می‌کند:
در دقیقه برای هر پروژه: این هزینه پُرسمان برای پروژه Cloud شما در یک دقیقه است.
در دقیقه برای هر کاربر در هر پروژه: این هزینه پُرسمان برای پروژه Cloud شما برای یک دقیقه است که هر کاربر خاص می‌تواند استفاده کند.
جدول زیر جزئیات این سهمیه‌ها را نشان می‌دهد:
| نوع حد استفاده | هزینه پُرسمان |
|---|---|
| در دقیقه برای هر پروژه | ۱٬۲۰۰٬۰۰۰ |
| در دقیقه برای هر کاربر برای هر پروژه | ۶٬۰۰۰ |
سهمیه‌های مجموعه ابزار MCP در Gmail
جدول زیر جزئیات هزینه پُرسمان را برای هر مجموعه ابزار gmailmcp.googleapis.com نشان می‌دهد:
| نقطه پایانی | ابزار | هزینه پُرسمان |
|---|---|---|
/mcp/v1 |
|
10 |
|
40 |
|
|
10 |
|
|
10 |
|
|
5 |
|
|
1 |
|
|
10 |
|
|
10 |
|
|
10 |
برای اطلاعات بیشتر، به مرجع Gmail MCP API مراجعه کنید.