Directory API: מגבלות ומכסות

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

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

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

קוד	סיבה	תיאור	מה מומלץ לעשות?
403	userRateLimitExceeded	מציין שחרגו מהגבלת הקצב של יצירת בקשות לכל משתמש. ערך ברירת המחדל שמוגדר במסוף Google Cloud הוא 2,400 שאילתות לדקה לכל משתמש לכל פרויקט ב-Google Cloud.	להגדיל את המגבלות לכל משתמש בדף המכסות של Admin SDK API בפרויקט ב-Google Cloud, או להאט את הקצב שבו שולחים את הבקשות באמצעות השהיה מעריכית.
403	quotaExceeded	הקוד הזה מציין שהגעתם למגבלה של בקשות בו-זמניות לפעולה מסוימת.	מנסים שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). צריך להאט את הקצב שבו שולחים את הבקשות.
429	rateLimitExceeded	הקוד הזה מציין שהגעתם למגבלה של בקשות בו-זמניות לפעולה מסוימת.	מנסים שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). צריך להאט את הקצב שבו שולחים את הבקשות. המגבלה הזו חלה על כל חשבון Google Workspace, ולא על כל לקוח API או על כל משתמש. אי אפשר להגדיל את המגבלה הזו.

הטמעת השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

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

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

1. שליחת בקשה ל-API
2. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
3. צריך להמתין 1s + random_number_milliseconds שניות
4. בקשה לניסיון חוזר
5. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
6. המתנה של 2 שניות + random_number_milliseconds שניות
7. בקשה לניסיון חוזר
8. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
9. המתנה של 4 שניות + random_number_milliseconds שניות
10. בקשה לניסיון חוזר
11. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
12. צריך להמתין 8 שניות + random_number_milliseconds שניות
13. בקשה לניסיון חוזר
14. קבלת תגובת שגיאה עם קוד שגיאה שניתן לנסות שוב
15. ממתינים 16 שניות + random_number_milliseconds שניות
16. בקשה לניסיון חוזר
17. אם השגיאה עדיין מופיעה, מפסיקים את הפעולה ומתעדים את השגיאה ביומן.

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

הערה: זמן ההמתנה הוא תמיד (2 ^ n) + random_number_milliseconds, כאשר n הוא מספר שלם שגדל באופן מונוטוני ומוגדר בהתחלה כ-0. n גדל ב-1 בכל חזרה (כל בקשה).

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

מגבלות ומכסות ל-API

קטגוריות של מגבלות API	מגבלות
יצירת משתמשים	אי אפשר ליצור יותר מ-10 משתמשים לדומיין לשנייה באמצעות Directory API.
קבוצה שנוספה כחברה בקבוצה אחרת	יכול להיות עיכוב של עד 10 דקות עד שהחברים בתת-הקבוצה יופיעו כחברים בקבוצת ההורה. המגבלה הזו עשויה להשתנות בהתאם לקיבולת המערכת.
מכשירים ניידים	באמצעות Directory API, אפשר לבצע עד 100 פעולות: 20 בקשות פעולה לשנייה. 20 בקשות מחיקה לשנייה. 10 בקשות GET לשנייה. 10 בקשות לרשימות לשנייה.
שינוי שמות של משתמשים	תהליך ההפצה לכל השירותים עשוי להימשך עד 10 דקות. לפני שמשנה את שם המשתמש, מומלץ להוציא את המשתמש מכל הסשנים והשירותים בדפדפן. פרטים נוספים זמינים במאמר עדכון משתמשים.
יצירה ועדכון של יחידות ארגוניות	אי אפשר ליצור או לעדכן יותר מיחידת ארגון אחת לכל לקוח בשנייה באמצעות Directory API. היררכיית היחידות הארגוניות של הלקוח מוגבלת ל-35 רמות עומק. המספר הכולל של היחידות הארגוניות לכל לקוח לא יכול לחרוג מ-40,000.
קטגוריות של מכסות ל-API	מכסות
מכשירי Chrome annotatedLocation, תווים לכל היותר	מספר התווים המקסימלי של פרטי המיקום של מכשיר הוא 200.
מכשירי Chrome notes, תווים לכל היותר	מספר התווים המקסימלי של פרטי ההערות של מכשיר הוא 500.
מכשירי Chrome, עד user תווים	מספר התווים המקסימלי בשם של משתמש במכשיר הוא 100.
דומיינים חלופיים, מקסימום	המספר המקסימלי של דומיינים חלופיים הוא 20.
קבוצות, תיאור	מספר התווים המקסימלי בתיאור הוא 4,096.
קבוצות, לכל חשבון	בחשבון במהדורת החינם הקודמת של G Suite, מספר הקבוצות מוגבל ל-10. במהדורות אחרות אין הגבלה על מספר הקבוצות.
קבוצות, חברים בכל קבוצה	בחשבון במהדורת החינם הקודמת של G Suite, קבוצה יכולה להכיל עד 100 חברים. במהדורות אחרות אין הגבלה על מספר החברים בקבוצה. במאמר הסבר על כללי המדיניות והמגבלות בקבוצות Google מפורטות המגבלות על מספר החברים בקבוצה לכל משתמש.
מחרוזת השאילתה maxResults	ה-API מחזיר: Chrome ומכשירים ניידים – ברירת מחדל ומספר מקסימלי של 100 רשומות לכל דף. קבוצות וחברי קבוצות – ברירת המחדל היא 200 רשומות לכל דף, והמספר המקסימלי הוא 200 רשומות. משתמשים – ברירת המחדל היא 100 רשומות לכל היותר 500 רשומות לכל דף. במשאבים של כתובת האימייל החלופית של המשתמש ובמשאבים של היחידה הארגונית לא נעשה שימוש בפיצול תגובות לדפים. כל כתובות האימייל הראשיות של המשתמשים מוחזרות בסדר אלפביתי, והתשובות לא תלויות רישיות.
מספר דומיינים, מספר הדומיינים המקסימלי שמותר בחשבון	600 (דומיין ראשי אחד + 599 דומיינים נוספים)
יחידה ארגונית, מספר המשתמשים המקסימלי שניתן להעביר בבת אחת	אפשר להעביר 20 משתמשים בכל פעם. בנוסף, כתובות האימייל הראשיות של המשתמש כבר צריכות להיות בחשבון.
כינויים של משתמשים	המספר הכולל של כתובות אימייל חלופיות שמותר להוסיף לכל חשבון משתמש הוא 30.
כתובות אימייל חלופיות של משתמשים, באמצעות כתובת אימייל חלופית שנמחקה	אפשר להשתמש שוב בשם המשתמש החלופי שנמחק באופן מיידי.

סוגים אחרים של מגבלות	מגבלות והנחיות
חיוב ויצירת משתמשים	למשתמשים בתוכנית גמישה של Google Workspace, יצירת משתמשים באמצעות ה-API הזה תהיה בעלת השפעה כספית ותגרום לחיוב בחשבון לחיוב של הלקוח. לדוגמה, אם יש לכם תוכנית גמישה ב-Google Workspace, יצירת 10 משתמשים תוביל לחיוב על 10 רישיונות Google Workspace בחשבון שלכם, לפי החלק היחסי מהזמן שבו היצירה בוצעה. אם יש לכם תוכנית שנתית, כבר התחייבתם לשלם מראש על מספר מסוים של רישיונות, ותוכלו ליצור רק את מספר המשתמשים שמתאים להתחייבות שלכם. מידע נוסף על תוכניות חיוב ועל החשבון לחיוב זמין במרכז העזרה לניהול.
שם פרטי ושם משפחה	האורך המקסימלי של השם הפרטי ושם המשפחה הוא 40 תווים. הם תומכים בתווים של Unicode/UTF-8, ויכולים להכיל רווחים, אותיות (a-z), מספרים (0-9), מקפים (-), קווים נטויים (/) ונקודות (.). מידע נוסף על כללי השימוש בתווים זמין במרכז העזרה לניהול.
קבוצות, מחיקה	מחיקת קבוצה לא מוחקת את חשבונות המשתמשים של חברי הקבוצה.
קבוצות וחברי קבוצה, שינוי כתובת האימייל	בגרסה הזו של ה-API, אפשר לשנות את כתובת האימייל של קבוצה לפני הפעלת שירות Google Workspace. משתמשים במסוף Admin כדי לשנות את כתובת האימייל של חבר בקבוצה. אחרי השינוי, השינויים בכתובת האימייל ישתקפו ב-API באופן אוטומטי.
קבוצות, הגדרות	הגדרות הגישה לקבוצות, אפשרויות השיתוף, המעקב והארכיון של הדיונים מנוהלים דרך מסוף Admin. מידע נוסף על הגדרות הקבוצות זמין במרכז העזרה לניהול.
קבוצות, שליחת הודעות	כדי למנוע ספאם ושימוש לרעה באימייל, Google מגבילה את מספר ההודעות שאפשר לשלוח בו-זמנית לנמענים חיצוניים. אם שולחים הודעה לקבוצה, כל חבר חיצוני נספר כנמען אחד. מידע נוסף זמין במאמרים מגבלות על שליחת אימיילים ואיך למנוע חסימה או העברה לספאם של אימייל שנשלח למשתמשי Gmail .
קבוצות, שליחת הודעות NDR	אי אפשר לשלוח או להעביר לקבוצה הודעות NDR (דיווחי אי-מסירה), שנקראות גם 'הודעות חזרה'.
קבוצות שנוצרו על ידי משתמשים, מגבלות	למידע על מגבלות על קבוצות שנוצרו על ידי משתמשים, אפשר לעיין במרכז העזרה לניהול.
יחידה ארגונית, הפעלה/השבתה של שירותים	במסוף Admin אפשר להפעיל ולהשבית שירותים ביחידה ארגונית.
סיסמאות	יכול להכיל כל שילוב של תווים. צריך להזין לפחות 8 תווים. האורך המקסימלי הוא 100 תווים.
תמונות	בגרסה הזו של ה-API, תמונה היא תמונת הפרופיל האחרונה של המשתמש ב-Google.
שמות משתמשים	שמות משתמשים יכולים להכיל אותיות (a-z), מספרים (0-9), מקפים (-), קווים תחתונים (_) ונקודות (.). ב-Google Workspace אפשר להשתמש בנקודות, בניגוד ל-Gmail. שם משתמש לא יכול להכיל סימן שוויון (=), סוגריים זוויתיים (<,>) או יותר מנקודה אחת (.) ברצף. מידע נוסף זמין במרכז העזרה לניהול.
שמות משתמשים, שינוי שמות	אחרי שינוי השם, כל ההזמנות לשיחות ש-Google Hangouts זוכרת יוסרו. המשתמש יצטרך לבקש שוב הרשאה לצ'אט עם חברים. שם המשתמש הישן נשמר ככתובת אימייל חלופית כדי להבטיח המשך העברת אימיילים במקרה של הגדרות העברה של אימיילים, והוא לא יהיה זמין כשם משתמש חדש. פרטים חשובים על ההשפעה של שינוי השם של משתמשים זמינים במרכז העזרה לניהול. משתמשים בפעולה מחיקת כתובת אימייל חלופית של משתמש כדי להסיר את כתובת האימייל החלופית אחרי שינוי השם.
משתמשים בכמה דומיינים	חשבון Google Workspace יכול לכלול כל אחד מהדומיינים שלכם. בחשבון עם כמה דומיינים, משתמשים בדומיין אחד יכולים לשתף שירותים עם משתמשים בדומיינים אחרים בחשבון. רכיבים של דומיינים מרובים הם: הדומיין הראשי – הדומיין הראשי של החשבון הוא הדומיין של האדמין שהסכים להסכם התנאים וההגבלות של Google Workspace. הדומיין הזה נמצא ברמת החשבון ביחידה הארגונית ברמה העליונה. כשנרשמים לחשבון Google Workspace, מומלץ להשתמש בדומיין העסקי בתור הדומיין הראשי, ולהשאיר את הדומיינים האחרים לשימושים מיוחדים כמו תוכניות פיילוט ובדיקות. כל הסופר-אדמינים יכולים לנהל את החשבון המלא. ה-API לא יכול לשנות או להעביר את הדומיין הראשי של חשבון Google Workspace. עם זאת, ה-API יכול לשנות את השם של חשבון משתמש, ולשנות את כתובת האימייל שלו מדומיין אחד לדומיין אחר. בחשבונות Google Workspace, יש לכם 21 יום לאמת את הבעלות על הדומיין הראשי. כדי להשתמש בדומיינים נוספים ככתובת האימייל הראשית של משתמשים, צריך לאמת את הבעלות על הדומיינים האלה. במקרים כאלה, תקופת החסד של 21 יום לא חלה. בגרסה הזו של ה-API, ההגדרות של הדומיין הראשי חלות על כל הדומיינים המשויכים לחשבון, מלבד גישת המשתמשים לשירותי Google Workspace. דומיינים נוספים בחשבון – אחרי שמגדירים את הדומיין הראשי ומגדירים את החשבון, אפשר להוסיף את הדומיינים הנוספים לחשבון. לגבי דומיינים נוספים, מאמתים את הבעלות כשמגדירים את הדומיין הזה, וגם לפני שמשתמשים בדומיין לכתובת האימייל הראשית של משתמש. הדומיין הביתי של המשתמש – הדומיין שבו נעשה שימוש בכתובת האימייל הראשית של המשתמש הוא הדומיין הביתי של המשתמש. הדומיין הזה יכול להיות כל דומיין בחשבון, כולל הדומיין הראשי. המגבלות העדכניות ביותר לגבי כמה דומיינים מפורטות במאמר מגבלות לגבי כמה דומיינים. זה כולל מידע על כתובות אימייל חלופיות של דומיינים, על מיזוג חשבונות וכו'.
אזהרות, חברי קבוצה	GROUP_CANNOT_CONTAIN_CYCLE – ממשק ה-API לא מאפשר מחזור בחברות בקבוצות. לדוגמה, אם קבוצה1 היא חברה בקבוצה2, קבוצה2 לא יכולה להיות חברה בקבוצה1.