מגבלות שימוש

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מכסות של שרת ה-MCP של Docs

שרת ה-MCP של Docs משתמש במדדים של בקשות קריאה וכתיבה. בטבלאות הבאות מפורטות המכסות ועלויות השאילתות לכל שיטה של שרת ה-MCP של Docs, לפי קטע:

מכסות של Docs MCP

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

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

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

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

מכסות של ערכת הכלים Docs MCP

בטבלה הבאה מפורטות עלויות השאילתות לכל docsmcp.googleapis.com ערכת כלים:

נקודת קצה כלי עלות שאילתה
/mcp/v1 read_doc בקשת קריאה אחת
update_doc בקשת כתיבה אחת

מידע נוסף מופיע במאמרי העזרה של Docs MCP API.