מגבלות שימוש

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

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

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

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

מכסות ל-Calendar API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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