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