מגבלות שימוש

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

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

ההודעה המלאה מופיעה במאמר עדכוני אבטחה וכלים לסוכנים למפתחים ב-Google Workspace.

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

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

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

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

מכסות ל-Calendar API

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

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

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

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

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

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

סף חיוב יומי

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

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

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

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

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

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

פתרון שגיאות במכסות מבוססות-זמן

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

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

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

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

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

כאשר:

• זמן ההמתנה הוא 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 זמין ללא עלות נוספת. בהמשך שנת 2026, חריגה ממגבלות הבקשות למכסות תגרום לחיובים בחשבון לחיוב ב-Google Cloud. מידע נוסף זמין במאמר המודל הסטנדרטי של Google Workspace לכלים ולממשקי API של סוכנים.

איך מבקשים להגדיל את המכסה

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

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

מידע נוסף זמין במשאבים הבאים:

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

פתרון בעיות

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי להשתמש ב-quotaUser לאכיפת מגבלות קצב של יצירת בקשות לכל משתמש, הבקשות צריכות לעמוד בדרישות הבאות:

• לכלול מפתח API שמוגבל לכתובת IP: מעבירים מפתח API בפרמטר השאילתה key, ומגדירים את המפתח הזה עם הגבלות על כתובות IP שמציינות את כתובות ה-IP הציבוריות של שרתי בק-אנד. אם לא תציינו את מפתח ה-API או לא תגדירו הגבלות על כתובות IP, ה-Calendar API יתעלם מ-quotaUser ויחייב את המכסה בחשבון המאומת (כמו חשבון השירות).

• השמטת הכותרת X-Goog-User-Project: לא שולחים כותרת HTTP מסוג X-Goog-User-Project בבקשות שמשתמשות ב-quotaUser. אם מציינים פרויקט של משתמש, הוא מבטל את מפתח ה-API לשיוך המכסה, ולכן Calendar API מתעלם מ-quotaUser.

מידע נוסף זמין במאמר הגבלת הבקשות לכל משתמש.

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

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

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

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

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

מכסות MCP ביומן Google

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

• לדקה לפרויקט: עלות השאילתה לפרויקט ב-Google Cloud לדקה.

• לדקה לכל משתמש בכל פרויקט: עלות השאילתה לפרויקט ב-Google Cloud לדקה, שכל משתמש ספציפי יכול להשתמש בה.

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

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

מכסות לערכת הכלים של MCP ביומן Google

בטבלה הבאה מפורטת עלות השאילתה לכל ערכת כלים של 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.

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

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