ההגבלות והמכסות מגנות על התשתית של Google מפני תהליך אוטומטי שמשתמש ב-Reports API בצורה לא הולמת. בקשות מוגזמות מ-API יכולות לנבוע משגיאת הקלדה תמימה, או ממערכת לא יעילה ששולחת קריאות מיותרות ל-API. לא משנה מה הסיבה, חסימת תנועה ממקור מסוים אחרי שהיא מגיעה לרמה מסוימת נחוצה כדי לשמור על תקינות המערכת של Google Workspace. היא מבטיחה שפעולות של מפתח אחד לא ישפיעו לרעה על הקהילה הרחבה יותר.
במקרה לא סביר שבקשת ה-API תיכשל, תקבלו תגובה עם קוד סטטוס HTTP. קוד סטטוס 403 כולל מידע על שגיאה שקשורה לקלט שגוי, וקוד סטטוס 503 כולל מידע על שגיאה שמציין אילו מכסות של API חרגו. התשובות האלה מאפשרות לאפליקציה המותאמת אישית לזהות את השגיאות ולנקוט פעולה מתאימה.
אם הבקשות שלכם צריכות להסתיים בפרק זמן קבוע, אתם יכולים לשלוח את הבקשות במקביל או להשתמש בכמה שרשורים באפליקציית Java או C#. דוגמה לבקשות מקבילות היא בקשה של קבוצות קטנות של אימיילים ממשתמשים שונים, במקום להוסיף או להסיר הרבה אימיילים ממשתמש אחד בו-זמנית. במקרה של שרשורים, כדאי להתחיל עם 10 שרשורים, שכל אחד מהם הוא אימייל של משתמש. הערה: להמלצה על שרשור יש חסרונות, והיא לא שימושית בכל המצבים שקשורים ל-API. אם מספר הבקשות יהיה גבוה מדי, יוצגו שגיאות שקשורות למכסה.
לכל השגיאות שמבוססות על זמן (מקסימום N פעולות ל-N שניות לכל שרשור), במיוחד שגיאות עם קוד סטטוס 503, מומלץ שהקוד יתפוס את החריגה וישתמש באלגוריתם של השהיה מעריכית לפני ניסיון חוזר כדי להמתין פרק זמן קצר לפני שינסה שוב לבצע את הקריאה שנכשלה. דוגמה ל-Reports API עבור שרשור אחד היא להמתין 5 שניות ולנסות שוב את הקריאה שנכשלה. אם הבקשה מצליחה, חוזרים על התבנית הזו עבור השרשורים האחרים. אם הבקשה השנייה לא מצליחה, האפליקציה צריכה להקטין את תדירות הבקשות עד שהשיחה תצליח. לדוגמה, אפשר להגדיל את העיכוב הראשוני של 5 שניות ל-10 שניות ולנסות שוב להתקשר. כמו כן, מגדירים מגבלת ניסיונות חוזרים. לדוגמה, כדאי לנסות לשלוח בקשה 5 עד 7 פעמים עם זמני השהיה שונים לפני שהאפליקציה מחזירה שגיאה למשתמש.
מגבלות
| קטגוריות של מגבלות API | מגבלות |
|---|---|
| דיווח על שיעורי QPS ו-QPD | ה-API מגביל את מספר הבקשות לפרויקט שלכם ב-Google Cloud.
ערך ברירת המחדל שמוגדר במסוף Google Cloud הוא 2,400 שאילתות לדקה לכל משתמש לכל פרויקט ב-Google Cloud. אפשר להגדיל את המגבלה הזו מדף המכסות של Admin SDK API בפרויקט Google Cloud.
אם חורגים מהמגבלות האלה, השרת מחזיר קוד סטטוס HTTP 503. כדאי להשתמש באלגוריתם של השהיה מעריכית לפני ניסיון חוזר (exponential backoff) כשמנסים לשלוח שוב את הבקשות. |
מגבלות נוספות ל-activities.list |
ל-API activities.list יש מגבלה נוספת של 250 שאילתות סינון לדקה (15,000 שאילתות סינון לשעה). שאילתת סינון
היא בקשת API שמכילה לפחות אחד מהפרמטרים הבאים של השאילתה:
|
| קטגוריות של מכסות ל-API | מכסות |
| maxResults | מספר הרשומות שמופיעות בכל דף בתשובת API הוא בין 0 ל-1,000 רשומות. ברירת המחדל היא 1,000 רשומות. |
סוגים אחרים של מגבלות
| סוגים אחרים של מגבלות | מגבלות והנחיות |
|---|---|
| פורמט נתונים, ברירת מחדל | פורמט הנתונים שמוגדר כברירת מחדל הוא JSON. ה-API תומך גם בפורמט Atom. |
| בקשות לא מורשות | Google לא מאפשרת בקשות לא מורשות ל-API. בקשה נחשבת לא מורשית אם לא מסופק טוקן הרשאה. מידע נוסף זמין במאמר בנושא אישור בקשות. |
| הודעות אזהרה |
|
שיטות מומלצות לשימוש בשיטה activities.list
השיטה activities.list מיועדת לשימוש בחקירות ביקורת. כדי לקבל את הביצועים הטובים ביותר, הבקשה צריכה לכלול טווח זמן באמצעות הפרמטרים startTime ו-endTime. טווחים צרים יותר של שעות יביאו לזמני תגובה מהירים יותר באופן משמעותי. השיטה הזו לא מיועדת לאחזור של יומני ביקורת בכמויות גדולות. אם אתם ממצים באופן קבוע את מכסת הבקשות של המסנן activities.list, כדאי לשקול את האפשרויות הבאות:
- מגדירים ייצוא של יומנים מ-Google Workspace ל-BigQuery ומשתמשים בממשקי ה-API של שאילתות המתקדמים של BigQuery כדי לאחזר ולנתח את הנתונים שאתם צריכים ללא מגבלות על מכסת ה-API.
- במקום להשתמש בבקשות סינון, אפשר להשתמש בבקשות ללא סינון עם טווח זמן ולבצע סינון בצד הלקוח (כלומר, להשתמש בלוגיקת הסינון באפליקציה). כך תוכלו לעבור את המגבלה של 250 שאילתות סינון לדקה, אבל עדיין תחול עליכם המגבלה של 2,400 שאילתות לדקה לכל משתמש לכל פרויקט ב-Google Cloud.