אתם צופים במסמכי התיעוד של Apigee Edge.
אפשר לעבור אל מסמכי התיעוד של Apigee X. מידע
מה
אפשר להשתמש במדיניות Quota כדי להגדיר את מספר הודעות הבקשה ש-API Proxy מאפשר במהלך תקופת זמן מסוימת, כמו דקה, שעה, יום, שבוע או חודש. אפשר להגדיר את המכסה כך שתהיה זהה לכל האפליקציות שמקבלות גישה לשרת ה-proxy של ה-API, או להגדיר את המכסה על סמך:
- המוצר שמכיל את שרת ה-API הפרוקסי
- האפליקציה ששולחת בקשה ל-API
- מפתחי האפליקציה
- קריטריונים רבים אחרים
אל תשתמשו במכסת נפח כדי להתגונן מפני עליות פתאומיות בתנועה הכוללת. לשם כך, משתמשים במדיניות Spike Arrest. מדיניות בנושא מניעת עליות פתאומיות בתנועה
סרטונים
בסרטונים האלה מוצג ניהול מכסות באמצעות מדיניות המכסות:
פתיח (New Edge)
פתיח (גרסה קלאסית של Edge)
מכסה דינמית
מבוזר וסינכרוני
משקל ההודעה
יומן
חלון מתגלגל
Flexi
מכסה מותנית
משתני זרימה
טיפול בשגיאות
דוגמאות
בדוגמאות הקוד הבאות של מדיניות אפשר לראות איך מתחילים ומסיימים תקופות מכסה על ידי:
מכסה דינמית נוספת
<Quota name="CheckQuota"> <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval> <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit> <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/> </Quota>
מכסות דינמיות מאפשרות לכם להגדיר מדיניות מכסות אחת שמחילה הגדרות שונות של מכסות על סמך מידע שמועבר למדיניות המכסות. מונח נוסף להגדרות מכסת השימוש בהקשר הזה הוא 'תוכנית שירות'. הקצאת הנפח הדינמית בודקת את 'תוכנית השירות' של האפליקציות ואז אוכפת את ההגדרות האלה.
הערה: אם מציינים גם ערך וגם הפניה לרכיב, ההפניה מקבלת עדיפות. אם ההפניה לא נפתרת בזמן הריצה, נעשה שימוש בערך.
לדוגמה, כשיוצרים מוצר API, אפשר להגדיר את מכסת ההקצאה המותרת, יחידת הזמן והמרווח. עם זאת, הגדרת הערכים האלה במוצר ה-API לא מחייבת את השימוש בהם ב-API proxy. צריך גם להוסיף מדיניות מכסה ל-API Proxy שקורא את הערכים האלה. מידע נוסף זמין במאמר בנושא יצירת מוצרי API.
בדוגמה שלמעלה, פרוקסי ה-API שמכיל את מדיניות המכסות משתמש במדיניות VerifyAPIKey
בשם verify-api-key כדי לאמת את מפתח ה-API שמועבר בבקשה.
Quota policy then accesses the flow variables from the VerifyAPIKey policy to read the quota
values set on the API product. מידע נוסף על משתני הזרימה של VerifyAPIKey זמין במאמר מדיניות Verify API Key.
אפשרות נוספת היא להגדיר מאפיינים מותאמים אישית למפתחים או לאפליקציות ספציפיות, ואז לקרוא את הערכים האלה במדיניות בנושא מכסות. לדוגמה, אם רוצים להגדיר ערכי מכסה שונים לכל מפתח. במקרה כזה, מגדירים מאפיינים מותאמים אישית אצל המפתח שמכילים את המגבלה, יחידת הזמן והמרווח. אחר כך מפנים לערכים האלה במדיניות בנושא מכסות, כמו שמוצג בהמשך:
<Quota name="DeveloperQuota"> <Identifier ref="verifyapikey.verify-api-key.client_id"/> <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/> <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/> <Allow countRef="verifyapikey.verify-api-key.developer.limit"/> </Quota>
בדוגמה הזו נעשה שימוש גם במשתני הזרימה VerifyAPIKey כדי להפנות למאפיינים המותאמים אישית שהוגדרו למפתח.
אפשר להשתמש בכל משתנה כדי להגדיר את הפרמטרים של מדיניות המכסות. המשתנים האלה יכולים להגיע מהמקורות הבאים:
- משתני תהליך
- מאפיינים במוצר ה-API, באפליקציה או במפתח
- מפת מפתח/ערך (KVM)
- כותרת, פרמטר של שאילתה, פרמטר של טופס וכו'
לכל פרוקסי של API אפשר להוסיף מדיניות מכסה שמפנה לאותו משתנה כמו כל שאר מדיניות המכסה בכל שאר הפרוקסי, או שמדיניות המכסה יכולה להפנות למשתנים ייחודיים למדיניות ולפרוקסי האלה.
שעת ההתחלה
<Quota name="QuotaPolicy" type="calendar"> <StartTime>2017-02-18 10:30:00</StartTime> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
אם המכסה מוגדר עם type שמוגדר ל-calendar, צריך להגדיר ערך <StartTime> מפורש. ערך הזמן הוא הזמן לפי שעון GMT, ולא הזמן המקומי. אם לא מספקים ערך <StartTime> למדיניות מסוג calendar, Edge מציג שגיאה.
מונה המכסה של כל אפליקציה מתעדכן על סמך הערכים <StartTime>, <Interval> ו-<TimeUnit>. בדוגמה הזו, המכסה מתחילה להיספר ב-18 בפברואר 2017 בשעה 10:30 (GMT), ומתעדכנת כל 5 שעות. לכן, החידוש הבא יהיה ב-18 בפברואר 2017 בשעה 15:30 GMT.
מונה גישה
<Quota name="QuotaPolicy"> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
לשרת proxy של API יש גישה למשתני הזרימה שמוגדרים על ידי מדיניות המכסה. אפשר לגשת למשתני הזרימה האלה ב-API proxy כדי לבצע עיבוד מותנה, לעקוב אחרי המדיניות כשהיא מתקרבת למגבלת המכסה, להחזיר את מונה המכסה הנוכחי לאפליקציה או מסיבות אחרות.
הגישה למשתני הזרימה של המדיניות מבוססת על המאפיין name של המדיניות. לכן, כדי לגשת למשתני הזרימה של המדיניות שצוינה למעלה בשם QuotaPolicy, צריך להשתמש בפורמט הבא:
-
ratelimit.QuotaPolicy.allowed.count: מספר הפעמים שמותר להשתמש בהרשאה. -
ratelimit.QuotaPolicy.used.count: הערך הנוכחי של המונה. -
ratelimit.QuotaPolicy.expiry.time: השעה לפי שעון UTC שבה הדלפק מתאפס.
יש עוד הרבה משתני זרימה שאפשר לגשת אליהם, כמו שמתואר בהמשך.
לדוגמה, אפשר להשתמש במדיניות AssignMessage הבאה כדי להחזיר את הערכים של משתני Quota flow ככותרות תגובה:
<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars"> <AssignTo createNew="false" type="response"/> <Set> <Headers> <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header> <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header> <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
בקשה ראשונה
<Quota name="MyQuota"> <Interval>1</Interval> <TimeUnit>hour</TimeUnit> <Allow count="10000"/> </Quota>
אפשר להשתמש בקוד לדוגמה הזה כדי לאכוף מכסה של 10,000 קריאות לשעה. המדיניות מאפסת את מונה המכסה בראש כל שעה. אם המונה מגיע למכסת 10,000 שיחות לפני סוף השעה, שיחות מעבר ל-10,000 נדחות.
לדוגמה, אם הדלפק מתחיל ב-2017-07-08 07:00:00, הוא יתאפס ל-0 בשעה 2017-07-08 08:00:00 (שעה אחת אחרי זמן ההתחלה). אם ההודעה הראשונה מתקבלת בשעה 2017-07-08 07:35:28 ומספר ההודעות מגיע ל-10,000 לפני השעה 2017-07-08 08:00:00, שיחות מעבר למספר הזה יידחו עד שהמספר יתאפס בתחילת השעה.
זמן האיפוס של המונה מבוסס על השילוב של <Interval> ושל <TimeUnit>. לדוגמה, אם מגדירים את <Interval> ל-12 עבור <TimeUnit> של שעה, המונה מתאפס כל 12 שעות.
אפשר להגדיר את <TimeUnit> לדקה, לשעה, ליום, לשבוע או לחודש.
אפשר להפנות למדיניות הזו בכמה מקומות ב-API Proxy. לדוגמה, אפשר למקם אותו ב-Proxy PreFlow כדי שהוא יופעל בכל בקשה. לחלופין, אפשר להציב אותו בכמה רכיבי Flow ב-API Proxy. אם משתמשים במדיניות הזו בכמה מקומות בשרת הפרוקסי, היא שומרת על מונה יחיד שמתעדכן על ידי כל המופעים של המדיניות.
אפשרות אחרת היא להגדיר כמה כללי מדיניות בנושא מכסות בשרת ה-proxy של ה-API. לכל מדיניות מכסת נפח יש מונה משלה, שמבוסס על מאפיין name של המדיניות.
הגדרת מזהה
<Quota name="QuotaPolicy" type="calendar"> <Identifier ref="request.header.clientId"/> <StartTime>2017-02-18 10:00:00</StartTime> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
כברירת מחדל, מדיניות מכסה מגדירה מונה יחיד ל-API proxy, ללא קשר למקור הבקשה. לחלופין, אפשר להשתמש במאפיין <Identifier> עם מדיניות מכסה כדי לשמור על מוני נפרדים על סמך הערך של המאפיין <Identifier>.
לדוגמה, אפשר להשתמש בתג <Identifier> כדי להגדיר מונה נפרד לכל מזהה לקוח. בבקשה לשרת ה-proxy, אפליקציית הלקוח מעבירה כותרת שמכילה את clientID, כמו בדוגמה שלמעלה.
אפשר לציין כל משתנה של זרימת נתונים במאפיין <Identifier>. לדוגמה, אפשר לציין שפרמטר שאילתה בשם id מכיל את המזהה הייחודי:
<Identifier ref="request.queryparam.id"/>
אם משתמשים במדיניות VerifyAPIKey כדי לאמת את מפתח ה-API, או במדיניות OAuthV2 עם אסימוני OAuth, אפשר להשתמש במידע במפתח ה-API או באסימון כדי להגדיר מוניטורים נפרדים לאותה מדיניות Quota. לדוגמה, בתג <Identifier> הבא נעשה שימוש במשתנה הזרימה client_id של מדיניות VerifyAPIKey בשם verify-api-key:
<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>
כל ערך ייחודי של client_id מגדיר עכשיו מונה משלו במדיניות Quota.
מחלקה
<Quota name="QuotaPolicy">
<Interval>1</Interval>
<TimeUnit>day</TimeUnit>
<Allow>
<Class ref="request.header.developer_segment">
<Allow class="platinum" count="10000"/>
<Allow class="silver" count="1000" />
</Class>
</Allow>
</Quota>אפשר להגדיר מגבלות מכסה באופן דינמי באמצעות ספירת מכסות שמבוססת על מחלקה. בדוגמה הזו, מגבלת המכסה נקבעת לפי הערך של הכותרת developer_segmentשמועברת עם כל בקשה. המשתנה הזה יכול לקבל את הערך platinum או silver. אם הערך של הכותרת לא תקין, המדיניות מחזירה שגיאה של חריגה מהמכסה.
מידע על מדיניות בנושא מכסות
מכסה היא הקצאה של הודעות בקשה ששרת proxy של API יכול לטפל בהן במשך תקופת זמן מסוימת, כמו דקה, שעה, יום, שבוע או חודש. במדיניות יש מונה שמסכם את מספר הבקשות שהתקבלו על ידי שרת ה-proxy של ה-API. היכולת הזו מאפשרת לספקי API לאכוף מגבלות על מספר הקריאות ל-API שאפליקציות מבצעות במרווחי זמן. באמצעות מדיניות מכסות, אפשר למשל להגביל את האפליקציות לבקשה אחת בדקה, או ל-10,000 בקשות בחודש.
לדוגמה, אם מכסת ההודעות היא 10,000 הודעות בחודש, הגבלת הקצב מתחילה אחרי ההודעה ה-10,000. לא משנה אם 10,000 ההודעות נספרו ביום הראשון או ביום האחרון של התקופה הזו. לא ניתן לשלוח בקשות נוספות עד שהמונה של המכסה יתאפס אוטומטית בסוף מרווח הזמן שצוין, או עד שהמכסה יתאפס באופן מפורש באמצעות מדיניות איפוס המכסה.
וריאציה של מכסת השימוש שנקראת SpikeArrest מונעת עליות חדות בתנועה (או פרצי תנועה) שיכולות להיגרם כתוצאה מעלייה פתאומית בשימוש, מלקוחות עם באגים או מהתקפות זדוניות. מידע נוסף על SpikeArrest זמין במאמר מדיניות Spike Arrest.
המכסות חלות על שרתי proxy ספציפיים ל-API, ולא מחולקות בין שרתי proxy ל-API. לדוגמה, אם יש לכם שלושה שרתי proxy ל-API במוצר API, מכסה אחת לא משותפת בין שלושתם, גם אם כולם משתמשים באותה הגדרת מדיניות מכסה.
סוגים של כללי מדיניות בנושא מכסות
מדיניות המכסות תומכת בכמה סוגים שונים של מדיניות: ברירת מחדל, calendar, flexi ו-rollingwindow. כל סוג מגדיר מתי מתחיל מונה המכסה ומתי הוא מתאפס, כמו שמוצג בטבלה הבאה:
| יחידת זמן | איפוס ברירת מחדל (או null) | איפוס היומן | איפוס גמיש |
|---|---|---|---|
| דקה | תחילת הדקה הבאה | דקה אחרי <StartTime> |
דקה אחת אחרי הבקשה הראשונה |
| hour | בתחילת השעה הבאה | שעה אחרי <StartTime> |
שעה אחרי הבקשה הראשונה |
| יום | חצות לפי שעון גריניץ' של היום הנוכחי | 24 שעות אחרי <StartTime> |
24 שעות אחרי הבקשה הראשונה |
| שבוע | חצות שעון גריניץ' ביום ראשון בסוף השבוע | שבוע אחרי <StartTime> |
שבוע אחרי הבקשה הראשונה |
| חודש | חצות לפי שעון GMT ביום האחרון של החודש | חודש אחד (28 ימים) אחרי <StartTime> |
חודש אחד (28 ימים) אחרי הבקשה הראשונה |
עבור type="calendar", צריך לציין את הערך של <StartTime>.
הטבלה לא מציגה את הערך של הסוג rollingwindow. מכסות של חלון מתגלגל פועלות על ידי הגדרת הגודל של 'חלון' מכסה, כמו חלון של שעה או של יום. כשמתקבלת בקשה חדשה, המדיניות קובעת אם חרגתם מהמכסה בפרק הזמן האחרון.
לדוגמה, אתם מגדירים חלון של שעתיים שמאפשר 1,000 בקשות. בקשה חדשה מתקבלת בשעה 16:45.המדיניות מחשבת את מספר הבקשות בחלון של שעתיים אחורה, כלומר מספר הבקשות מאז השעה 14:45. אם לא חרגתם ממגבלת המכסה בחלון הזמן של שעתיים, הבקשה תאושר.
דקה לאחר מכן, בשעה 16:46, מתקבלת בקשה נוספת. עכשיו המדיניות מחשבת את מספר המכסות מאז 14:46 כדי לקבוע אם חרגתם מהמגבלה.
בסוג rollingwindow, הדלפק אף פעם לא מתאפס, אבל הוא מחושב מחדש בכל בקשה.
הסבר על מוניטורים של מכסות
כברירת מחדל, מדיניות מכסות מתחזקת מונה יחיד, בלי קשר למספר הפעמים שמתייחסים אליה ב-API Proxy. השם של מונה המכסות מבוסס על המאפיין name של המדיניות.
לדוגמה, יוצרים מדיניות מכסה בשם MyQuotaPolicy עם מגבלה של 5 בקשות ומציבים אותה בכמה תהליכים (תהליך א', תהליך ב' ותהליך ג') בשרת ה-proxy של ה-API. למרות שהיא משמשת בכמה תהליכים, היא שומרת על מונה יחיד שמתעדכן על ידי כל המופעים של המדיניות:
- תהליך A מבוצע -> מדיניות MyQuota מבוצעת והמונה שלה = 1
- תהליך B מופעל -> מדיניות MyQuotaPolicy מופעלת והמונה שלה = 2
- תהליך A מבוצע -> מדיניות MyQuotaPolicy מבוצעת והמונה שלה = 3
- תהליך C מבוצע -> מדיניות MyQuotaPolicy מבוצעת והמונה שלה = 4
- תהליך A מבוצע -> מדיניות MyQuota מבוצעת והמונה שלה = 5
הבקשה הבאה לאחד משלושת התהליכים נדחית כי מונה המכסה הגיע למגבלה שלו.
שימוש באותה מדיניות מכסת נתונים ביותר ממקום אחד בתהליך של API proxy, שעלול לגרום למכסת הנתונים להיגמר מהר יותר מהצפוי, הוא דפוס אנטי שמתואר בThe Book of Apigee Edge Antipatterns.
אפשרות אחרת היא להגדיר כמה מדיניות מכסה ב-API Proxy ולהשתמש במדיניות שונה בכל זרימה. לכל מדיניות מכסת שימוש יש מונה משלה, שמבוסס על מאפיין name של המדיניות.
לחלופין, אפשר להשתמש ברכיבים <Class> או <Identifier> במדיניות בנושא מכסות כדי להגדיר כמה מונים ייחודיים במדיניות אחת. באמצעות הרכיבים האלה, אפשר להגדיר מדיניות אחת עם מוני נפרדים בהתאם לאפליקציה ששולחת את הבקשה, למפתח האפליקציה ששולח את הבקשה, למזהה לקוח או למזהה לקוח אחר ועוד. למידע נוסף על השימוש ברכיבים <Class> או <Identifier>, אפשר לעיין בדוגמאות שלמעלה.
סימון זמן
כל השעות שמוגדרות במכסת השימוש הן לפי אזור הזמן זמן אוניברסלי מתואם (UTC).
הפורמט של מכסת הזמן הוא פורמט התאריך הבינלאומי שמוגדר בתקן הבינלאומי ISO 8601.
התאריכים מוגדרים כשנה, חודש ויום, בפורמט הבא: YYYY-MM-DD.
לדוגמה, 2015-02-04 מייצג את התאריך 4 בפברואר 2015.
השעה ביום מוגדרת כשעות, דקות ושניות בפורמט הבא:
hours:minutes:seconds. לדוגמה, 23:59:59 מייצג את השעה שנייה אחת לפני חצות.
שימו לב שיש שני סימונים, 00:00:00 ו-24:00:00, כדי להבחין בין שתי חצות שאפשר לשייך לתאריך אחד. לכן, 2015-02-04
24:00:00 הוא אותו תאריך ושעה כמו 2015-02-05 00:00:00. בדרך כלל עדיף להשתמש בסימון השני.
קבלת הגדרות מכסה מהגדרות מוצר ה-API
אפשר להגדיר מכסות בהגדרות של מוצרי API. המגבלות האלה לא נאכפות אוטומטית. במקום זאת, אפשר להפנות להגדרות של מכסת מוצרים במדיניות מכסות. אלה כמה יתרונות של הגדרת מכסה במוצר לצורך הפניה למדיניות בנושא מכסות:
- במדיניות בנושא מכסות אפשר להשתמש בהגדרה אחידה בכל שרתי ה-proxy של ה-API במוצר ה-API.
- אפשר לבצע שינויים בהגדרת המכסה של מוצר API בזמן ריצה, ומדיניות מכסות שמפנה לערך הזה תעודכן אוטומטית עם ערכי מכסות מעודכנים.
למידע נוסף על שימוש בהגדרות מכסה ממוצר API, אפשר לעיין בדוגמה 'מכסה דינמית' שבהמשך המאמר..
מידע על הגדרת מוצרי API עם מכסות זמין במאמר יצירת מוצרי API.
הפניה לרכיב
בהמשך מפורטים האלמנטים והמאפיינים שאפשר להגדיר במדיניות הזו. חשוב לדעת: חלק מהשילובים של רכיבים הם בלעדיים או לא נדרשים. דוגמאות לשימוש ספציפי מופיעות במאמרים הבאים: המשתנים verifyapikey.VerifyAPIKey.apiproduct.* שבהמשך זמינים כברירת מחדל כשמשתמשים במדיניות Verify API Key (אימות מפתח API) שנקראת VerifyAPIKey כדי לבדוק את מפתח ה-API של האפליקציה בבקשה.
ערכי המשתנים מגיעים מהגדרות המכסה במוצר ה-API שאליו משויך המפתח, כפי שמתואר במאמר קבלת הגדרות המכסה מהגדרת מוצר ה-API.
<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar"> <DisplayName>Quota 3</DisplayName> <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> <Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow> <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit> <StartTime>2017-7-16 12:00:00</StartTime> <Distributed>false</Distributed> <Synchronous>false</ Synchronous> <AsynchronousConfiguration> <SyncIntervalInSeconds>20</ SyncIntervalInSeconds> <SyncMessageCount>5</ SyncMessageCount> </AsynchronousConfiguration> <Identifier/> <MessageWeight/> </Quota>
מאפייני <Quota>
<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
המאפיינים הבאים ספציפיים למדיניות הזו.
| מאפיין | תיאור | ברירת מחדל | נוכחות |
|---|---|---|---|
| סוג |
הפרמטר הזה משמש לקביעה מתי ואיך מונה המכסה בודק את השימוש במכסה. מידע נוסף זמין במאמר סוגי מדיניות בנושא מכסות. אם לא מציינים ערך של הערכים האפשריים כוללים:
|
יומן, קלנדר, קאלנדר | אופציונלי |
בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:
| מאפיין | תיאור | ברירת מחדל | נוכחות |
|---|---|---|---|
name |
השם הפנימי של המדיניות. הערך של המאפיין אפשר להשתמש ברכיב |
לא רלוונטי | חובה |
continueOnError |
צריך להגדיר את הערך יש להגדיר ל- |
false | אופציונלי |
enabled |
צריך להגדיר את הערך צריך להגדיר את הערך |
true | אופציונלי |
async |
המאפיין הזה הוצא משימוש. |
false | הוצא משימוש |
<DisplayName> רכיב
צריך להשתמש בנוסף למאפיין name כדי להוסיף תווית למדיניות
עורך proxy של ממשק משתמש לניהול עם שם אחר בשפה טבעית.
<DisplayName>Policy Display Name</DisplayName>
| ברירת מחדל |
לא רלוונטי אם משמיטים את הרכיב הזה, הערך של המאפיין |
|---|---|
| נוכחות | אופציונלי |
| סוג | מחרוזת |
אלמנט <Allow>
מציין את מגבלת הספירה של המכסה. אם מונה המדיניות מגיע לערך הזה של המגבלה, הקריאות הבאות נדחות עד לאיפוס המונה.
בהמשך מוצגות שלוש דרכים להגדיר את הרכיב <Allow>:
<Allow count="2000"/>
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
אם מציינים גם את count וגם את countRef, אז countRef מקבל עדיפות. אם לא ניתן לפתור את countRef בזמן הריצה, המערכת תשתמש בערך של count.
| ברירת מחדל: | לא רלוונטי |
| נוכחות: | אופציונלי |
| סוג: | מספר שלם |
מאפיינים
| מאפיין | תיאור | ברירת מחדל | נוכחות |
|---|---|---|---|
| ספירה |
משמש לציון מספר ההודעות במכסת נפח האחסון. לדוגמה, אם ערך המאפיין |
2000 | אופציונלי |
| countRef |
משתמשים במשתנה הזה כדי לציין משתנה של זרימת נתונים שמכיל את מספר ההודעות למכסת השימוש.
המאפיין |
אין | אופציונלי |
אלמנט <Allow>/<Class>
רכיב <Class> מאפשר להגדיר תנאי לערך של רכיב <Allow> על סמך הערך של משתנה זרימה. לכל תג צאצא שונה של <Class>, המדיניות שומרת על מונה שונה.<Allow>
כדי להשתמש ברכיב <Class>, מציינים משתנה של זרימת נתונים באמצעות המאפיין ref בתג <Class>. לאחר מכן, Edge משתמש בערך של משתנה הזרימה כדי לבחור אחד מתגי הצאצא <Allow> כדי לקבוע את המספר המותר של המדיניות. Edge מתאים את הערך של משתנה הזרימה למאפיין class של התג <Allow>, כמו שמוצג בהמשך:
<Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow>
בדוגמה הזו, מונה המכסות הנוכחי נקבע לפי הערך של פרמטר השאילתה time_variable שמועבר עם כל בקשה. המשתנה הזה יכול לקבל את הערך peak_time או off_peak_time. אם פרמטר השאילתה מכיל ערך לא תקין, המדיניות מחזירה שגיאה של חריגה מהמכסה.
| ברירת מחדל: | לא רלוונטי |
| נוכחות: | אופציונלי |
| סוג: | לא רלוונטי |
מאפיינים
| מאפיין | תיאור | ברירת מחדל | נוכחות |
|---|---|---|---|
| ref |
משתמשים במשתנה הזה כדי לציין משתנה של זרימה שמכיל את סוג המכסה של מכסה מסוימת. |
אין | חובה |
<Allow>/<Class>/<Allow> element
הרכיב <Allow> מציין את המגבלה של מונה מכסת השימוש שהוגדר על ידי הרכיב <Class>. לכל תג ילד שונה <Allow> של <Class>, המדיניות שומרת על מונה שונה.
לדוגמה:
<Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow>
בדוגמה הזו, מדיניות הקצאה לשירות שומרת על שני מוני מכסת נתונים בשם peak_time ו-off_peak_time.
| ברירת מחדל: | לא רלוונטי |
| נוכחות: | אופציונלי |
| סוג: | לא רלוונטי |
מאפיינים
| מאפיין | תיאור | ברירת מחדל | נוכחות |
|---|---|---|---|
| כיתה |
ההגדרה מגדירה את השם של מונה המכסות. |
אין | חובה |
| ספירה | מציין את מגבלת המכסה של הדלפק. | אין | חובה |
אלמנט <Interval>
משתמשים במאפיין הזה כדי לציין מספר שלם (לדוגמה, 1, 2, 5, 60 וכן הלאה) שיוצמד לערך TimeUnit שתציינו (minute, hour, day, week או month) כדי לקבוע תקופת זמן שבמהלכה Edge יחשב את השימוש במכסה.
לדוגמה, אם Interval הוא 24 ו-TimeUnit הוא hour, המכסה תחושב במהלך 24 שעות.
<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
| ברירת מחדל: | אין |
| נוכחות: | חובה |
| סוג: | מספר שלם |
מאפיינים
| מאפיין | תיאור | ברירת מחדל | נוכחות |
|---|---|---|---|
| ref |
המאפיין הזה משמש לציון משתנה של זרימת עבודה שמכיל את המרווח של מכסת שימוש. הערך של |
אין | אופציונלי |
אלמנט <TimeUnit>
משמש לציון יחידת הזמן הרלוונטית למכסת השימוש.
לדוגמה, אם Interval הוא 24 ו-TimeUnit הוא hour, המכסה תחושב במהלך 24 שעות.
<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
| ברירת מחדל: | אין |
| נוכחות: | חובה |
| סוג: |
מחרוזת. בוחרים מתוך האפשרויות |
מאפיינים
| מאפיין | תיאור | ברירת מחדל | נוכחות |
|---|---|---|---|
| ref | משתמשים בו כדי לציין משתנה של זרימה שמכיל את יחידת הזמן של מכסת השימוש. ref
מקבל עדיפות על פני ערך מפורש של פרק זמן. אם ref לא נפתר בזמן הריצה, המערכת משתמשת בערך. |
אין | אופציונלי |
אלמנט <StartTime>
כשמגדירים את type לערך calendar,, המערכת מציינת את התאריך והשעה שבהם יתחיל מונה המכסות לספור, בלי קשר לשאלה אם התקבלו בקשות מאפליקציות כלשהן.
לדוגמה:
<StartTime>2017-7-16 12:00:00</StartTime>
| ברירת מחדל: | אין |
| נוכחות: | חובה אם הערך של type הוא calendar. |
| סוג: |
מחרוזת בפורמט תאריך ושעה של ISO 8601. |
אלמנט <Distributed>
התקנה של Edge יכולה להשתמש במעבד הודעות אחד או יותר כדי לעבד בקשות. מגדירים את הרכיב הזה true כדי לציין שהמדיניות צריכה לשמור על מונה מרכזי ולסנכרן אותו באופן רציף בכל מעבדי ההודעות. מעבדי ההודעות יכולים להיות באזורי זמינות ו/או באזורים שונים.
אם משתמשים בערך ברירת המחדל false, יכול להיות שתחרגו מהמכסה כי הספירה של כל מעבד הודעות לא משותפת:
<Distributed>true</Distributed>
כדי להבטיח שהמונים מסונכרנים ומעודכנים בכל בקשה, צריך להגדיר את <Distributed> ואת <Synchronous> כ-true:
<Distributed>true</Distributed> <Synchronous>true</Synchronous>
| ברירת מחדל: | false |
| נוכחות: | אופציונלי |
| סוג: | בוליאני |
אלמנט <Synchronous>
הערך true מאפשר לעדכן באופן סינכרוני מונה מכסה מבוזר. כלומר, העדכון של המונה מתבצע באותו זמן שבו המכסה נבדקת בבקשה שנשלחת אל ה-API. מגדירים את הערך true אם חשוב לכם שלא לאפשר קריאות ל-API מעבר למכסה.
מגדירים את הערך false כדי לעדכן את מונה המכסות באופן אסינכרוני. המשמעות היא שאולי חלק מקריאות ה-API שחורגות מהמכסה יתבצעו, בהתאם למועד שבו מונה המכסה במאגר המרכזי מתעדכן באופן אסינכרוני. עם זאת, לא תהיה השפעה פוטנציאלית על הביצועים שקשורה לעדכונים סינכרוניים.
ברירת המחדל למרווח העדכון האסינכרוני היא 10 שניות. כדי להגדיר את ההתנהגות האסינכרונית הזו, צריך להשתמש ברכיב AsynchronousConfiguration.
<Synchronous>false</Synchronous>
| ברירת מחדל: | false |
| נוכחות: | אופציונלי |
| סוג: | בוליאני |
אלמנט <AsynchronousConfiguration>
המדיניות הזו מגדירה את מרווח הזמן בין הסנכרונים של מוני מכסות מבוזרים, כשרכיב ההגדרה של המדיניות <Synchronous> לא קיים או קיים ומוגדר לערך false.
אפשר לסנכרן אחרי פרק זמן מסוים או אחרי מספר מסוים של הודעות, באמצעות רכיבי הצאצא SyncIntervalInSeconds או SyncMessageCount.
הן בלעדיות הדדית. לדוגמה,
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
או
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
| ברירת מחדל: | SyncIntervalInSeconds = 10 seconds |
| נוכחות: | אופציונלי; המערכת מתעלמת מההגדרה הזו אם הערך של <Synchronous> הוא true. |
| סוג: |
מתחם |
<AsynchronousConfiguration>/<SyncIntervalInSeconds> element
ההגדרה הזו מאפשרת לשנות את התנהגות ברירת המחדל, שבה מתבצעים עדכונים אסינכרוניים אחרי מרווח של 10 שניות.
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
מרווח הסנכרון צריך להיות גדול מ-10 שניות או שווה לו, כפי שמתואר בנושא מגבלות.
| ברירת מחדל: | 10 |
| נוכחות: | אופציונלי |
| סוג: |
מספר שלם |
אלמנט <AsynchronousConfiguration>/<SyncMessageCount>
ההגדרה הזאת מציינת את מספר הבקשות בכל מעבדי ההודעות של Apigee בין עדכוני המכסה.
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
בדוגמה הזו מצוין שספירת המכסה מתעדכנת כל 5 בקשות בכל מעבד הודעות של Apigee Edge.
| ברירת מחדל: | לא רלוונטי |
| נוכחות: | אופציונלי |
| סוג: |
מספר שלם |
אלמנט <Identifier>
משתמשים ברכיב <Identifier> כדי להגדיר את המדיניות ליצירת מוני נתונים ייחודיים על סמך משתנה של זרימת נתונים.
אם לא משתמשים ברכיב הזה, המדיניות משתמשת בדלפק יחיד שמוחל על המכסה.
האלמנט הזה מתואר גם בפוסט הבא בקהילת Apigee: Quota identifier across different policies.
<Identifier ref="verifyapikey.verify-api-key.client_id"/>
| ברירת מחדל: | לא רלוונטי |
| נוכחות: | אופציונלי |
| סוג: |
מחרוזת |
מאפיינים
| מאפיין | תיאור | ברירת מחדל | נוכחות |
|---|---|---|---|
| ref |
מציינת משתנה של זרימת נתונים שמזהה את המונה שבו יש להשתמש לבקשה. המזהה יכול להיות כותרת HTTP, פרמטר שאילתה, פרמטר טופס או תוכן הודעה, שייחודי לכל אפליקציה, משתמש אפליקציה, מפתח אפליקציה, מוצר API או מאפיין אחר.
במקרים מסוימים, צריך לאחזר את הגדרות המכסה כשאין |
לא רלוונטי | אופציונלי |
אלמנט <MessageWeight>
המאפיין הזה משמש לציון המשקל שמוקצה לכל הודעה. אפשר להשתמש במשקל ההודעה כדי להגביר את ההשפעה של הודעות בקשה שצורכות יותר משאבי מחשוב מאחרות, למשל.
לדוגמה, אם רוצים לספור הודעות POST כהודעות 'כבדות' או יקרות פי שניים מהודעות GET. לכן, מגדירים את MessageWeight לערך 2 עבור POST ולערך 1 עבור GET. אפשר אפילו להגדיר את MessageWeight ל-0 כדי שהבקשה לא תשפיע על המונה. בדוגמה הזו, אם המכסה היא 10 הודעות בדקה ו-MessageWeight עבור בקשות POST הוא 2, אז המכסה מאפשרת 5 בקשות POST בכל מרווח של 10 דקות. כל בקשה נוספת, POST או GET,
לפני איפוס הדלפק נדחית.
צריך לציין ערך שמייצג את MessageWeight באמצעות משתנה של זרימת נתונים. אפשר לחלץ את הערך מכותרות HTTP, מפרמטרים של שאילתות, ממטען ייעודי (payload) של בקשת XML או JSON או מכל משתנה אחר של זרימת נתונים. לדוגמה, הגדרתם אותו בכותרת בשם weight:
<MessageWeight ref="message_weight"/>
| ברירת מחדל: | לא רלוונטי |
| נוכחות: | אופציונלי |
| סוג: |
מספר שלם |
משתני תהליך
משתני ה-Flow המוגדרים מראש הבאים מאוכלסים באופן אוטומטי כשמדיניות מכסת המכסות מופעלת. מידע נוסף על משתני Flow זמין במאמר הפניה למשתנים.
| משתנים | סוג | הרשאות | תיאור |
|---|---|---|---|
| ratelimit.{policy_name}.allowed.count | ארוך | הרשאת קריאה בלבד | מחזירה את מספר המכסות המותרות |
| ratelimit.{policy_name}.used.count | ארוך | הרשאת קריאה בלבד | מחזירה את המכסה הנוכחית בשימוש בתוך מרווח מכסה |
| ratelimit.{policy_name}.available.count | ארוך | הרשאת קריאה בלבד | מחזירה את מספר המכסות הזמינות במרווח המכסות |
| ratelimit.{policy_name}.exceed.count | ארוך | הרשאת קריאה בלבד | מחזירה 1 אחרי שחרגתם מהמכסה. |
| ratelimit.{policy_name}.total.exceed.count | ארוך | הרשאת קריאה בלבד | מחזירה 1 אחרי שחרגתם מהמכסה. |
| ratelimit.{policy_name}.expiry.time | ארוך | הרשאת קריאה בלבד |
הפונקציה מחזירה את הזמן ב-UTC באלפיות השנייה, שקובע מתי המכסה יפוג ומתי יתחיל מרווח זמן חדש של מכסה. אם סוג מדיניות הקצאה הוא |
| ratelimit.{policy_name}.identifier | מחרוזת | הרשאת קריאה בלבד | מחזירה את ההפניה למזהה (הלקוח) שמצורפת למדיניות |
| ratelimit.{policy_name}.class | מחרוזת | הרשאת קריאה בלבד | הפונקציה מחזירה את המחלקה שמשויכת למזהה הלקוח. |
| ratelimit.{policy_name}.class.allowed.count | ארוך | הרשאת קריאה בלבד | מחזירה את מספר המכסות המותרות שהוגדר בכיתה |
| ratelimit.{policy_name}.class.used.count | ארוך | הרשאת קריאה בלבד | החזרת המכסה שהייתה בשימוש בכיתה |
| ratelimit.{policy_name}.class.available.count | ארוך | הרשאת קריאה בלבד | מחזירה את מספר המקומות שזמינים בכיתה |
| ratelimit.{policy_name}.class.exceed.count | ארוך | הרשאת קריאה בלבד | מחזירה את מספר הבקשות שחורגות מהמגבלה בכיתה במרווח המכסה הנוכחי |
| ratelimit.{policy_name}.class.total.exceed.count | ארוך | הרשאת קריאה בלבד | הפונקציה מחזירה את המספר הכולל של בקשות שחרגו מהמגבלה בכיתה בכל מרווחי הזמן של המכסה, כך שהיא הסכום של class.exceed.count בכל מרווחי הזמן של המכסה. |
| ratelimit.{policy_name}.failed | בוליאני | הרשאת קריאה בלבד |
השדה הזה מציין אם המדיניות נכשלה (true או false). |
הפניה לשגיאה
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
| Fault code | HTTP status | Cause | Fix |
|---|---|---|---|
policies.ratelimit.FailedToResolveQuotaIntervalReference |
500 | Occurs if the <Interval> element is not defined within the Quota policy. This element
is mandatory and used to specify the interval of time applicable to the quota. The time interval
can be minutes, hours, days, weeks, or months as defined with the <TimeUnit> element. |
build |
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference |
500 | Occurs if the <TimeUnit> element is not defined within the Quota policy. This element
is mandatory and used to specify the unit of time applicable to the quota. The time interval
can be in minutes, hours, days, weeks, or months. |
build |
policies.ratelimit.InvalidMessageWeight |
500 | Occurs if the value of the <MessageWeight> element specified through a flow variable
is invalid (a non-integer value). |
build |
policies.ratelimit.QuotaViolation |
500 | The quota limit was exceeded. | N/A |
Deployment errors
| Error name | Cause | Fix |
|---|---|---|
InvalidQuotaInterval |
If the quota interval specified in the <Interval> element is not
an integer, then the deployment of the API proxy fails. For example, if the quota interval
specified is 0.1 in the <Interval> element, then the deployment of the
API proxy fails.
|
build |
InvalidQuotaTimeUnit |
If the time unit specified in the <TimeUnit> element is unsupported,
then the deployment of the API proxy fails. The supported time units are minute,
hour, day, week, and month.
|
build |
InvalidQuotaType |
If the type of the quota specified by the type attribute in the <Quota>
element is invalid, then the deployment of the API proxy fails. The
supported quota types are default, calendar, flexi, and rollingwindow.
|
build |
InvalidStartTime |
If the format of the time specified in the <StartTime> element is
invalid, then the deployment of the API proxy fails. The valid format is yyyy-MM-dd HH:mm:ss,
which is the ISO 8601 date and time format. For
example, if the time specified in the <StartTime> element is
7-16-2017 12:00:00 then the deployment of the API proxy fails.
|
build |
StartTimeNotSupported |
If the <StartTime> element is specified whose quota type is not
calendar type, then the deployment of the API proxy fails. The <StartTime> element is
supported only for the calendar quota type. For example, if the type attribute is set
to flexi or rolling window in the <Quota> element, then the
deployment of the API proxy fails.
|
build |
InvalidTimeUnitForDistributedQuota |
If the <Distributed> element is set to true and the <TimeUnit> element is set to
second then the deployment of the API proxy fails. The timeunit second is invalid for
a distributed quota. |
build |
InvalidSynchronizeIntervalForAsyncConfiguration |
If the value specified for the <SyncIntervalInSeconds> element within the
<AsynchronousConfiguration> element in a Quota policy is less than zero, then the
deployment of the API proxy fails. |
build |
InvalidAsynchronizeConfigurationForSynchronousQuota |
If the value of the <AsynchronousConfiguration> element is set to true in a Quota policy, which also
has asynchronous configuration defined using the <AsynchronousConfiguration> element, then
the deployment of the API proxy fails. |
build |
Fault variables
These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.
| Variables | Where | Example |
|---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "QuotaViolation" |
ratelimit.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | ratelimit.QT-QuotaPolicy.failed = true |
Example error response
{ "fault":{ "detail":{ "errorcode":"policies.ratelimit.QuotaViolation" }, "faultstring":"Rate limit quota violation. Quota limit exceeded. Identifier : _default" } }
Example fault rule
<FaultRules>
<FaultRule name="Quota Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "QuotaViolation") </Condition>
</Step>
<Condition>ratelimit.Quota-1.failed=true</Condition>
</FaultRule>
</FaultRules>סכימות
נושאים קשורים
השוואה בין כללי מדיניות בנושא מכסה, מניעת עליות פתאומיות ומגבלת קצב מקבילי