מגבלות ומכסות מגנות על התשתית של 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.