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

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

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

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

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