מכסות ומגבלות שימוש

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

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

אם הבקשות יושלמו בתוך פרק זמן קבוע, יש לשלוח את הבקשות במקביל או להשתמש במספר שרשורים באפליקציית Java או C#. לדוגמה, בקשות מקבילות הן בקשות לקבוצות קטנות של אימיילים ממשתמשים שונים, במקום להוסיף או להסיר הרבה אימיילים בבת אחת. במקרה של שרשורים, כדאי להתחיל עם 10 שרשורים, שרשור אחד לכל אימייל של משתמש. הערה: להמלצה על שרשור יש יתרונות שונים והיא לא מועילה לכל מצבי API. אם מספר הבקשות גבוה מדי, שגיאות במכסה מתרחשות. דוגמה נוספת לסירוב היא ה-API של ביקורת האימייל לקצב ההעלאה המקסימלי של הודעות. קצב ההעלאה הוא בקשת API אחת – לכל שנייה – לכל משתמש, בלי קשר למספר השרשורים שמגישים את בקשות ההעלאה.

לגבי כל השגיאות המבוססות על זמן (עד N דברים ב-N שניות לכל שרשור), במיוחד השגיאות בקוד הסטטוס של 503, מומלץ שהקוד שלך יאתר את החריגה ובעזרת אלגוריתם השהיה מעריכית יש להמתין מעט לעיכוב לפני ביצוע השיחה שנכשלה. דוגמה ל-Email Audit API לשרשור אחד היא להמתין 5 שניות ולנסות שוב את השיחה שנכשלה. אם הבקשה תתבצע בהצלחה, יש לחזור על הדפוס הזה לגבי השרשורים האחרים. אם הבקשה השנייה לא תבוצע בהצלחה, הבקשה שלך תקטן בהתאם לתדירות הבקשות עד שהשיחה תושלם. לדוגמה, אפשר להאריך את הזמן שחלף מ-5 שניות ל-10 שניות ולנסות לבצע שוב את השיחה שנכשלה. כמו כן, יש להגדיר מגבלה ולנסות שוב. לדוגמה, אפשר לנסות לשלוח בקשה 5 עד 7 פעמים עם עיכובים שונים לפני שהאפליקציה תחזיר שגיאה למשתמש.

בטבלה הבאה מפורטות המגבלות שחלות על Email Audit API:

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

בטבלה הבאה מפורטות המכסות ל-Email Audit API:

קטגוריות מכסות של API	מכסות
אסימוני אימות של התחברות לחשבון	תקף ל-24 שעות. השגיאה היא 401 token expired.
פורמטים של תאריכים	צריך להמיר את כל התאריכים לפורמט תואם של קואורדינטות אוניברסליות (UTC) לפני שמשתמשים בהם ב-Email Audit API. מידע נוסף זמין במאמר ממיר UTC.
קובצי תיבת דואר מוצפנים, EXPIRED סיכומים וקובצי ייצוא	Google שומרת את קובצי תיבת הדואר הנכנס המוצפנים למשך 3 שבועות. אחר כך הן יימחקו. מנהל הדומיין אחראי להוריד את קובצי תיבת הדואר בפרק הזמן הזה.
קובצי תיבת דואר מוצפנים, פורמט	קובצי תיבת דואר מוצפנים מוצפנים בפורמט mbox.
קובצי תיבת דואר מוצפנים, בקשות מקסימליות ליצירה	המספר הכולל של בקשות לייצוא של תיבת דואר ביום הוא סך הכול 100 בקשות מכל האדמינים בדומיין.
חלוקה לדפים – קובץ קובץ מוצפן	כששולחים בקשה לקבלת סטטוס של כל הבקשות בתיבת דואר, התשובות יכולות להחזיר כמויות גדולות של נתונים. ה-API של ביקורת האימייל מקבץ את הנתונים האלה לדפים כאשר כל דף מכיל עד 100 רשומות, ומזהה URI בתג link rel='next' שמפנה לדף התוצאות הבא. כשאתם מפתחים את אפליקציית הלקוח שלכם, הקוד צריך לנהל את התוצאות הנוספות האלה.
מעקב אחר אימייל	המספר המקסימלי של בקשות למעקב אחר אימייל ביום הוא 1,500. המגבלה הזו מתייחסת לדומיין והיא כוללת את כל הבקשות שנשלחו על ידי מנהל מערכת במהלך היום.
מפתח ציבורי	ממשק ה-API לביקורת אימייל תומך במפתח אחד בלבד. המפתח הציבורי משתמש בתוכנת GNU Privacy Guard (GPG). הוא בפורמט PGP והוא מפתח הצפנת RSA מקודד ASCII. לפני העלאת המפתח הציבורי צריך קודם להמיר אותו למחרוזת בקידוד Base64. קובץ המפתח הציבורי צריך להיכתב עם charset US-ASCII, (IANA שם charset מועדף ל-ASCII).
מתבצע חיפוש	הפרמטרים searchQuery ו-includeDeleted הם לא כוללים ערכים הדדיים. לא ניתן לבצע שאילתת חיפוש אם includeDeleted="true".