מוצג המסמך של Apigee Edge.
עוברים אל
מסמכי תיעוד של Apigee X. מידע
מה
משתמשים במדיניות Quota כדי להגדיר את מספר הודעות הבקשה ששרת proxy ל-API מאפשר לעבור פרק זמן, כמו דקה, שעה, יום, שבוע או חודש. אפשר להגדיר שהמכסה תהיה זהה לכל האפליקציות שיש להן גישה לשרת ה-proxy ל-API. לחלופין, אפשר להגדיר את המכסה לפי:
- המוצר שמכיל את ה-Proxy ל-API
- האפליקציה שמבקשת את ה-API
- מפתח האפליקציה
- קריטריונים רבים נוספים
אל תשתמשו במכסה כדי להגן מפני עליות חדות בנפח התנועה הכולל. לשם כך, צריך להשתמש ב-Spke Arrest. המדיניות בנושא ראו מעצר ספייק .
סרטונים
בסרטונים הבאים מוצגת אפשרות לניהול המכסות באמצעות מדיניות המכסות:
פתיח (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 לא לאכוף את השימוש בהם בשרת proxy ל-API. כמו כן צריך להוסיף מדיניות מכסה לשרת ה-proxy של ה-API שקוראת את הערכים האלה. מידע נוסף זמין בקטע יצירת API מוצרים נוספים.
בדוגמה שלמעלה, שרת ה-proxy ל-API שמכיל את המדיניות Quota משתמש ב-VerifyAPIKey
, שנקראת verify-api-key
, כדי לאמת את מפתח ה-API שמועבר בבקשה.
לאחר מכן, מדיניות המכסות ניגשת למשתני הזרימה מהמדיניות VerifyAPIKey כדי לקרוא את המכסה
שמוגדרים במוצר ה-API. מידע נוסף על משתני זרימה של VerifyAPIKey זמין במאמר אימות המדיניות של מפתח API.
אפשרות אחרת היא להגדיר מאפיינים מותאמים אישית למפתחים או לאפליקציות מסוימים, ולאחר מכן לקרוא הערכים האלה במדיניות Quota. לדוגמה, אתם רוצים להגדיר ערכי מכסה שונים לכל למפתחים. במקרה כזה, מגדירים מאפיינים מותאמים אישית אצל המפתח שכולל את המגבלה, ביחידת הזמן והמרווח. לאחר מכן אתם מפנים לערכים האלה במדיניות המכסה, כפי שמוצג למטה:
<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)
- כותרת, פרמטר של שאילתה, פרמטר של טופס וכו'
לכל שרת proxy של API, אפשר להוסיף מדיניות Quota שמתייחסת לאותו משתנה כמו את כל שאר כללי מדיניות המכסות בכל שרתי ה-proxy האחרים, או שמדיניות המכסה יכולה להפנות משתנים ייחודיים למדיניות הזו ולשרת ה-proxy.
שעת ההתחלה
<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>
. בשביל זה
לדוגמה, המכסה מתחילה להיספר בשעה 10:30 (שעון גריניץ') ב-18 בפברואר 2017 ומתעדכן כל
5 שעות. לכן, הרענון הבא יתבצע ב-18 בפברואר 2017 בשעה 15:30 (שעון גריניץ').
מונה גישה
<Quota name="QuotaPolicy"> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
לשרת proxy של API יש גישה למשתני הזרימה שהוגדרו במדיניות Quota. יש לך גישה אל את משתני הזרימה האלה בשרת ה-proxy ל-API כדי לבצע עיבוד מותנה, לעקוב אחר המדיניות כשמתקרבים למגבלת המכסה, מחזירים את המכסה הנוכחית לאפליקציה, או סיבות נוספות.
כי הגישה למשתני הזרימה של המדיניות מבוססת על
מאפיין name
, במסגרת המדיניות שלמעלה שנקראת QuotaPolicy
ניגשים למשתני הזרימה שלו בצורה הבאה:
ratelimit.QuotaPolicy.allowed.count
: ספירה מותרת.ratelimit.QuotaPolicy.used.count
: הערך המונה הנוכחי.ratelimit.QuotaPolicy.expiry.time
: שעון UTC שבו המונה מתאפס.
קיימים משתני זרימה רבים נוספים שניתן לגשת אליהם, כפי שמתואר בהמשך.
לדוגמה, אפשר להשתמש במדיניות AssignMessage הבאה כדי להחזיר את ערכי Quota משתני זרימה ככותרות תגובה:
<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
, שיחות מעבר למספר הזה יידחו עד
count מתאפס בחלק העליון של השעה.
הזמן של איפוס המונה מבוסס על השילוב של <Interval>
ו
<TimeUnit>
. לדוגמה, אם מגדירים את <Interval>
לערך
12 במשך <TimeUnit>
של שעה, ואז המונה מתאפס כל 12 שעות.
אפשר להגדיר את <TimeUnit>
לדקה, שעה, יום, שבוע או חודש.
אפשר להפנות למדיניות הזו במקומות רבים בשרת ה-proxy ל-API. לדוגמה, אפשר: להציב אותו ב-Proxy PreFlow כך שהוא יופעל בכל בקשה. לחלופין, אפשר להציב אותו בכמה תהליכים בשרת ה-proxy ל-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>
כברירת מחדל, מדיניות Quota מגדירה מונה יחיד עבור שרת ה-proxy ל-API, ללא קשר
מקור הבקשה. לחלופין, אפשר להשתמש במאפיין <Identifier>
באמצעות מדיניות מכסה כדי לשמור ספירות נפרדות על סמך הערך של
מאפיין <Identifier>
.
לדוגמה, אפשר להשתמש בתג <Identifier>
כדי להגדיר מוניים נפרדים עבור
כל מזהה לקוח. בבקשה לשרת ה-proxy שלכם, אפליקציית הלקוח מעבירה כותרת שמכילה
clientID
, כפי שמוצג בדוגמה שלמעלה.
אפשר לציין כל משתנה זרימה במאפיין <Identifier>
. עבור
לדוגמה, אפשר לציין שפרמטר של שאילתה בשם id
מכיל את
מזהה:
<Identifier ref="request.queryparam.id"/>
אם משתמשים במדיניות VerifyAPIKey כדי לאמת את מפתח ה-API, או את מדיניות OAuthV2
באמצעות אסימוני OAuth, ניתן להשתמש במידע ממפתח ה-API או מהאסימון כדי להגדיר
מונים לאותה מדיניות מכסה. לדוגמה,
התג <Identifier>
משתמש במשתנה הזרימה client_id
של
מדיניות VerifyAPIKey בשם verify-api-key
:
<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>
לכל ערך ייחודי של client_id
מוגדר עכשיו מונה משלו במכסה
המדיניות בנושא
מחלקה
<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. לדוגמה, אם במוצר API יש שלושה שרתי proxy ל-API, מכסה אחת לא משותפת לכל השלושה גם אם כל השלוש משתמשות באותה הגדרה של מדיניות המכסה.
סוגי המדיניות בנושא מכסות
במדיניות המכסה יש תמיכה בכמה סוגים שונים של כללי מדיניות: ברירת המחדל, calendar
,
flexi
ו-rollingwindow
. כל סוג מגדיר מתי מונה המכסה
כשהערך מתחיל ומתי הוא מתאפס, כפי שמוצג בטבלה הבאה:
יחידת זמן | איפוס ברירת מחדל (או null) | איפוס היומן | איפוס גמיש |
---|---|---|---|
דקה | תחילת הדקה הבאה | דקה אחת אחרי <StartTime> |
דקה אחת אחרי הבקשה הראשונה |
hour | תחילת השעה הבאה | שעה אחת אחרי <StartTime> |
שעה אחת אחרי הבקשה הראשונה |
יום | חצות לפי שעון גריניץ' (GMT) ביום הנוכחי | 24 שעות אחרי <StartTime> |
24 שעות אחרי הבקשה הראשונה |
שבוע | יום ראשון בסוף השבוע לפי שעון גריניץ' (GMT) | שבוע אחד אחרי <StartTime> |
שבוע אחד אחרי הבקשה הראשונה |
חודש | חצות לפי שעון גריניץ' (GMT) ביום האחרון בחודש | חודש אחד (28 ימים) אחרי <StartTime> |
חודש אחד (28 ימים) לאחר הבקשה הראשונה |
עבור type="calendar"
, עליך לציין את הערך של
<StartTime>
.
בטבלה לא מופיע הערך של הסוג rollingwindow
. חלון מתגלגל
מכסות פועלות על ידי הגדרת הגודל של 'חלון' של מכסה, למשל חלון של שעה או יום אחד. כאשר
מתקבלת בקשה חדשה, המדיניות קובעת אם חרגת מהמכסה בעבר
'window' הזמן.
לדוגמה, תוכלו להגדיר חלון של שעתיים שבו אפשר לכלול 1,000 בקשות. בקשה חדשה נכנסת בשעה 16:45.המדיניות מחשבת את מספר המכסות בחלון של השעתיים האחרונות, כלומר, מספר הבקשות מאז 14:45. אם לא תחרגו ממגבלת המכסה החלון של שעתיים, ואז הבקשה מורשית.
דקה לאחר מכן, בשעה 16:46, נכנסת בקשה נוספת. עכשיו המדיניות מחשבת את וספירת מכסות מאז 14:46 כדי לקבוע אם הייתה חריגה מהמגבלה.
בסוג rollingwindow
, המונה אף פעם לא מתאפס, אבל
מחושב מחדש בכל בקשה.
הסבר על מוני המכסות
כברירת מחדל, במדיניות מכסה נשמר מונה אחד, ללא קשר לכמות הפעמים
להפנות אליו בשרת proxy ל-API. השם של מונה המכסות מבוסס על
המאפיין name
של המדיניות.
לדוגמה, יוצרים מדיניות מכסה בשם MyQuotaPolicy
ומוגבלת ל-5.
ומציבים אותו בתהליכים מרובים (Flow A, B ו-C) בשרת ה-proxy ל-API. למרות שזה
משמש במספר תהליכים, יש מונה אחד שמתעדכן בכל המופעים של
מדיניות:
- פעולת זרימה א' בוצעה -> MyQuotaPolicy בוצעה והמונה שלו = 1
- תהליך ב' בוצע -> MyQuotaPolicy בוצעה והמונה שלו = 2
- פעולת זרימה א' בוצעה -> MyQuotaPolicy בוצעה והמונה שלו = 3
- תהליך ג' בוצע -> MyQuotaPolicy בוצעה והמונה שלו = 4
- פעולת זרימה א' בוצעה -> MyQuotaPolicy בוצעה והמונה שלו = 5
הבקשה הבאה לכל אחד משלושת התהליכים נדחתה כי הגעתם למונה למגבלה.
שימוש באותה מדיניות מכסה ביותר ממקום אחד בתהליך של שרת proxy ל-API, מה שיכול גורמת בטעות למכסה להיגמר מהר מהצפוי, היא דפוס אנטי-דפוס שמתואר The Book of Apigee Edge Antipatterns.
לחלופין, אפשר להגדיר כמה כללי מדיניות מכסות בשרת ה-proxy ל-API ולהשתמש
המדיניות בכל תהליך. לכל מדיניות Quota יש מונה משלה, בהתאם
המאפיין 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.*
המשתנים שלמטה זמינים כברירת מחדל כאשר
מדיניות לאימות מפתח 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
.
ברירת המחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: | מספר שלם |
מאפיינים
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
count |
משמש לציון ספירת הודעות במכסה. לדוגמה, ערך המאפיין |
2000 | אופציונלי |
countRef |
משמש לציון משתנה זרימה שמכיל את ספירת ההודעות למכסה.
המאפיין |
אין | אופציונלי |
<Allow>/<Class> רכיב
הרכיב <Class>
מאפשר התניה של הערך
של הרכיב <Allow>
על סמך הערך של משתנה הזרימה. עבור
כל תג צאצא שונה מסוג <Allow>
של <Class>
,
במדיניות מוצג מונה שונה.
כדי להשתמש ברכיב <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
. אם פרמטר השאילתה מכיל
, המדיניות מחזירה שגיאה של הפרת המכסה.
ברירת המחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: | לא רלוונטי |
מאפיינים
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
אזכור |
משמש לציון משתנה זרימה שמכיל את סיווג המכסה של מכסה. |
אין | חובה |
<Allow>/<Class>/<Allow> רכיב
הרכיב <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>
בדוגמה הזו, במדיניות Quota יש שני מוני מכסה שנקראים
של peak_time
ו-off_peak_time
.
ברירת המחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: | לא רלוונטי |
מאפיינים
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
מחלקה |
הגדרת השם של מונה המכסות. |
אין | חובה |
count | מציינת את מגבלת המכסה למונה. | אין | חובה |
<Interval> רכיב
משמש לציון מספר שלם (לדוגמה, 1, 2, 5, 60 וכן הלאה) שיותאם עם
TimeUnit
שמציינים (דקה, שעה, יום, שבוע או חודש) כדי לקבוע שעה
שבמהלכה דפדפן Edge מחשב את השימוש במכסה.
לדוגמה, Interval
של 24
עם
המשמעות של TimeUnit
של hour
שהמכסה תהיה
מחושב לאורך 24 שעות.
<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
ברירת המחדל: | אין |
נוכחות: | חובה |
סוג: | מספר שלם |
מאפיינים
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
אזכור |
משמש לציון משתנה זרימה שמכיל את המרווח של
במכסה. |
אין | אופציונלי |
<TimeUnit> רכיב
משמש לציון יחידת הזמן הרלוונטית למכסה.
לדוגמה, Interval
של 24
עם
המשמעות של TimeUnit
של hour
שהמכסה תהיה
מחושב לאורך 24 שעות.
<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
ברירת המחדל: | אין |
נוכחות: | חובה |
סוג: |
מחרוזת. בחירה מתוך |
מאפיינים
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
אזכור | משמש לציון משתנה זרימה שמכיל את יחידת הזמן למכסה. ref
מקבלת עדיפות על פני ערך מרווח מפורש. אם ref
לא מזוהים בזמן הריצה, אז נעשה שימוש בערך. |
אין | אופציונלי |
<StartTime> רכיב
אם המדיניות type
מוגדרת לערך calendar,
, התאריך הזה מציין את התאריך
ואת השעה שבה תתחיל הספירה של מונה המכסות, בין אם נשלחו בקשות כלשהן
שהתקבלו מאפליקציות.
צריך לציין StartTime
מפורש כשמוגדר type
באופן מפורש
אל calendar,
לא ניתן להשתמש בהפניה למשתנה זרימה, אם מציינים
ערך של StartTime
אם לא הוגדר ערך של type
, אז מתקבל ערך של StartTime
שגיאה.
לדוגמה:
<StartTime>2017-7-16 12:00:00</StartTime>
ברירת המחדל: | אין |
נוכחות: | חובה כשהערך בשדה type מוגדר ל-calendar . |
סוג: |
מחרוזת בתקן ISO 8601 פורמט תאריך ושעה. |
<הופצה> רכיב
בהתקנה של Edge אפשר להשתמש במעבד הודעות אחד או יותר כדי לעבד בקשות. הגדרה
ל-true
כדי לציין שהמדיניות צריכה לשמור
מונה ולסנכרן אותו באופן רציף בין כל מעבדי ההודעות. מעבדי ההודעות
יכולים להיות בכמה אזורי זמינות ו/או אזורים.
אם משתמשים בערך ברירת המחדל של false
, יכול להיות שתחרגו מהמכסה כי
הספירה עבור כל מעבד הודעות לא משותפת:
<Distributed>true</Distributed>
כדי להבטיח שהמוניים יסונכרנו ומעודכנים בכל בקשה, מגדירים
<Distributed>
ו-<Synchronous>
לערך True:
<Distributed>true</Distributed> <Synchronous>true</Synchronous>
ברירת המחדל: | false |
נוכחות: | אופציונלי |
סוג: | ערך בוליאני |
<Synchronous> רכיב
צריך להגדיר את הערך true
כדי לעדכן מונה מכסה מבוזר באופן סינכרוני. הזה
פירושו שהעדכון למונה מתבצע באותו זמן שבו נבדקת המכסה בבקשה
ל-API. אם חשוב לא לאפשר אף API, צריך להגדיר את הערך ל-true
קריאות מעבר למכסה.
צריך להגדיר את הערך 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 שניות |
נוכחות: | אופציונלי; המערכת מתעלמת מהמדיניות <Synchronous> מוגדר לערך
true . |
סוג: |
מתחם |
<AsynchronousConfiguration>/<SyncIntervalInSeconds> רכיב
להשתמש באפשרות הזו כדי לשנות את התנהגות ברירת המחדל שבה מבוצעים עדכונים אסינכרוניים אחרי מרווח של 10 שניות.
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
מרווח הזמן לסנכרון חייב להיות >= 10 שניות כפי שמתואר מגבלות.
ברירת המחדל: | 10 |
נוכחות: | אופציונלי |
סוג: |
מספר שלם |
<AsynchronousConfiguration>/<SyncMessageCount> רכיב
מציינת את מספר הבקשות בין מכסה בכל מעבדי ההודעות ב-Apigee
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
הדוגמה הזו מציינת שספירת המכסות מתעדכנת כל 5 בקשות בכל Apigee מעבד הודעות Edge.
ברירת המחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: |
מספר שלם |
<Identifier> רכיב
עליך להשתמש ברכיב <Identifier>
כדי להגדיר את המדיניות ליצירת תכונות ייחודיות
מונה שמבוססים על משתנה זרימה.
אם לא משתמשים ברכיב הזה, המדיניות משתמשת במונה אחד שמוחל על במכסה.
הרכיב הזה מתואר גם בפוסט הבא בקהילת Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.
<Identifier ref="verifyapikey.verify-api-key.client_id"/>
ברירת המחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: |
מחרוזת |
מאפיינים
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
אזכור |
מציינת משתנה זרימה שמזהה את המונה לשימוש בבקשה. מזהה יכול להיות כותרת HTTP, פרמטר שאילתה, פרמטר של טופס או תוכן הודעה ייחודיים לכל אפליקציה, משתמש באפליקציה, מפתח אפליקציות, מוצר API או מאפיון.
במקרים מסוימים, צריך לאחזר את הגדרות המכסה כאשר לא
המדיניות |
לא רלוונטי | אופציונלי |
<MessageWeight> רכיב
משמש לציון המשקל שיוקצה לכל הודעה. שימוש במשקל ההודעה כדי להגדיל את ההשפעה של בקשות להודעות שצורכות, למשל, יותר משאבי חישוב מאחרים.
לדוגמה, אתם רוצים לספור הודעות POST כ'כבדות' פי שניים. או יקר, כמו GET
הודעות. לכן, מגדירים את הערך MessageWeight
ל-2 עבור POST ול-1 עבור
הורדה. אפשר אפילו להגדיר את MessageWeight
ל-0 כדי שהבקשה לא
משפיעים על המונה. בדוגמה הזאת, אם המכסה היא 10 הודעות בדקה,
הערך MessageWeight
של בקשות POST הוא 2
, ואז המכסה
מאפשרת 5 בקשות POST בכל פרק זמן של 10 דקות. כל בקשה נוספת, POST או GET,
לפני שפעולות האיפוס הנגדיות נדחו.
יש לציין ערך שמייצג את MessageWeight
באמצעות זרימה
משתנה, ואפשר לחלץ אותו מכותרות HTTP, מפרמטרים של שאילתה, מבקשת XML או בקשת JSON
מטען ייעודי (payload) או כל משתנה אחר של זרימה. לדוגמה, מגדירים אותו בכותרת בשם
weight
:
<MessageWeight ref="message_weight"/>
ברירת המחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: |
מספר שלם |
משתני זרימה
משתני ה-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). |
התייחסות לשגיאות
בקטע הזה מתוארים קודי השגיאה והודעות השגיאה שהוחזרו, ומשתני התקלה שמוגדרים על ידי Edge כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת את המידע הזה אם אתם מפתחים כללי כשל כדי לטפל בתקלות. מידע נוסף זמין במאמר מה צריך לדעת? מידע על שגיאות שקשורות למדיניות וטיפול פגמים.
שגיאות זמן ריצה
השגיאות האלה עשויות להתרחש כשהמדיניות מופעלת.
קוד תקלה | סטטוס HTTP | סיבה | תיקון |
---|---|---|---|
policies.ratelimit.FailedToResolveQuotaIntervalReference |
500 | קורה אם הרכיב <Interval> לא מוגדר במדיניות Quota. הרכיב הזה
חובה ומשמש לציון מרווח הזמן שרלוונטי למכסה. מרווח הזמן
הערך יכול להיות דקות, שעות, ימים, שבועות או חודשים, כפי שמוגדר באמצעות הרכיב <TimeUnit> . |
build |
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference |
500 | קורה אם הרכיב <TimeUnit> לא מוגדר במדיניות Quota. הרכיב הזה
חובה ומשמש לציון יחידת הזמן הרלוונטית למכסה. מרווח הזמן
יכול להיות בדקות, שעות, ימים, שבועות או חודשים. |
build |
policies.ratelimit.InvalidMessageWeight |
500 | מתרחש אם הערך של הרכיב <MessageWeight> צוין באמצעות משתנה זרימה
לא חוקי (ערך שאינו מספר שלם). |
build |
policies.ratelimit.QuotaViolation |
500 | חרגת מהמיכסה. | לא רלוונטי |
שגיאות פריסה
שם השגיאה | סיבה | תיקון |
---|---|---|
InvalidQuotaInterval |
אם מרווח המכסה שצוין ברכיב <Interval> הוא לא
מספר שלם, הפריסה של שרת ה-proxy ל-API נכשלת. לדוגמה, אם מרווח הזמן במכסה
שצוין הוא 0.1 ברכיב <Interval> , אז הפריסה של
ה-Proxy ל-API נכשל.
|
build |
InvalidQuotaTimeUnit |
אם יחידת הזמן שצוינה ברכיב <TimeUnit> אינה נתמכת,
הפריסה של שרת ה-proxy ל-API נכשלת. יחידות הזמן הנתמכות הן minute ,
hour , day , week וגם month .
|
build |
InvalidQuotaType |
אם סוג המכסה שצוין על ידי המאפיין type ב<Quota>
לא חוקי, אז הפריסה של שרת ה-proxy ל-API נכשלת.
המכסות הנתמכות הן default , calendar , flexi ו-rollingwindow .
|
build |
InvalidStartTime |
אם פורמט השעה שצוין ברכיב <StartTime> הוא
לא, הפריסה של שרת ה-proxy ל-API נכשלת. הפורמט החוקי הוא yyyy-MM-dd HH:mm:ss ,
שהוא פורמט תאריך ושעה ב-ISO 8601. עבור
לדוגמה, אם השעה שצוינה ברכיב <StartTime> היא
7-16-2017 12:00:00 , הפריסה של שרת ה-proxy ל-API נכשלת.
|
build |
StartTimeNotSupported |
אם צוין הרכיב <StartTime> שסוג המכסה שלו לא צוין
סוג calendar , הפריסה של שרת ה-proxy ל-API נכשלת. הרכיב <StartTime> הוא
רק למכסה מסוג calendar . לדוגמה, אם המאפיין type מוגדר
אל flexi או rolling window ברכיב <Quota> , ואז אל
הפריסה של שרת ה-proxy ל-API נכשלה.
|
build |
InvalidTimeUnitForDistributedQuota |
אם הרכיב <Distributed> מוגדר לערך true והרכיב <TimeUnit> מוגדר לערך
second – הפריסה של שרת ה-proxy ל-API נכשלת. יחידת הזמן second אינה חוקית עבור
מכסה מבוזרת. |
build |
InvalidSynchronizeIntervalForAsyncConfiguration |
אם הערך שצוין לרכיב <SyncIntervalInSeconds> בתוך
הרכיב <AsynchronousConfiguration> במדיניות מכסה קטן מאפס, ואז
הפריסה של שרת ה-proxy ל-API נכשלה. |
build |
InvalidAsynchronizeConfigurationForSynchronousQuota |
אם הערך של הרכיב <AsynchronousConfiguration> מוגדר כ-true במדיניות מכסה, שגם
בהגדרה אסינכרונית באמצעות הרכיב <AsynchronousConfiguration> , לאחר מכן
הפריסה של שרת ה-proxy ל-API נכשלה. |
build |
משתני כשל
המשתנים האלה מוגדרים כשהמדיניות הזו גורמת לשגיאה. מידע נוסף זמין במאמר מה צריך לדעת? על שגיאות שקשורות למדיניות.
משתנים | איפה | דוגמה |
---|---|---|
fault.name="fault_name" |
fault_name הוא שם השגיאה, כפי שמצוין בטבלה שגיאות זמן ריצה שלמעלה. שם השגיאה הוא החלק האחרון בקוד השגיאה. | fault.name Matches "QuotaViolation" |
ratelimit.policy_name.failed |
policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לבעיה. | ratelimit.QT-QuotaPolicy.failed = true |
דוגמה לתגובת שגיאה
{ "fault":{ "detail":{ "errorcode":"policies.ratelimit.QuotaViolation" }, "faultstring":"Rate limit quota violation. Quota limit exceeded. Identifier : _default" } }
דוגמה לכלל שגוי
<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>
סכימות
נושאים קשורים
השוואה כללי המדיניות בנושא מכסות, מעצרים והגבלת קצב של יצירת בקשות בו-זמנית