حدود استفاده

Google Calendar API دارای سهمیه‌هایی است تا اطمینان حاصل شود که همه کاربران به‌طور عادلانه از آن استفاده می‌کنند. هنگام استفاده از Calendar API، سه محدودیت مهم وجود دارد که باید درنظر بگیرید:

  • سهمیه‌های استفاده از میانای برنامه‌سازی کاربردی: برای هر پروژه و هر کاربر اعمال می‌شود. برای اطلاعات بیشتر، به انواع سهمیه استفاده از Calendar API مراجعه کنید.

  • محدودیت‌های کلی استفاده از «تقویم Google»: Google Calendar API سرویسی مشترک است که برای محافظت از عملکرد کلی سیستم Google Workspace محدودیت‌هایی دارد. برای اطلاعات بیشتر، به اجتناب از محدودیت‌های استفاده از «تقویم» مراجعه کنید.

  • محدودیت‌های عملیاتی: این محدودیت‌ها ممکن است در هرزمانی محدود شوند. برای مثال، اگر تلاش کنید در یک تقویم به‌طور متوالی و سریع بنویسید.

سهمیه‌های Calendar API

دو نوع سهمیه اعمال می‌شود:

  • در دقیقه برای هر پروژه: این تعداد درخواست‌هایی است که پروژه Google Cloud شما می‌تواند در یک دقیقه انجام دهد.

  • در دقیقه برای هر کاربر برای هر پروژه: این تعداد درخواست‌هایی است که هر کاربر خاص می‌تواند در پروژه Cloud شما ایجاد کند. هدف از این محدودیت این است که به شما کمک کند از توزیع عادلانه استفاده در میان کاربران خود اطمینان حاصل کنید.

سهمیه‌ها در هر دقیقه بااستفاده از پنجره لغزنده محاسبه می‌شود. افزایش ناگهانی ترافیک که از سهمیه دقیقه‌ای شما درطول یک دقیقه فراتر رود، منجر به محدودیت نرخ در پنجره بعدی می‌شود تا اطمینان حاصل شود که به‌طور میانگین، استفاده شما در محدوده سهمیه‌ها باقی می‌ماند.

جدول زیر جزئیات این محدودیت‌ها را نشان می‌دهد:

نوع حد استفاده حد
در دقیقه برای هر پروژه ‫۱۰٬۰۰۰ درخواست
در دقیقه برای هر کاربر برای هر پروژه ‫۶۰۰ درخواست

آستانه صورت‌حساب روزانه

این حد روزانه برای هر پروژه حداکثر تعداد درخواست‌هایی را که پروژه Google Cloud شما می‌تواند در یک دوره ۲۴ ساعته قبل‌از اعمال هزینه‌ها استفاده کند، تعریف می‌کند.

استفاده کمتر از این آستانه هزینه اضافی ندارد و برای حساب Google Cloud شما صورت‌حساب صادر نمی‌شود. جزئیات کامل صدور صورت‌حساب بعداً در سال ۲۰۲۶ با حداقل ۹۰ روز پیش‌اعلان قبل‌از اعمال هرگونه تغییر هم‌رسانی خواهد شد.

نمی‌توانید برای این حد آستانه روزانه درخواست افزایش دهید.

جدول زیر جزئیات این محدودیت را نشان می‌دهد:

نوع حد آستانه حد
در روز برای هر پروژه ‫۱٬۰۰۰٬۰۰۰ درخواست

برای اطلاعات بیشتر، مدل استانداردشده Google Workspace برای ابزارها و میاناهای برنامه‌سازی کاربردی عامل را ببینید.

حل‌وفصل کردن خطاهای سهمیه زمان‌محور

برای همه خطاهای مبتنی بر زمان (حداکثر N درخواست در هر X دقیقه)، توصیه می‌کنیم کد شما استثنا را بگیرد و از عقب‌نشینی نمایی کوتاه استفاده کند تا مطمئن شوید دستگاه‌هایتان بار اضافی تولید نمی‌کنند.

عقب‌نشینی نمایی یک استراتژی استاندارد رسیدگی به خطا برای برنامه‌های شبکه است. الگوریتم عقب‌گرد نمایی درخواست‌ها را بااستفاده از زمان‌های انتظار به‌صورت نمایی افزایشی بین درخواست‌ها، تا حداکثر زمان عقب‌گرد، دوباره امتحان می‌کند. اگر درخواست‌ها همچنان ناموفق بود، مهم است که تأخیر بین درخواست‌ها به‌مرور زمان افزایش یابد تا درخواست موفقیت‌آمیز شود.

الگوریتم نمونه

الگوریتم عقب‌گرد نمایی درخواست‌ها را به‌صورت نمایی امتحان مجدد می‌کند و زمان انتظار بین امتحان‌های مجدد را تا حداکثر زمان عقب‌گرد افزایش می‌دهد. برای مثال:

  1. درخواستی به Google Calendar API ارسال کنید.
  2. اگر درخواست ناموفق بود، random_number_milliseconds + ۱ صبر کنید و درخواست را دوباره امتحان کنید.
  3. اگر درخواست ناموفق بود، random_number_milliseconds + ۲ صبر کنید و درخواست را دوباره امتحان کنید.
  4. اگر درخواست ناموفق بود، random_number_milliseconds + ۴ صبر کنید و درخواست را دوباره امتحان کنید.
  5. و به همین ترتیب، تا maximum_backoff بار.
  6. به انتظار و تلاش مجدد تا حداکثر تعداد تلاش مجدد ادامه دهید، اما دوره انتظار بین تلاش‌های مجدد را افزایش ندهید.

where:

  • زمان انتظار min(((2^n)+random_number_milliseconds), maximum_backoff) است، و n برای هر تکرار (درخواست) ۱ عدد افزایش می‌یابد.
  • ‫random_number_milliseconds عدد تصادفی از میلی‌ثانیه‌ها است که کمتر یا مساوی ۱۰۰۰ است. این کار کمک می‌کند از مواردی که در آن بسیاری از کارخواه‌ها به‌دلیل شرایطی همگام‌سازی می‌شوند و همه به‌طور هم‌زمان دوباره امتحان می‌کنند و درخواست‌ها را در موج‌های همگام‌سازی‌شده ارسال می‌کنند، جلوگیری شود. مقدار random_number_milliseconds پس‌از هر درخواست تکرار مجدد دوباره محاسبه می‌شود.
  • maximum_backoff معمولاً ۳۲ یا ۶۴ ثانیه است. مقدار مناسب به مورد استفاده بستگی دارد.

مشتری می‌تواند پس‌از رسیدن به زمان maximum_backoff، به تلاش مجدد ادامه دهد. تلاش‌های مجدد پس‌از این نقطه نیازی به ادامه افزایش زمان عقب‌نشینی ندارند. برای مثال، اگر کارخواهی از زمان maximum_backoff ۶۴ ثانیه استفاده کند، پس‌از رسیدن به این مقدار، کارخواه می‌تواند هر ۶۴ ثانیه دوباره امتحان کند. در نقطه‌ای، باید از تلاش مجدد نامحدود کارخواه‌ها جلوگیری شود.

زمان انتظار بین تلاش‌های مجدد و تعداد تلاش‌های مجدد به مورد استفاده شما و شرایط شبکه بستگی دارد.

قیمت‌گذاری

همه استفاده‌های استاندارد از Google Calendar API بدون هزینه اضافی دردسترس است. فراتر رفتن از حدود درخواست سهمیه قرار است در اواخر سال ۲۰۲۶ برای حساب صورت‌حساب Google Cloud شما هزینه داشته باشد. برای اطلاعات بیشتر، مدل استانداردشده Google Workspace برای میاناهای برنامه‌سازی کاربردی و ابزارهای نماینده را ببینید.

درخواست افزایش سهمیه

بسته به میزان استفاده از منابع پروژه‌تان، ممکن است بخواهید درخواست تعدیل سهمیه کنید. فراخوانی‌های API توسط حساب سرویس به‌عنوان استفاده از یک حساب واحد درنظر گرفته می‌شود. درخواست برای سهمیه اصلاح‌شده تضمینی برای تأیید نیست. درخواست‌های تعدیل سهمیه که مقدار سهمیه را به‌طور قابل‌توجهی افزایش می‌دهند ممکن است برای تأیید شدن به زمان بیشتری نیاز داشته باشند.

همه پروژه‌ها سهمیه‌های یکسانی ندارند. با گذشت زمان و افزایش استفاده شما از Google Cloud، ممکن است لازم باشد مقادیر سهمیه شما افزایش یابد. اگر انتظار دارید در آینده نزدیک افزایش قابل‌توجهی در استفاده داشته باشید، می‌توانید به‌طور پیش‌گیرانه از صفحه سهمیه‌ها و حدود سیستم در کنسول Google Cloud درخواست اصلاح سهمیه کنید.

برای اطلاعات بیشتر، منابع زیر را ببینید:

عیب‌یابی

اگر از هرکدام از این سهمیه‌ها فراتر بروید، نرخ شما محدود می‌شود و در پاسخ به پُرسمان‌هایتان، رمز وضعیت 403 usageLimits یا رمز وضعیت 429 usageLimits دریافت می‌کنید.

اگر این اتفاق افتاد، می‌توانید موارد زیر را امتحان کنید:

  1. حتماً همه روال‌های مطلوب را دنبال کنید: از عقب‌نشینی نمایی استفاده کنید، الگوهای ترافیک را تصادفی کنید، و از اعلان‌های لحظه‌ای استفاده کنید.

  2. اگر پروژه‌تان درحال رشد است و کاربران بیشتری دارید، می‌توانید درخواست افزایش سهمیه کنید.

  3. اگر به حد سهمیه هر کاربر رسیدید، می‌توانید کارهای زیر را انجام دهید:

    • اگر از حساب سرویس استفاده می‌کنید، بار را به کاربران اختصاص دهید یا آن را بین چند حساب سرویس تقسیم کنید.

    • اگرچه می‌توانید درخواست افزایش سهمیه برای هر کاربر را داشته باشید، اما به‌طور کلی، توصیه نمی‌شود که آن را بالاتر از مقدار پیش‌فرض افزایش دهید زیرا ممکن است برنامه شما با انواع دیگری از محدودیت‌ها مواجه شود، برای مثال، محدودیت‌های عمومی استفاده از تقویم یا محدودیت‌های عملیاتی.

  4. با ثبت پروژه آزمایشی جداگانه‌ای که پیکربندی مشابهی با پروژه تولیدی شما دارد، محدودیت‌های سهمیه‌تان را آزمایش کنید. برای اطلاعات بیشتر، مدیریت حد سهمیه آزمایشی را ببینید.

تصادفی کردن الگوهای ترافیک

مشتریان «تقویم» مستعد الگوهای ترافیک جهشی هستند که به‌دلیل انجام عملیات توسط چندین مشتری به‌طور هم‌زمان ایجاد می‌شود. برای مثال، یک عملکرد بد رایج برای کارخواه «تقویم» این است که همگام‌سازی کامل را در نیمه‌شب انجام دهد. این کار تقریباً به‌طور قطع منجر به فراتر رفتن از سهمیه دقیقه‌ای شما می‌شود و به محدودیت نرخ و عقب‌نشینی منجر می‌شود.

برای جلوگیری از این امر، مطمئن شوید که ترافیک شما درطول روز تا حد امکان توزیع شده باشد. اگر کارخواهتان باید همگام‌سازی روزانه انجام دهد، از او بخواهید زمان تصادفی‌ای را تعیین کند (برای هر کارخواه متفاوت باشد). اگر لازم است عملیاتی را به‌طور منظم انجام دهید، فاصله زمانی را ۲۵٪ بیشتر یا کمتر کنید. این کار ترافیک را به‌طور یکنواخت‌تری توزیع می‌کند و تجربه کاربری بسیار بهتری ارائه می‌دهد.

استفاده از اعلان‌های لحظه‌ای

یک مورد استفاده رایج، انجام کنشی است که هرگاه چیزی در تقویم کاربر تغییر می‌کند، انجام می‌شود. یک الگوی ضد در اینجا این است که به‌طور مکرر هر تقویم مورد علاقه را نظرسنجی کنید. این کار خیلی سریع کل سهمیه شما را مصرف می‌کند. برای مثال، اگر برنامه شما ۵۰۰۰ کاربر داشته باشد و تقویم هر کاربر را یک بار در دقیقه نظرسنجی کند، این کار به سهمیه دقیقه‌ای حداقل ۵۰۰۰ نیاز دارد، حتی قبل‌از اینکه کاری انجام شود.

برنامه‌های سمت سرور می‌توانند برای اعلان‌های لحظه‌ای ثبت‌نام کنند، که به ما امکان می‌دهد وقتی اتفاق جالبی می‌افتد به شما اطلاع دهیم. راه‌اندازی این موارد به کار بیشتری نیاز دارد، اما امکان استفاده بسیار کارآمدتر از سهمیه‌تان را فراهم می‌کند و تجربه کاربری بهتری ارائه می‌دهد. حتماً eventType را که می‌خواهید برای آن اعلان دریافت کنید مشخص کنید. برای اطلاعات بیشتر، به اعلان‌های فشاری مراجعه کنید.

تخصیص مناسب با حساب‌های سرویس

اگر برنامه شما درخواست‌ها را بااستفاده از واگذاری سراسر دامنه انجام می‌دهد، به‌طور پیش‌فرض حساب سرویس با توجه به سهمیه‌های «در دقیقه برای هر کاربر برای هر پروژه» شارژ می‌شود، نه کاربری که خود را به‌جای او جا می‌زنید. این یعنی احتمالاً سهمیه حساب سرویس تمام می‌شود و نرخ آن محدود می‌شود، هرچند ممکن است در تقویم‌های چند کاربر درحال اجرا باشد.

بااستفاده از پارامتر نشانی وب quotaUser (یا سرصفحه HTTP x-goog-quota-user) برای مشخص کردن رشته‌ای دلخواه (حداکثر ۴۰ نویسه) که هر کاربر متمایز را به‌طور منحصربه‌فرد شناسایی می‌کند، می‌توانید از این امر جلوگیری کنید. Calendar API از این مقدار فقط برای محاسبات سهمیه استفاده می‌کند.

برای استفاده از quotaUser جهت اعمال محدودیت‌های نرخ برای هر کاربر در میان کاربران متمایز، درخواست‌های شما باید شرایط زیر را برآورده کند:

  • کلید میانای برنامه‌سازی کاربردی محدودشده با IP را اضافه کنید: کلید میانای برنامه‌سازی کاربردی را در پارامتر پُرسمان key ارسال کنید و آن کلید را با محدودیت‌های نشانی IP پیکربندی کنید و نشانی‌های IP عمومی سرورهای زیرینه خود را مشخص کنید. اگر کلید API را حذف کنید یا محدودیت‌های نشانی IP را پیکربندی نکنید، Calendar API از quotaUser صرف‌نظر می‌کند و سهمیه را به حساب اصالت‌سنجی‌شده (مانند حساب سرویس) اختصاص می‌دهد.

  • حذف سرایند X-Goog-User-Project: سرایند HTTP‏ X-Goog-User-Project را در درخواست‌هایی که از quotaUser استفاده می‌کنند ارسال نکنید. ارائه پروژه کاربر، کلید میانای برنامه‌سازی کاربردی را برای تخصیص سهمیه لغو می‌کند، بنابراین Calendar API quotaUser را نادیده می‌گیرد.

برای اطلاعات بیشتر، محدود کردن درخواست‌ها برای هر کاربر را ببینید.

آزمایش مدیریت حد سهمیه

برای اطمینان از اینکه برنامه‌تان می‌تواند در عمل به‌خوبی از پس رسیدن به محدودیت‌های سهمیه برآید (برای مثال، ازطریق امتحان مجدد با عقب‌گرد نمایی) و برای به‌حداقل رساندن هرگونه اختلال احتمالی برای کاربران، اکیداً توصیه می‌کنیم سناریوتان را در محیطی واقعی آزمایش کنید.

برای آزمایش بدون تداخل با استفاده واقعی از برنامه‌تان، توصیه می‌کنیم پروژه آزمایشی جداگانه‌ای در کنسول Google Cloud ثبت کنید و سپس صفحه رضایت OAuth را به‌روشی مشابه با پروژه تولیدتان پیکربندی کنید. سپس می‌توانید محدودیت‌های سهمیه را به‌طور مصنوعی برای این پروژه پایین تنظیم کنید و رفتار برنامه‌تان را مشاهده کنید.

سهمیه‌های سرور MCP «تقویم»

سرور MCP «تقویم» از سنجه تخصیص هزینه پُرسمان استفاده می‌کند. جدول‌های زیر جزئیات هزینه پُرسمان را برای هر روش سرور MCP «تقویم» براساس بخش نشان می‌دهد:

سهمیه‌های MCP تقویم

دو نوع سهمیه اعمال می‌شود:

  • در دقیقه برای هر پروژه: این هزینه پُرسمان برای پروژه Google Cloud شما در یک دقیقه است.

  • در دقیقه به‌ازای هر کاربر به‌ازای هر پروژه: این هزینه پُرسمان برای پروژه Google Cloud شما به‌مدت یک دقیقه است که هر کاربر خاصی می‌تواند از آن استفاده کند.

جدول زیر جزئیات این سهمیه‌ها را نشان می‌دهد:

نوع حد استفاده هزینه پُرسمان
در دقیقه برای هر پروژه ‫۱۰٬۰۰۰
در دقیقه برای هر کاربر برای هر پروژه 600

سهمیه‌های مجموعه ابزار MCP «تقویم»

جدول زیر جزئیات هزینه پُرسمان را برای هر مجموعه ابزار calendarmcp.googleapis.com نشان می‌دهد:

نقطه پایانی ابزار هزینه پُرسمان

/mcp/v1

create_event

1

delete_event

10

get_event

1

list_events

1

respond_to_event

1

search_events

1

update_event

1

suggest_time

1

list_calendars

1

برای اطلاعات بیشتر، به مرجع میانای برنامه‌سازی کاربردی MCP «تقویم» مراجعه کنید.