מגבלות שימוש

ל-יומן Google API יש מכסות כדי לוודא שכל המשתמשים משתמשים בו בצורה הוגנת. כשמשתמשים ב-Calendar API, חשוב לשים לב לשלוש מגבלות חשובות:

• מכסות שימוש ב-API: נאכפות לכל פרויקט ולכל משתמש. מידע נוסף זמין במאמר בנושא סוגי מכסות לשימוש ב-Calendar API.

• הגבלות כלליות על השימוש ביומן: Calendar API הוא שירות משותף שיש לו הגבלות כדי להגן על הביצועים הכוללים של מערכת Google Workspace. מידע נוסף מופיע במאמר בנושא איך להימנע ממגבלות השימוש ביומן.

• מגבלות תפעוליות: יכול להיות שהמגבלות האלה יחולו בכל שלב. לדוגמה, יכול להיות שיוחלו מגבלות אם תנסו לכתוב ליומן יחיד ברצף מהיר.

מכסות ל-Calendar API

יש שני סוגים של מכסות:

• לכל דקה לכל פרויקט: זהו מספר הבקשות שפרויקט Google Cloud יכול לשלוח בדקה אחת.

• לדקה לכל משתמש לכל פרויקט: זהו מספר הבקשות שכל משתמש יכול לשלוח בפרויקט בענן. המגבלה הזו עוזרת להבטיח חלוקה הוגנת של השימוש בין המשתמשים.

המכסות מחושבות לדקה באמצעות חלון הזזה. אם תהיה עלייה חדה בתנועה שתחרוג מהמכסה לדקה, תופעל הגבלת קצב במהלך חלון הזמן הבא כדי להבטיח שהשימוש הממוצע יישאר במסגרת המכסות.

בטבלה הבאה מפורטות המגבלות האלה:

סוג מכסת השימוש	מגבלה
לדקה לכל פרויקט	‫10,000 בקשות
לדקה לכל משתמש לכל פרויקט	‫600 בקשות

סף החיוב היומי

המגבלה הזו לכל פרויקט ביום מגדירה את המספר המקסימלי של בקשות שפרויקט בענן יכול לשלוח בפרק זמן של 24 שעות לפני שמתחילים לחייב עליו.

אם השימוש שלכם נמוך מהסף הזה, לא תחויבו בחשבון Google Cloud. פרטי החיוב המלאים ישותפו בהמשך בשנת 2026, לפחות 90 יום לפני ששינויים ייכנסו לתוקף.

אי אפשר לבקש להגדיל את המגבלה הזו של סף יומי.

בטבלה הבאה מפורטת המגבלה:

סוג מגבלת הסף	מגבלה
לכל פרויקט ביום	‫1,000,000 בקשות

מידע נוסף זמין במאמר בנושא מודל סטנדרטי של Google Workspace לכלי סוכנים וממשקי API.

פתרון שגיאות שקשורות למכסת זמן

לגבי כל השגיאות שמבוססות על זמן (מקסימום N בקשות לכל X דקות), מומלץ שהקוד יזהה את החריגה וישתמש בנסיגה אקספוננציאלית קטומה כדי לוודא שהמכשירים לא יוצרים עומס מוגזם.

השהיה מעריכית לפני ניסיון חוזר (exponential backoff) היא אסטרטגיה סטנדרטית לטיפול בשגיאות באפליקציות רשת. אלגוריתם של השהיה מעריכית לפני ניסיון חוזר (exponential backoff) מבצע ניסיון חוזר של בקשות באמצעות הגדלה אקספוננציאלית של זמני ההמתנה בין הבקשות, עד למשך ההשהיה המקסימלי. אם הבקשות עדיין לא מצליחות, חשוב שההשהיות בין הבקשות יגדלו עם הזמן עד שהבקשה תצליח.

אלגוריתם לדוגמה

אלגוריתם של השהיה מעריכית לפני ניסיון חוזר (exponential backoff) מבצע ניסיון חוזר של בקשות באופן אקספוננציאלי, ומגדיל את זמן ההמתנה בין הניסיונות החוזרים עד למשך ההשהיה המקסימלי. לדוגמה:

1. שליחת בקשה ל-Google Calendar API.
2. אם הבקשה נכשלת, צריך להמתין ‎1 + random_number_milliseconds‎ שניות ולנסות שוב את הבקשה.
3. אם הבקשה נכשלת, צריך להמתין ‎2 + random_number_milliseconds‎ שניות ולנסות שוב את הבקשה.
4. אם הבקשה נכשלת, צריך להמתין ‎4 + random_number_milliseconds‎ שניות ולנסות שוב את הבקשה.
5. וכך הלאה, עד maximum_backoff פעמים.
6. ממשיכים להמתין ולנסות שוב עד שמגיעים למספר מקסימלי מסוים של ניסיונות חוזרים, אבל לא מגדילים את תקופת ההמתנה בין הניסיונות החוזרים.

where:

• זמן ההמתנה הוא min(((2^n)+random_number_milliseconds), maximum_backoff), שבו n גדל ב-1 בכל איטרציה (בקשה).
• ‫random_number_milliseconds הוא מספר אקראי של אלפיות השנייה שקטן מ-1,000 או שווה לו. כך אפשר להימנע ממקרים שבהם הרבה לקוחות מסונכרנים בגלל מצב מסוים וכולם מנסים לשלוח בקשות בו-זמנית. הערך של random_number_milliseconds מחושב מחדש אחרי כל בקשה לניסיון חוזר.
• הערך של maximum_backoff הוא בדרך כלל 32 או 64 שניות. הערך המתאים תלוי בתרחיש לדוגמה.

הלקוח יכול להמשיך לנסות שוב אחרי שהגיע לזמן maximum_backoff. ניסיונות חוזרים אחרי הנקודה הזו לא צריכים להמשיך להגדיל את זמן ההשהיה. לדוגמה, אם לקוח משתמש בזמן maximum_backoff של 64 שניות, אחרי שהערך הזה מושג, הלקוח יכול לנסות שוב כל 64 שניות. בשלב מסוים, צריך למנוע מהלקוחות לנסות שוב ללא הגבלה.

זמן ההמתנה בין ניסיונות חוזרים ומספר הניסיונות החוזרים תלויים בתרחיש לדוגמה ובתנאי הרשת.

תמחור

כל השימוש הרגיל ב-Google Calendar API זמין ללא עלות נוספת. אנחנו מתכננים להתחיל לחייב את החשבון שלכם לחיוב ב-Google Cloud על חריגה ממגבלות הבקשות של המכסה בהמשך שנת 2026. מידע נוסף זמין במאמר בנושא מודל סטנדרטי של Google Workspace לכלי סוכנים וממשקי API.

שליחת בקשה להגדלת המכסה

יכול להיות שתרצו לבקש שינוי במכסות בהתאם לשימוש במשאבים בפרויקט. קריאות ל-API על ידי חשבון שירות נחשבות לשימוש בחשבון יחיד. הגשת בקשה להתאמת המכסה לא מבטיחה שהבקשה תאושר. יכול להיות שיחלפו יותר זמן עד לאישור בקשות להתאמת מכסה שיגרמו לעלייה משמעותית בערך המכסה.

המכסות לא זהות בכל הפרויקטים. ככל שהשימוש שלכם ב-Google Cloud יגדל עם הזמן, יכול להיות שתצטרכו להגדיל את ערכי המכסות. אם צפויה עלייה משמעותית בשימוש, אפשר לבקש התאמות של המכסות מראש בדף Quotas & System Limits (מכסות ומגבלות מערכת) במסוף Google Cloud.

מידע נוסף זמין במקורות המידע הבאים:

• מידע על שינוי מכסות
• איך רואים את השימוש במכסות ואת המכסות
• איך מבקשים להגדיל את המכסות

פתרון בעיות

אם תחרגו מאחת מהמכסות, תוגבל מהירות השליחה של הבקשות ותקבלו קוד סטטוס 403 usageLimits או קוד סטטוס 429 usageLimits בתגובה לשאילתות.

אם זה קורה, אפשר לנסות את הפעולות הבאות:

1. חשוב לפעול לפי כל השיטות המומלצות: להשתמש בנסיגה אקספוננציאלית, לערבב את דפוסי התנועה ולהשתמש בהתראות פוש.

2. אם הפרויקט שלכם גדל ויש לכם יותר משתמשים, אתם יכולים לבקש הגדלה של המכסה.

3. אם הגעתם למכסות לכל משתמש, אתם יכולים:

   • אם משתמשים בחשבון שירות, צריך להקצות את העומס למשתמשים או לפצל אותו בין כמה חשבונות שירות.

   • אפשר לבקש להגדיל את המכסה לכל משתמש, אבל באופן כללי לא מומלץ להגדיל אותה מעבר לערך ברירת המחדל, כי יכול להיות שהאפליקציה תגיע למגבלות מסוגים אחרים, למשל מגבלות כלליות על השימוש ביומן או מגבלות תפעוליות.

4. כדי לבדוק את מגבלות המכסה, צריך לרשום פרויקט נפרד לבדיקה בלבד, עם הגדרה דומה לזו של פרויקט הייצור. מידע נוסף מופיע במאמר בנושא בדיקת הטיפול במגבלת המכסה.

יצירת דפוסי תנועה אקראיים

לקוחות של יומנים נוטים לדפוסי תנועה עם עליות חדות שנגרמות בגלל כמה לקוחות שמבצעים פעולות בו-זמנית. לדוגמה, שיטה לא מומלצת ללקוח של יומן היא לבצע סנכרון מלא בחצות. בדרך כלל, מספר הבקשות חורג מהמכסה לדקה, ולכן המערכת מגבילה את קצב הבקשות ומבצעת נסיגות.

כדי להימנע מכך, מומלץ לפזר את התנועה במהלך היום בכל מקום שאפשר. אם הלקוח צריך לבצע סנכרון יומי, הלקוח צריך לקבוע שעה אקראית (שונה לכל לקוח). אם אתם צריכים לבצע פעולה על בסיס קבוע, כדאי לשנות את המרווח בטווח של ‎±25%‎. כך התנועה מתחלקת בצורה שווה יותר וחוויית המשתמש משתפרת.

שימוש בהתראות

תרחיש נפוץ לשימוש הוא ביצוע פעולה בכל פעם שמשהו משתנה ביומן של המשתמש. דוגמה לאנטי-תבנית היא שליחת בקשות חוזרות לכל היומנים שמעניינים אתכם. כך המכסה שלכם מתמלאת במהירות. לדוגמה, אם לאפליקציה שלכם יש 5,000 משתמשים והיא שולחת שאילתה ליומן של כל משתמש פעם בדקה, אז נדרשת מכסה של 5,000 לפחות לדקה, עוד לפני שמתבצעת עבודה כלשהי.

אפליקציות בצד השרת יכולות להירשם לקבלת התראות פוש, וכך יומן Google יוכל להודיע לכם כשקורה משהו שמעניין אתכם. ההגדרות האלה דורשות יותר עבודה, אבל הן מאפשרות להשתמש במכסת האחסון בצורה יעילה יותר ולספק חוויית משתמש טובה יותר. מציינים את eventType שרוצים לקבל עליה התראות. מידע נוסף זמין במאמר בנושא התראות Push.

הקצאה נכונה באמצעות חשבונות שירות

אם האפליקציה שלכם מבצעת בקשות באמצעות הענקת גישה ברמת הדומיין, כברירת מחדל חשבון השירות מחויב במסגרת המכסות 'לדקה לכל משתמש לכל פרויקט', ולא המשתמש שאתם מתחזים לו. המשמעות היא שסביר להניח שהמכסה של חשבון השירות תנוצל במלואה והוא יוגבל בקצב, גם אם הוא פועל ביומנים של כמה משתמשים.

כדי להימנע מכך, אפשר להשתמש בפרמטר quotaUser של כתובת ה-URL (או בכותרת ה-HTTP‏ x-goog-quota-user) כדי לציין איזה משתמש מחויב. ‫Google משתמשת בפרמטר הזה רק לחישוב מכסת השימוש. מידע נוסף מופיע במאמר בנושא הגבלת הבקשות לכל משתמש.

בדיקה של טיפול במגבלות מכסה

כדי לוודא שהאפליקציה שלך מטפלת בצורה חלקה בהגעה למגבלות מכסת השימוש בפועל (לדוגמה, באמצעות ניסיונות חוזרים עם השהיה מעריכית לפני ניסיון חוזר) וכדי לצמצם הפרעות אפשריות למשתמשים, מומלץ לבדוק את האפליקציה בסביבה ריאליסטית.

כדי לבצע בדיקה בלי להפריע לשימוש באפליקציה האמיתית, צריך לרשום פרויקט נפרד למטרות בדיקה בלבד במסוף Google Cloud ואז להגדיר את מסך ההסכמה של OAuth באופן דומה לפרויקט הייצור. אחר כך תוכלו להגדיר מכסות נמוכות באופן מלאכותי לפרויקט הזה ולבחון את ההתנהגות של האפליקציה.

מכסות של שרת ה-MCP של היומן

שרת ה-MCP של Calendar משתמש במדד להקצאת עלויות של שאילתות. בטבלאות הבאות מפורטת עלות השאילתה לכל שיטה של שרת ה-MCP של Calendar לפי קטע:

מכסות של תוכנית השותפים של Google ליומן

יש שני סוגים של מכסות:

• לדקה לכל פרויקט: העלות של השאילתה בפרויקט בענן למשך דקה אחת.

• לדקה לכל משתמש לכל פרויקט: זו העלות של השאילתה שכל משתמש בפרויקט Cloud יכול לצבור בדקה אחת.

בטבלה הבאה מפורטות המכסות האלה:

סוג מכסת השימוש	עלות שאילתה
לדקה לכל פרויקט	10,000
לדקה לכל משתמש לכל פרויקט	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

מידע נוסף זמין במאמר Calendar MCP API reference.

נושאים קשורים

• שליחת בקשות באצווה
• שיפור הביצועים
• איך נמנעים ממגבלות השימוש ביומן