כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
מה
אפשר להשתמש במדיניות המכסה כדי להגדיר את מספר הודעות הבקשות ששרת proxy ל-API מאפשר במהלך פרק זמן מסוים, כמו דקה, שעה, יום, שבוע או חודש. אפשר להגדיר את המכסה שתהיה זהה לכל האפליקציות שמקבלות גישה לשרת ה-API של ה-API, או שאפשר להגדיר את המכסה לפי:
- המוצר שמכיל את שרת ה-API של שרת ה-API
- האפליקציה שמבקשת את ה-API
- מפַתח האפליקציה
- קריטריונים רבים נוספים
אל תשתמשו במכסה כדי להגן מפני עליות חדות בנפח התנועה. לשם כך, צריך להשתמש במדיניות Spike Arrest. למידע נוסף, אפשר לקרוא את המדיניות בנושא מעצר ספייק.
סרטונים
בסרטונים הבאים מוצג ניהול מכסות באמצעות מדיניות המכסה:
מבוא (חדש Edge)
פתיח (הגרסה הקלאסית של Edge)
מכסה דינמית
מבוזר וסינכרוני
משקל ההודעה
יומן
חלון מתגלגל
גמיש
מכסה מותנית
משתני זרימה
טיפול בשגיאות
דוגמאות
דוגמאות קוד המדיניות הבאות ממחישות איך להתחיל ולסיים תקופות מכסות על ידי:
עוד מכסה דינמית
<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>
באמצעות מכסות דינמיות אפשר להגדיר מדיניות מכסה אחת שתאכוף הגדרות מכסה שונות על סמך המידע שמועבר למדיניות המכסה. מונח נוסף להגדרות Quota בהקשר הזה הוא 'תוכנית שירות'. המכסה הדינמית בודקת את 'תוכנית השירות' של האפליקציה ואז אוכפת את ההגדרות האלה.
הערה: אם מציינים גם ערך וגם הפניה לרכיב, ההפניה מקבלת את העדיפות. אם ההפניה לא מזוהה בזמן הריצה, נעשה שימוש בערך.
לדוגמה, כשיוצרים מוצר של API, אפשר להגדיר את המכסה המותרת, את יחידת הזמן ואת המרווח. עם זאת, הגדרת הערכים האלה במוצר ה-API לא אוכפת את השימוש בהם בשרת proxy ל-API. צריך גם להוסיף מדיניות מכסה לשרת ה-proxy של ה-API שקורא את הערכים האלה. מידע נוסף זמין במאמר יצירת מוצרי API.
בדוגמה שלמעלה, שרת ה-API של ה-API שמכיל את מדיניות המכסה משתמש במדיניות ValidAPIKey שנקראת verify-api-key
, כדי לאמת את מפתח ה-API שמועבר בבקשה. לאחר מכן, מדיניות המכסה ניגשת למשתני הזרימה מהמדיניות ValidAPIKey כדי לקרוא את ערכי המכסה שהוגדרו במוצר ה-API. מידע נוסף על משתני זרימה של ValidAPIKey זמין במדיניות בנושא אימות מפתח API.
אפשרות אחרת היא להגדיר מאפיינים מותאמים אישית לאפליקציות או למפתחים ספציפיים, ולאחר מכן לקרוא את הערכים האלה במדיניות המכסה. לדוגמה, אתם רוצים להגדיר ערכי מכסה שונים לכל מפתח. במקרה כזה, צריך להגדיר אצל המפתח מאפיינים מותאמים אישית שכוללים את המגבלה, יחידת הזמן ומרווח הזמן. לאחר מכן הערכים האלה מופיעים במדיניות המכסה, כפי שמוצג כאן:
<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>
בדוגמה הזו נעשה שימוש גם במשתני הזרימה של ValidAPIKey כדי להפנות למאפיינים המותאמים אישית שהוגדרו במפתח.
אפשר להשתמש בכל משתנה כדי להגדיר את הפרמטרים של מדיניות המכסה. המשתנים האלה יכולים להגיע מהמקורות הבאים:
- משתני זרימה
- נכסים של המוצר, האפליקציה או המפתח של ה-API
- מפת ערך מפתח (KVM)
- כותרת, פרמטר של שאילתה, פרמטר טופס וכו'
לכל שרת proxy ל-API, אפשר להוסיף מדיניות מכסה שמפנה לאותו משתנה שאליו מתייחסות כל כללי מדיניות המכסה האחרים בכל שרתי ה-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 שעות. לכן, הרענון הבא יתבצע בשעה 15:30 (שעון גריניץ') ב-18 בפברואר 2017.
מונה גישה
<Quota name="QuotaPolicy"> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </Quota>
לשרת proxy של API יש גישה למשתני הזרימה שמוגדרים במדיניות המכסה. אפשר לגשת למשתני הזרימה האלה דרך שרת ה-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
, שיחות מעבר למספר הזה יידחו עד שהספירה תתאפס בתחילת השעה.
הזמן לאיפוס המונה מבוסס על השילוב של <Interval>
ו-<TimeUnit>
. לדוגמה, אם מגדירים את הערך של <Interval>
ל-12
למשך <TimeUnit>
שעה, המונה מתאפס כל 12 שעות.
אפשר להגדיר את <TimeUnit>
לדקה, לשעה, ליום, לשבוע או לחודש.
אפשר להפנות למדיניות הזו בכמה מקומות בשרת proxy ל-API. לדוגמה, אפשר למקם אותו ב-PreFlow של שרת ה-Proxy כדי להפעיל אותו בכל בקשה. לחלופין, אפשר למקם אותה בכמה תהליכי עבודה בשרת ה-API של שרת ה-proxy. אם משתמשים במדיניות הזו במספר מקומות בשרת ה-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>
כברירת מחדל, במדיניות מכסה מוגדרת מונה יחיד לשרת ה-proxy של ה-API, ללא קשר
למקור הבקשה. לחלופין, אפשר להשתמש במאפיין <Identifier>
עם מדיניות מכסה, כדי להפריד בין מונים על סמך הערך של
המאפיין <Identifier>
.
לדוגמה, אפשר להשתמש בתג <Identifier>
כדי להגדיר מונים נפרדים
לכל מזהה לקוח. בתגובה לבקשה לשרת ה-proxy, אפליקציית הלקוח מעבירה כותרת שמכילה
את השדה clientID
, כפי שמוצג בדוגמה שלמעלה.
אפשר לציין כל משתנה זרימה למאפיין <Identifier>
. לדוגמה, תוכלו לציין שפרמטר שאילתה בשם id
מכיל את המזהה הייחודי:
<Identifier ref="request.queryparam.id"/>
אם משתמשים במדיניות ConfirmAPIKey כדי לאמת את מפתח ה-API, או במדיניות OAuthV2
עם אסימוני OAuth, אפשר להשתמש במידע שבמפתח ה-API או באסימון כדי להגדיר מונים
נפרדים לאותה מדיניות מכסה. לדוגמה, בתג <Identifier>
הבא נעשה שימוש במשתנה הזרימה client_id
של מדיניות ValidAPIKey בשם 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 הודעות ביום הראשון או ביום האחרון של התקופה הזו. לא ניתן להגדיר אזור בקשות נוסף עד שמונה המכסות יתאפס אוטומטית בסוף פרק הזמן שצוין, או עד שהמכסה תאופס באופן מפורש באמצעות Reset Quota מדיניות.
גרסה של Quota שנקראת SpikeArrest מונעת עליות (או התפרצויות) של עומסי תנועה, שיכולות להיגרם מעלייה פתאומית בשימוש, מלקוחות עם באגים או מהתקפות זדוניות. למידע נוסף על SpikeArrest, אפשר לעיין במדיניות בנושא מעצר ספייק.
המכסות חלות על שרתי proxy נפרדים של ה-API ואינן מחולקות בין שרתי proxy של API. לדוגמה, אם יש לכם שלושה שרתי proxy של API במוצר API, מכסה אחת לא תחולק לכל שלושת שרתי ה-API, גם אם לכל שלושת ממשקי ה-API תהיה אותה הגדרה של מדיניות המכסה.
סוגי המדיניות בנושא מכסות
במדיניות המכסה יש תמיכה בכמה סוגים שונים של כללי מדיניות: ברירת המחדל, calendar
, flexi
ו-rollingwindow
. בטבלה הבאה נקבע לפי סוג המונה מתי מונה המכסות מתחיל ומתי הוא מתאפס:
יחידת זמן | איפוס ברירת המחדל (או ערך null) | איפוס יומן | איפוס גמיש |
---|---|---|---|
דקה | תחילת הדקה הבאה | דקה אחת אחרי <StartTime> |
דקה אחת אחרי הבקשה הראשונה |
hour | תחילת השעה הבאה | שעה אחת אחרי <StartTime> |
שעה אחת אחרי הבקשה הראשונה |
יום | חצות, לפי שעון גריניץ' (GMT) של היום הנוכחי | 24 שעות אחרי <StartTime> |
24 שעות אחרי שליחת הבקשה הראשונה |
שבוע | חצות לפי שעון גריניץ', בסוף השבוע | שבוע אחד אחרי <StartTime> |
שבוע לאחר הבקשה הראשונה |
חודש | חצות לפי שעון גריניץ' (GMT) ביום האחרון של החודש | חודש אחד (28 ימים) אחרי <StartTime> |
חודש (28 ימים) אחרי שליחת הבקשה הראשונה |
עבור type="calendar"
, עליכם לציין את הערך של
<StartTime>
.
בטבלה לא מופיע הערך של הסוג rollingwindow
. כדי לשנות את המכסות לחלונות, אפשר להגדיר את גודל ה "חלון" של המכסה, כמו חלון של שעה או יום. כשנשלחת בקשה חדשה, המדיניות קובעת אם חלה חריגה מהמכסה
ב'חלון הזמן' האחרון.
לדוגמה, אתם מגדירים חלון של שעתיים שמאפשר 1,000 בקשות. בקשה חדשה מתקבלת בשעה 16:45.המדיניות מחשבת את מספר המכסות של שעתיים האחרונות, כלומר את מספר הבקשות מאז 14:45. אם לא תחרגו ממגבלת המכסות בחלון הזמן של השעתיים, הבקשה תאושר.
דקה אחת אחר כך, בשעה 16:46, מגיעה בקשה נוספת. עכשיו המדיניות מחשבת את מספר המכסות החל משעה 14:46 כדי לקבוע אם חרגת מהמגבלה.
בסוג rollingwindow
, המונה אף פעם לא מתאפס, אבל הוא מחושב מחדש בכל בקשה.
הסבר על מוני מכסות
כברירת מחדל, במדיניות מכסה מוגדר מונה יחיד, בלי קשר למספר הפעמים שאתם
מפנים אליו בשרת proxy ל-API. השם של מונה המכסות מבוסס על
המאפיין name
של המדיניות.
לדוגמה: יוצרים מדיניות מכסה בשם MyQuotaPolicy
עם מגבלה ל-5 בקשות ומציבים אותה בכמה תהליכי עבודה (Flow A , B ו-C) בשרת ה-API של ה-API. למרות שמשתמשים בה בכמה תהליכי עבודה, היא כוללת מונה אחד שמתעדכן בכל המופעים של המדיניות:
- שלב א' מתבצע -> MyQuotaPolicy מתבצע והמונה שלו = 1
- שלב B מתבצע -> MyQuotaPolicy מתבצע והמונה שלו = 2
- שלב א' מבוצע -> MyQuotaPolicy מתבצע והמונה שלו = 3
- שלב ג' מתבצע -> MyQuotaPolicy מתבצע והמונה שלו = 4
- שלב א' מתבצע -> MyQuotaPolicy מתבצע והמונה שלו = 5
הבקשה הבאה לכל אחד משלושת התהליכים נדחתה כי מונה המכסות הגיע למגבלה.
שימוש באותה מדיניות מכסה ביותר ממקום אחד בתהליך של שרת ה-proxy של API, שעלול לגרום בטעות למכסה להתרוקן מהר מהצפוי, הוא אמצעי נגד דפוס שמתואר במאמר הספר של Apigee Edge Antipatterns.
לחלופין, אפשר להגדיר כמה כללי מדיניות מכסה בשרת ה-API של ממשק ה-API ולהשתמש במדיניות
שונה בכל תהליך. לכל מדיניות מכסה יש מונה משלה, בהתאם
למאפיין 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 עם מגבלות מכסה?
הפניה לרכיב
בטבלה הבאה מפורטים הרכיבים והתכונות שאפשר להגדיר במדיניות הזו. חשוב לשים לב ששילובי רכיבים מסוימים
הם בלעדיים או לא נדרשים. עיינו בדוגמאות לשימוש ספציפי. המשתנים
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
.
ברירת מחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: | מספר שלם |
מאפיינים
מאפיין | תיאור | ברירת המחדל | נוכחות |
---|---|---|---|
ספירה |
משמש לציון מספר ההודעות במכסה. לדוגמה, במאפיין |
2,000 | אופציונלי |
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>
בדוגמה הזו, במדיניות המכסה מוגדרים שני מוני מכסות שנקראים peak_time
ו-off_peak_time
.
ברירת מחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: | לא רלוונטי |
מאפיינים
מאפיין | תיאור | ברירת המחדל | נוכחות |
---|---|---|---|
מחלקה |
כאן מגדירים את השם של מונה המכסות. |
אין | חובה |
ספירה | מציין את מגבלת המכסה של המונה. | אין | חובה |
רכיב <מרווח>
משמש לציון מספר שלם (לדוגמה 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>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 |
נוכחות: | אופציונלי |
סוג: | בוליאני |
רכיב <סינכרוני>
צריך להגדיר את הערך 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 או מאפיין אחר. המאפיין בחלק מהמקרים צריך לאחזר את הגדרות המכסה מכל מקום שבו אין
|
לא רלוונטי | אופציונלי |
הרכיב <Message weight>
משמש לציון המשקל שהוקצה לכל הודעה. מומלץ להשתמש במשקל ההודעה כדי להגביר את ההשפעה של הודעות בקשה שצורכות, לדוגמה, יותר משאבי חישוב מאחרות.
לדוגמה, אתם רוצים שהודעות 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"/>
ברירת מחדל: | לא רלוונטי |
נוכחות: | אופציונלי |
סוג: |
מספר שלם |
משתני זרימה
משתני הזרימה המוגדרים מראש הבאים מאוכלסים באופן אוטומטי כשמדיניות מכסה מופעלת. מידע נוסף על משתני זרימה זמין במאמר מידע על משתנים.
משתנים | סוג | הרשאות | תיאור |
---|---|---|---|
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, באלפיות השנייה, שקובע מתי תוקף המכסה ויתחיל המרווח החדש במכסה. אם סוג המדיניות Quota הוא |
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 | בוליאני | הרשאת קריאה בלבד |
מציין אם המדיניות נכשלה (נכון או לא נכון). |
הפניה לשגיאות
בקטע הזה מתוארים קודי התקלות והודעות השגיאה שמוחזרים, ומשתני השגיאה שמוגדרים על ידי Edge כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת אם אתם מפתחים כללים לתיקון תקלות. מידע נוסף זמין במאמר מה צריך לדעת על שגיאות מדיניות ועל טיפול בפגמים.
שגיאות בזמן ריצה
השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.
קוד שגיאה | סטטוס HTTP | סיבה | תיקון |
---|---|---|---|
policies.ratelimit.FailedToResolveQuotaIntervalReference |
500 | מופיע אם הרכיב <Interval> לא מוגדר במדיניות המכסה. זהו רכיב חובה ומשמש לציון מרווח הזמן שרלוונטי למכסה. מרווח הזמן יכול להיות דקות, שעות, ימים, שבועות או חודשים, בהתאם למוגדר ברכיב <TimeUnit> . |
build |
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference |
500 | מופיע אם הרכיב <TimeUnit> לא מוגדר במדיניות המכסה. זהו רכיב חובה ומשמש לציון יחידת הזמן הרלוונטית למכסה. מרווח הזמן יכול להיות דקות, שעות, ימים, שבועות או חודשים. |
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 , הפריסה של שרת ה-API של שרת ה-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>
סכימות
נושאים קשורים
השוואה בין כללי המדיניות לגבי מכסות, נקודות עצירה ומגבלות על בו-זמנית