ל-Google Calendar API יש מכסות כדי לוודא שכל המשתמשים משתמשים בו בצורה הוגנת. יש שלוש הגבלות חשובות שחשוב להביא בחשבון כשמשתמשים ב-Calendar API:
- מכסות השימוש ב-API נאכפות לכל פרויקט ולכל משתמש. מידע נוסף זמין בקטע הבא.
- מגבלות כלליות לשימוש ביומן Google: חשוב להימנע ממגבלות השימוש ביומן Google.
- מגבלות תפעוליות: יכול להיות שתוגבל מהירות השליחה של הבקשות בכל שלב. לדוגמה, אם מנסים לכתוב ביומן אחד ברצף מהיר.
סוגי המכסות לשימוש ב-Calendar API
אנחנו אוכפים שני סוגים של מכסות:
- לדקה לכל פרויקט: זהו מספר הבקשות שהוגשו מהפרויקט שלכם ב-Google Cloud.
- לדקה, לכל פרויקט לכל משתמש: זהו מספר הבקשות שנשלחו על ידי משתמש מסוים בפרויקט ב-Cloud. המגבלה הזו נועדה לעזור לכם להבטיח חלוקה הוגנת של השימוש בין המשתמשים.
המכסות מחושבות לדקה באמצעות חלון הזזה, כך שפרץ מהיר של תנועה שחורג מהמכסה לדקה במהלך דקה אחת יוביל להגבלת הקצב במהלך החלון הבא, כדי להבטיח שהשימוש שלכם יישאר במסגרת המכסות בממוצע.
אם תחרגו מכל אחת מהמכסות, תהיה הגבלת קצב של יצירת הבקשות ותקבלו קוד סטטוס 403 usageLimits או קוד סטטוס 429 usageLimits בחזרה מהשאילתות. במקרה כזה, אפשר לבצע את הפעולות הבאות:
- חשוב לפעול לפי כל השיטות המומלצות: שימוש בהשהיה מעריכית לפני ניסיון חוזר, רנדומיזציה של דפוסי התנועה, שימוש בהתראות על מודעות דחיפה.
- אם הפרויקט שלכם מתרחב ויש לכם יותר משתמשים, תוכלו לבקש להגדיל את המכסה לכל פרויקט.
- אם מגיעים למכסה לכל משתמש, אפשר לבצע את הפעולות הבאות:
- אם אתם משתמשים בחשבון שירות, מקצים את העומס למשתמשים או מפצלים אותו בין כמה חשבונות שירות.
- אפשר לבקש להגדיל את המכסה לכל משתמש, אבל באופן כללי לא מומלץ להגדיל אותה מעבר לערך ברירת המחדל, כי האפליקציה עשויה להתחיל לחרוג מסוגים אחרים של מגבלות, למשל מגבלות כלליות לשימוש ביומן או מגבלות תפעוליות.
בקשה להגדלת מכסה
כדי להציג או לשנות את מגבלות השימוש בפרויקט, או כדי לבקש הגדלת מכסה:
- אם עדיין אין לכם חשבון לחיוב בפרויקט, צריך ליצור חשבון כזה.
- נכנסים לדף Enabled APIs בספריית ה-API במסוף API ובוחרים ממשק API מהרשימה.
- כדי להציג ולשנות הגדרות שקשורות למכסות, בוחרים באפשרות Quotas. כדי להציג את נתוני השימוש, בוחרים באפשרות שימוש.
שימוש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff)
אם נרצה לבקש מכם להאט את קצב הבקשות, נחזיר תגובה מסוג 403 'usageLimits' או תגובה מסוג 429 (ראו מסמכי התיעוד המלאים של השגיאות). זו לא שגיאה קטלנית, וניתן לנסות שוב את הבקשה לאחר פרק זמן קצר. אם הבקשות עדיין יגיעו מהר מדי, נבקש שוב וכן הלאה. כדי שהשיטה הזו תפעל כמו שצריך, חשוב שההשהיות בין הבקשות יגברו עם הזמן.
באופן כללי, כדאי להשתמש בהשהיה מעריכית לפני ניסיון חוזר קטועה. במסמכי העזרה של Cloud Storage מוסבר איך זה עובד ומה האלגוריתם המועדף. אם אתם משתמשים בספריית לקוח של Google, בדרך כלל הבעיה הזו מטופלת באופן אוטומטי. כדאי לעיין במסמכי העזרה של הספרייה. בדרך כלל, מומלץ להשתמש בהטמעה של הספרייה במקום לכתוב הטמעה משלכם.
רנדומיזציה של דפוסי התנועה
לקוחות של יומן Google נוטים לתנודות חדות בדפוסי התנועה, שנגרמות כתוצאה מכמה לקוחות שמבצעים פעולות בו-זמנית. לדוגמה, שיטה נפוצה ומוטעית של לקוח יומן היא לבצע סנכרון מלא בחצות. כמעט בטוח שזה יוביל לחריגה מהמכסה לדקה, וכתוצאה מכך תהיה הגבלת קצב שליחת הבקשות והשהיות.
כדי למנוע זאת, כדאי לפזר את התנועה לאורך היום, במידת האפשר. אם הלקוח צריך לבצע סנכרון יומי, צריך לבקש מהלקוח לקבוע שעה אקראית (שונה לכל לקוח). אם אתם צריכים לבצע פעולה באופן קבוע, כדאי לשנות את המרווח ב-25% לפחות או ליותר. כך תוכלו לחלק את התנועה בצורה שווה יותר ולספק חוויית משתמש טובה יותר.
שימוש בהתראות
תרחיש לדוגמה: אתם רוצים לבצע פעולה בכל פעם שמשהו משתנה ביומן של המשתמש. דפוס שלילי הוא לבצע סקרים חוזרים ונשנים של כל לוח שנה רצוי. הפעולה הזו תגרום לכך שכל המכסות ינוצלו במהירות רבה. לדוגמה, אם לאפליקציה יש 5,000 משתמשים והיא בודקת את היומן של כל משתמש פעם בדקה, תצטרכו מכסה של לפחות 5,000 פעולות לדקה עוד לפני שתבצעו עבודה כלשהי.
אפליקציות בצד השרת יכולות להירשם לקבלת התראות, וכך נוכל להודיע לכם כשמשהו מעניין קורה. הגדרת התכונות האלה מחייבת יותר עבודה, אבל הן מאפשרות לנצל את המכסה בצורה יעילה יותר ומספקות חוויית משתמש טובה יותר. חשוב לציין את eventType שרוצים לקבל עליו התראות. למידע נוסף, ראו התראות Push.
ניהול חשבונות תקין באמצעות חשבונות שירות
אם האפליקציה מבצעת בקשות באמצעות הענקת גישה ברמת הדומיין, כברירת מחדל החיוב של חשבון השירות מתבצע בהתאם למכסות 'בדקה, לכל פרויקט, לכל משתמש', ולא של המשתמש שאליו מתחזים. המשמעות היא שלחשבון השירות כנראה תיגמר המכסה והוא יוגבל בקצב שליחת הבקשות, גם אם הוא פועל בלוחות שנה של כמה משתמשים. כדי למנוע זאת, אפשר להשתמש בפרמטר quotaUser בכתובת ה-URL (או בכותרת ה-HTTP x-goog-quota-user) כדי לציין איזה משתמש יחויב. הוא משמש רק לחישוב המכסות. למידע נוסף, ראו הגבלת הבקשות לכל משתמש במסמכי התיעוד של Cloud.
בדיקת הטיפול במגבלות מכסה
כדי לוודא שהאפליקציה שלכם תוכל לטפל בצורה חלקה במצב שבו היא מגיעה למגבלות המכסות בפועל (למשל, על ידי ביצוע ניסיונות חוזרים עם השהיה מעריכית לפני ניסיון חוזר) וכדי למזער את ההפרעות הפוטנציאליות למשתמשים, מומלץ מאוד לבדוק את התרחיש הזה בסביבה אמיתית.
כדי שהבדיקה לא תפריע לשימוש האמיתי באפליקציה, מומלץ לרשום פרויקט נפרד לבדיקה בלבד ב-מסוף Google API ולהגדיר אותו באופן דומה לפרויקט הייצור. לאחר מכן תוכלו להגדיר מכסות נמוכות באופן מלאכותי לפרויקט הזה ולבחון את ההתנהגות של האפליקציה.
תמחור
כל השימוש ב-Google Calendar API זמין ללא עלות נוספת. אין חיובים נוספים על חריגה ממגבלות הבקשות במכסה, והחשבון לא מחויב.