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

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

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

אם הבקשות שלכם צריכות להסתיים בפרק זמן קבוע, אתם יכולים לשלוח את הבקשות במקביל או להשתמש בכמה שרשורים באפליקציית Java או C#. דוגמה לבקשות מקבילות היא בקשה של קבוצות קטנות של אימיילים ממשתמשים שונים, במקום להוסיף או להסיר הרבה אימיילים ממשתמש אחד בו-זמנית. במקרה של שרשורים, כדאי להתחיל עם 10 שרשורים, שרשור אחד לכל כתובת אימייל של משתמש. הערה: להמלצה על שרשור יש חסרונות, והיא לא שימושית בכל המקרים שקשורים ל-API. אם מספר הבקשות גבוה מדי, מתרחשות שגיאות שקשורות למכסה. דוגמה נוספת לפשרה היא המכסה של Email Audit 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	מכסות
טוקנים של אימות ClientLogin	בתוקף ל-24 שעות. השגיאה היא 401 token expired.
פורמטים של תאריך	צריך להמיר את כל התאריכים לפורמט של זמן אוניברסלי מתואם (UTC) לפני שמשתמשים בהם ב-Email Audit API. למידע נוסף אפשר לעיין בכלי להמרת תאריכים ל-UTC.
קבצים מוצפנים של תיבת הדואר, סיכומים וקבצים לייצואEXPIRED	‫Google שומרת את הקבצים המוצפנים של תיבת הדואר למשך 3 שבועות. אחרי התקופה הזו, הם נמחקים. באחריות האדמין של הדומיין להוריד את הקבצים האלה של תיבת הדואר במהלך התקופה הזו.
קבצים מוצפנים של תיבת דואר, פורמט	קבצים מוצפנים של תיבת דואר הם בפורמט mbox.
קבצים מוצפנים של תיבת דואר, בקשות ליצירת קבצים	מספר הבקשות המקסימלי ליצירת ייצוא של תיבת דואר ביום הוא 100 בקשות בסך הכול מכל האדמינים בדומיין.
סטטוס של קובץ תיבת דואר מוצפן, חלוקה לדפים	כשמבקשים את הסטטוס של כל הבקשות לתיבות דואר, התשובות יכולות להחזיר כמויות גדולות של נתונים. ממשק ה-API של Email Audit מחלק את הנתונים האלה לדפים, כשכל דף מכיל עד 100 רשומות, ו-URI בתג link rel='next'מפנה לדף התוצאות הבא. במהלך פיתוח אפליקציית הלקוח, הקוד צריך לנהל את התוצאות הנוספות האלה.
מעקב אחר אימייל	המספר המקסימלי של בקשות לניטור אימייל ביום הוא 1,500. המגבלה הזו היא לדומיין וכוללת את כל הבקשות שמוגשות על ידי כל אדמין במהלך היום.
מפתח ציבורי	ה-API של ביקורת האימייל תומך רק במפתח אחד. המפתח הציבורי משתמש בתוכנת GNU Privacy Guard‏ (GPG). הוא בפורמט PGP והוא מפתח הצפנה מסוג RSA בקידוד ASCII. לפני שמעלים את המפתח הציבורי, צריך להמיר אותו למחרוזת בקידוד base64. קובץ המפתח הציבורי צריך להיות בקידוד התווים US-ASCII, (שם קידוד התווים המועדף של IANA עבור ASCII).
חיפוש	הפרמטרים searchQuery ו-includeDeleted הם בלעדיים. אי אפשר להזין שאילתת חיפוש אם includeDeleted="true".