API تقویم گوگل سهمیهبندیهایی دارد تا اطمینان حاصل شود که همه کاربران به طور منصفانه از آن استفاده میکنند. هنگام استفاده از API تقویم، سه محدودیت مهم را در نظر بگیرید:
سهمیه استفاده از API : به ازای هر پروژه و هر کاربر اعمال میشود. برای اطلاعات بیشتر، به انواع سهمیه استفاده از API تقویم مراجعه کنید.
محدودیتهای عمومی استفاده از تقویم : API تقویم یک سرویس اشتراکی است که محدودیتهایی برای محافظت از عملکرد کلی سیستم Google Workspace دارد. برای اطلاعات بیشتر، به بخش «اجتناب از محدودیتهای استفاده از تقویم» مراجعه کنید.
محدودیتهای عملیاتی : این محدودیتها ممکن است در هر زمانی اعمال شوند. برای مثال، اگر سعی کنید پشت سر هم و سریع در یک تقویم بنویسید، ممکن است محدودیتهایی اعمال شود.
سهمیههای API تقویم
دو نوع سهمیه اعمال میشود:
در هر دقیقه برای هر پروژه: این تعداد درخواستهایی است که پروژه Google Cloud شما میتواند در یک دقیقه انجام دهد.
در هر دقیقه به ازای هر کاربر در هر پروژه: این تعداد درخواستهایی است که هر کاربر خاص میتواند در پروژه ابری شما انجام دهد. این محدودیت به تضمین توزیع عادلانه استفاده بین کاربران شما کمک میکند.
سهمیهها با استفاده از یک پنجره کشویی در هر دقیقه محاسبه میشوند. افزایش سریع ترافیک که از سهمیه شما در هر دقیقه بیشتر شود، منجر به محدود کردن نرخ در طول پنجره بعدی میشود تا اطمینان حاصل شود که به طور متوسط، میزان استفاده شما در محدوده سهمیه باقی میماند.
جدول زیر جزئیات این محدودیتها را نشان میدهد:
| نوع محدودیت استفاده | حد |
|---|---|
| به ازای هر دقیقه برای هر پروژه | ۱۰،۰۰۰ درخواست |
| به ازای هر دقیقه به ازای هر کاربر در هر پروژه | ۶۰۰ درخواست |
آستانه صورتحساب روزانه
این محدودیت در هر روز برای هر پروژه، حداکثر تعداد درخواستهایی را که پروژه ابری شما میتواند در یک دوره ۲۴ ساعته قبل از اعمال هزینهها استفاده کند، تعریف میکند.
استفاده کمتر از این حد مجاز، هزینه اضافی ندارد و از حساب گوگل کلود شما صورتحسابی دریافت نمیشود. جزئیات کامل صورتحساب در اواخر سال ۲۰۲۶ با حداقل ۹۰ روز اطلاعرسانی قبل از اعمال هرگونه تغییر، به اشتراک گذاشته خواهد شد.
شما نمیتوانید درخواست افزایش این محدودیت آستانه روزانه را بدهید.
جدول زیر جزئیات این محدودیت را نشان میدهد:
| نوع محدودیت آستانه | حد |
|---|---|
| به ازای هر روز برای هر پروژه | ۱,۰۰۰,۰۰۰ درخواست |
برای اطلاعات بیشتر، به مدل استاندارد شدهی ابزارهای عامل و APIها در Google Workspace مراجعه کنید.
خطاهای سهمیهبندی مبتنی بر زمان را برطرف کنید
برای همه خطاهای مبتنی بر زمان (حداکثر 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 تقویم گوگل بدون هیچ هزینه اضافی در دسترس است. تجاوز از محدودیتهای درخواست سهمیه، طبق برنامهریزی، هزینههایی را برای حساب صورتحساب Google Cloud شما در اواخر سال 2026 به همراه خواهد داشت. برای اطلاعات بیشتر، به مدل استاندارد Google Workspace برای ابزارها و APIهای عامل مراجعه کنید.
درخواست افزایش سهمیه
بسته به میزان استفاده از منابع پروژهتان، ممکن است بخواهید درخواست تنظیم سهمیه بدهید. فراخوانیهای API توسط یک حساب کاربری سرویس، به عنوان استفاده از یک حساب کاربری واحد در نظر گرفته میشوند. درخواست برای سهمیه تنظیمشده، تضمینی برای تأیید نیست. درخواستهای تنظیم سهمیه که مقدار سهمیه را به میزان قابل توجهی افزایش میدهند، ممکن است مدت زمان بیشتری طول بکشد تا تأیید شوند.
همه پروژهها سهمیههای یکسانی ندارند. با گذشت زمان و افزایش استفاده از گوگل کلود، ممکن است لازم باشد مقادیر سهمیه شما افزایش یابد. اگر انتظار افزایش قابل توجه استفاده در آینده را دارید، میتوانید به صورت پیشگیرانه از صفحه سهمیهها و محدودیتهای سیستم در کنسول گوگل کلود، درخواست تنظیم سهمیه کنید .
برای مطالعه بیشتر، به منابع زیر مراجعه کنید:
عیبیابی
اگر از هر یک از سهمیهها تجاوز شود، نرخ شما محدود میشود و در پاسخ به درخواستهایتان، کد وضعیت 403 usageLimits یا کد وضعیت 429 usageLimits دریافت خواهید کرد.
اگر این اتفاق افتاد، میتوانید موارد زیر را امتحان کنید:
مطمئن شوید که تمام بهترین شیوهها را دنبال میکنید: از backoff نمایی استفاده کنید، الگوهای ترافیک را تصادفی کنید و از اعلانهای فوری استفاده کنید.
اگر پروژه شما در حال رشد است و کاربران بیشتری دارید، میتوانید درخواست افزایش سهمیه دهید.
اگر به محدودیت سهمیه هر کاربر برخوردید، میتوانید موارد زیر را انجام دهید:
اگر از یک حساب کاربری سرویس استفاده میکنید، بار را به کاربران اختصاص دهید یا آن را بین چندین حساب کاربری سرویس تقسیم کنید.
اگرچه میتوانید درخواست افزایش سهمیه هر کاربر را بدهید، اما بهطورکلی توصیه نمیکنیم آن را بالاتر از مقدار پیشفرض افزایش دهید زیرا ممکن است برنامه شما با انواع دیگری از محدودیتها، بهعنوانمثال، محدودیتهای استفاده از تقویم عمومی یا محدودیتهای عملیاتی، مواجه شود.
محدودیتهای سهمیه خود را با ثبت یک پروژه آزمایشی جداگانه که پیکربندی مشابهی با پروژه اصلی شما دارد، آزمایش کنید. برای اطلاعات بیشتر، به بخش «مدیریت محدودیت سهمیه آزمایشی» مراجعه کنید.
الگوهای ترافیک را تصادفی کنید
کلاینتهای تقویم مستعد الگوهای ترافیکی نامنظم هستند که ناشی از انجام همزمان عملیات توسط چندین کلاینت است. به عنوان مثال، یک روش بد رایج برای یک کلاینت تقویم، انجام همگامسازی کامل در نیمهشب است. این معمولاً از سهمیه هر دقیقه شما فراتر میرود و باعث محدودیت سرعت و قطعی میشود.
برای جلوگیری از این امر، ترافیک خود را در طول روز، تا حد امکان، پخش کنید. اگر کلاینت شما نیاز به همگامسازی روزانه دارد، از کلاینت بخواهید یک زمان تصادفی (برای هر کلاینت متفاوت) تعیین کند. اگر نیاز دارید عملیاتی را به طور منظم انجام دهید، فاصله زمانی را ±25٪ تغییر دهید. این کار ترافیک را به طور مساویتری توزیع میکند و تجربه کاربری بهتری را فراهم میکند.
از اعلانهای فشاری استفاده کنید
یک مورد استفاده رایج، انجام یک عمل در هر زمانی است که چیزی در تقویم کاربر تغییر میکند. یک الگوی مخالف در اینجا، نظرسنجی مکرر از هر تقویم مورد نظر است. این کار به سرعت سهمیه شما را تمام میکند. به عنوان مثال، اگر برنامه شما ۵۰۰۰ کاربر دارد و تقویم هر کاربر را یک بار در دقیقه نظرسنجی میکند، این امر به سهمیه حداقل ۵۰۰۰ در دقیقه، حتی قبل از انجام هر کاری، نیاز دارد.
برنامههای سمت سرور میتوانند برای اعلانهای فوری ثبتنام کنند، که به تقویم اجازه میدهد وقتی اتفاق جالبی میافتد به شما اطلاع دهد. این موارد نیاز به کار بیشتری برای راهاندازی دارند، اما به شما امکان میدهند از سهمیه به طور مؤثرتری استفاده کنید و تجربه کاربری بهتری ارائه دهید. eventType که میخواهید اعلانها را برای آن دریافت کنید، مشخص کنید. برای اطلاعات بیشتر، به اعلانهای فوری مراجعه کنید.
تخصیص مناسب با حسابهای خدماتی
اگر برنامه شما درخواستها را با استفاده از واگذاری اختیارات در سطح دامنه انجام میدهد، به طور پیشفرض، حساب سرویس بر اساس سهمیههای «به ازای هر دقیقه برای هر کاربر در هر پروژه» محاسبه میشود، و نه کاربری که شما جعل هویت میکنید. این بدان معناست که حساب سرویس احتمالاً سهمیه خود را تمام کرده و محدود به نرخ میشود، حتی اگر ممکن است بر اساس تقویمهای چندین کاربر عمل کند.
شما میتوانید با استفاده از پارامتر آدرس URL quotaUser (یا هدر HTTP مربوط به x-goog-quota-user ) برای نشان دادن اینکه از کدام کاربر هزینه دریافت میشود، از این مشکل جلوگیری کنید. گوگل از این پارامتر فقط برای محاسبات سهمیه استفاده میکند. برای اطلاعات بیشتر، به بخش محدود کردن درخواستها به ازای هر کاربر مراجعه کنید.
مدیریت محدودیت سهمیه آزمون
برای اطمینان از اینکه برنامه شما در عمل به خوبی از پسِ رسیدن به محدوده سهمیه برمیآید (برای مثال، از طریق تلاشهای مجدد با backoff نمایی ) و برای به حداقل رساندن هرگونه اختلال احتمالی برای کاربرانتان، برنامه خود را در یک محیط واقعی آزمایش کنید.
برای آزمایش بدون تداخل با کاربرد واقعی برنامهتان، یک پروژه آزمایشی جداگانه در کنسول Google Cloud ثبت کنید و سپس صفحه رضایت OAuth را مشابه پروژه اصلی خود پیکربندی کنید . سپس میتوانید محدودیتهای سهمیه مصنوعی پایین برای این پروژه تعیین کنید و رفتار برنامه خود را مشاهده کنید.
سهمیههای سرور تقویم MCP
سرور Calendar MCP از یک معیار تخصیص هزینه پرسوجو استفاده میکند. جداول زیر هزینه پرسوجو را برای هر روش سرور Calendar MCP بر اساس بخش، به تفصیل نشان میدهند:
سهمیههای تقویمی MCP
دو نوع سهمیه اعمال میشود:
به ازای هر دقیقه برای هر پروژه: این هزینه پرس و جو برای پروژه ابری شما به مدت یک دقیقه است.
به ازای هر دقیقه به ازای هر کاربر در هر پروژه: این هزینه پرسوجویی است که هر کاربر در پروژه ابری شما میتواند در یک دقیقه متحمل شود.
جدول زیر جزئیات این سهمیهها را نشان میدهد:
| نوع محدودیت استفاده | هزینه پرس و جو |
|---|---|
| به ازای هر دقیقه برای هر پروژه | ۱۰۰۰۰ |
| به ازای هر دقیقه به ازای هر کاربر در هر پروژه | ۶۰۰ |
سهمیههای ابزار تقویم MCP
جدول زیر هزینه پرس و جو برای هر مجموعه ابزار calendarmcp.googleapis.com را با جزئیات نشان میدهد:
| نقطه پایانی | ابزار | هزینه پرس و جو |
|---|---|---|
/mcp/v1 | | ۱ |
| ۱۰ | |
| ۱ | |
| ۱ | |
| ۱ | |
| ۱ | |
| ۱ | |
| ۱ | |
| ۱ |
برای اطلاعات بیشتر، به مرجع API تقویم MCP مراجعه کنید.