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, או מאטים את קצב שליחת הבקשות באמצעות השהיה מעריכית לפני ניסיון חוזר (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.
מחיקת משתמשים אתם יכולים למחוק עד 5 משתמשים בכל דומיין בשנייה באמצעות Directory API. זו מגבלה על שירות לקצה העורפי לכל דומיין, ואי אפשר לשנות אותה במכסות הפרויקט במסוף Google Cloud. כששולחים בקשות Batch, צריך לוודא שסך כל הפעולות בכל האצוות לא עולה על 5 שאילתות לשנייה (QPS).
מחיקת חברים מהקבוצה אתם יכולים למחוק עד 30 חברים בקבוצה בכל דומיין בשנייה באמצעות Directory API. זו מגבלה על שירות לקצה העורפי לכל דומיין, ואי אפשר לשנות אותה במכסות הפרויקט במסוף Google Cloud. כששולחים בקשות Batch, צריך לוודא שסך כל הפעולות בכל האצוות לא עולה על 30 שאילתות לשנייה (QPS).
קבוצה נוספה כחברה בקבוצה אחרת יכול להיות עיכוב של עד 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, מומלץ להשתמש בדומיין של העסק בתור הדומיין הראשי, ולשמור את הדומיינים האחרים לשימושים מיוחדים כמו פיילוטים ובדיקות.
    • כל הסופר-אדמינים יכולים לנהל את החשבון כולו.
    • ה-API לא יכול לשנות או להעביר את הדומיין הראשי של חשבון Google Workspace. עם זאת, ה-API יכול לשנות את השם של חשבון המשתמש, ולשנות את כתובת האימייל שלו מדומיין אחד לאחר.
    • בחשבונות Google Workspace, יש לכם 21 ימים לאמת את הבעלות על הדומיין הראשי. בדומיינים נוספים, אתם צריכים לאמת את הבעלות על הדומיין לפני שתוכלו להשתמש בו ככתובת האימייל הראשית של המשתמש. במקרים כאלה, תקופת החסד של 21 הימים לא חלה.
    • בגרסה הזו של ה-API, ההגדרות של הדומיין הראשי חלות על כל הדומיינים שמשויכים לחשבון, חוץ מגישת המשתמשים לשירותי Google Workspace.
  • דומיינים נוספים בחשבון – אחרי שקובעים את הדומיין הראשי ומגדירים את החשבון, אפשר להוסיף לחשבון דומיינים נוספים. בדומיינים נוספים, אמתו את הבעלות שלכם כשאתם מגדירים את הדומיין הזה ולפני שאתם משתמשים בדומיין לכתובת האימייל הראשית של המשתמש.
  • דומיין הבית של המשתמש – הדומיין שמופיע בכתובת האימייל הראשית של המשתמש הוא דומיין הבית שלו. הדומיין הזה יכול להיות כל דומיין בחשבון, כולל הדומיין הראשי.
כדי לראות את המגבלות העדכניות על כמה דומיינים, אפשר לעיין במאמר מגבלות בעבודה עם כמה דומיינים. המידע הזה כולל פרטים על דומיינים חלופיים, מיזוג חשבונות וכו'.
אזהרות, חברי הקבוצה ‫GROUP_CANNOT_CONTAIN_CYCLE – ה-API לא מאפשר מעגל בחברויות בקבוצה. לדוגמה, אם קבוצה 1 היא חברה בקבוצה 2, קבוצה 2 לא יכולה להיות חברה בקבוצה 1.