API تقویم گوگل سهمیهبندیهایی دارد تا اطمینان حاصل شود که همه کاربران به طور منصفانه از آن استفاده میکنند. هنگام استفاده از API تقویم، سه محدودیت مهم وجود دارد که باید در نظر گرفته شوند:
سهمیه استفاده از API : به ازای هر پروژه و هر کاربر اعمال میشود. برای اطلاعات بیشتر، به انواع سهمیه استفاده از API تقویم مراجعه کنید.
محدودیتهای کلی استفاده از تقویم گوگل : رابط برنامهنویسی کاربردی تقویم گوگل (Google Calendar API) یک سرویس اشتراکی است که محدودیتهایی برای محافظت از عملکرد کلی سیستم Google Workspace دارد. برای اطلاعات بیشتر، به بخش «اجتناب از محدودیتهای استفاده از تقویم» مراجعه کنید.
محدودیتهای عملیاتی : این محدودیتها ممکن است در هر زمانی محدود شوند. برای مثال، اگر سعی کنید پشت سر هم و سریع در یک تقویم بنویسید.
سهمیههای API تقویم
دو نوع سهمیه اعمال میشود:
در هر دقیقه برای هر پروژه: این تعداد درخواستهایی است که پروژه Google Cloud شما میتواند در یک دقیقه انجام دهد.
در هر دقیقه به ازای هر کاربر در هر پروژه: این تعداد درخواستهایی است که هر کاربر خاص میتواند در پروژه ابری شما انجام دهد. هدف این محدودیت کمک به شما در تضمین توزیع عادلانه استفاده بین کاربرانتان است.
سهمیهها با استفاده از یک پنجره کشویی در هر دقیقه محاسبه میشوند. افزایش سریع ترافیک که در طول یک دقیقه از سهمیه شما در هر دقیقه بیشتر شود، منجر به محدودیت سرعت در طول پنجره بعدی میشود تا اطمینان حاصل شود که به طور متوسط، میزان استفاده شما در محدوده سهمیه باقی میماند.
جدول زیر جزئیات این محدودیتها را نشان میدهد:
| نوع محدودیت استفاده | حد |
|---|---|
| به ازای هر دقیقه برای هر پروژه | ۱۰،۰۰۰ درخواست |
| به ازای هر دقیقه به ازای هر کاربر در هر پروژه | ۶۰۰ درخواست |
آستانه صورتحساب روزانه
این محدودیت در هر روز به ازای هر پروژه، حداکثر تعداد درخواستهایی را که پروژه 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 را مشابه پروژه اصلی خود پیکربندی کنید . سپس میتوانید محدودیتهای سهمیه مصنوعی پایین برای این پروژه تعیین کنید و رفتار برنامه خود را مشاهده کنید.