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

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

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

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

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

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

השהיה מעריכית לפני ניסיון חוזר (exponential backoff) הוא התהליך של לקוח שמנסה מדי פעם לשלוח בקשה שנכשלה למשך פרק זמן הולך וגדל. זוהי אסטרטגיה סטנדרטית לטיפול בשגיאות באפליקציות רשת. השימוש בהשהיה מעריכית לפני ניסיון חוזר (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 בקשות בשנייה. 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 יופעל. אפשר להשתמש במסוף 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 לא מאפשר מחזור בחברויות בקבוצות. לדוגמה, אם group1 הוא חברה בקבוצה 2, הקבוצה 2 לא יכולה להיות חברה בקבוצה 1.