מגבלות שימוש

‫Google Sheets API הוא שירות משותף, ואנחנו מגבילים את המכסות כדי להגן על הביצועים הכוללים של מערכת Google Workspace לכל המשתמשים.

מגבלות המכסה

ל-Sheets API אין מגבלות גודל קשיחות לבקשת API, אבל יכול להיות שהמשתמשים ייתקלו במגבלות מרכיבי עיבוד שונים שלא נשלטים על ידי Google Sheets. כדי לזרז את הבקשות, מומלץ להגביל את המטען הייעודי (payload) ל-2MB.

ל-Sheets API יש מכסות לקצב שליחת בקשות לדקה, והן מתחדשות כל דקה. לדוגמה, יש הגבלה של 300 בקשות קריאה לדקה לכל פרויקט. אם האפליקציה שולחת 350 בקשות בדקה אחת, 50 הבקשות הנוספות חורגות מהמכסה ומייצרות תגובה עם קוד סטטוס HTTP‏ 429: Too many requests. במקרה כזה, צריך להשתמש באלגוריתם של השהיה מעריכית לפני ניסיון חוזר (exponential backoff). אחרי דקה, אפשר להריץ שוב בקשות.

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

מכסות
קריאת בקשות
לדקה לכל פרויקט 300
לדקה, למשתמש, לפרויקט 60
כתיבת בקשות
לדקה לכל פרויקט 300
לדקה, למשתמש, לפרויקט 60

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

התנהגות ומגבלות

כשעובדים עם Sheets API, חשוב לשים לב להתנהגות ולמגבלות הבאות שמשפיעות על המכסות:

  • בקשות קריאה הן קריאות לכל שיטה שמחלצת נתונים מגיליון אלקטרוני, כמו get או search. בקשות כתיבה הן קריאות לכל שיטה שמשנה גיליון אלקטרוני, כמו update,‏ clear או copyTo.

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

  • כל הבקשות ל-Sheets מיושמות באופן אטומי. כלומר, אם בקשה כלשהי לא תקינה, העדכון כולו ייכשל ואף אחד מהשינויים (שיכול להיות שהם תלויים זה בזה) לא יחול.

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

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

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

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

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

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

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

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

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

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

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

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