מדיניות בנושא מכסות

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

מכסה היא הקצאה של בקשות ש-proxy ל-API יקבל במהלך תקופת זמן מסוימת, כמו דקה, שעה, יום, שבוע או חודש. במדיניות בנושא מכסות מתנהלים מונים שסופרים את מספר הבקשות שהתקבלו על ידי proxy ל-API. היכולת הזו מאפשרת לספקי API לאכוף מגבלות על מספר הקריאות ל-API שאפליקציות מבצעות במהלך פרק זמן מסוים. באמצעות מדיניות מכסות, אפשר למשל להגביל את האפליקציות לבקשה אחת בדקה או ל-10,000 בקשות בחודש.

כש-proxy ל-API מגיע למגבלת המכסה שלו, Apigee דוחה קריאות ל-API עוקבות ומחזיר הודעת שגיאה עד שהמונה של המכסה מתאפס אוטומטית בסוף פרק הזמן שצוין, או עד שהמכסה מתאפסת באופן מפורש באמצעות מדיניות ResetQuota.

לדוגמה, אם מכסת ההודעות היא 10,000 הודעות בחודש, הגבלת הקצב מתחילה אחרי ההודעה ה-10,000. לא משנה אם 10,000 ההודעות נספרו ביום הראשון או ביום האחרון של אותו חודש.

המכסות חלות על שרתי proxy ספציפיים ל-API, ולא מתחלקות בין שרתי proxy ל-API. לדוגמה, אם יש לכם שלושה שרתי proxy ל-API במוצר API, לא תהיה מכסה אחת משותפת לכל השלושה, גם אם כולם משתמשים באותה הגדרת מדיניות מכסות.

אפשר להגדיר את אותה מכסה לכל האפליקציות שיש להן גישה ל-proxy ל-API, או להגדיר מכסות שונות בהתאם ל:

  • מוצר API שמכיל את proxy ל-API
  • האפליקציה ששולחת בקשה ל-API
  • מפַתח האפליקציה
  • השירות במעלה הזרם
  • קריטריונים רבים אחרים
  • שילובים של כל הקריטריונים הזמינים

אפשר להגדיר משקל באופן דינמי לכל קריאה ל-API. לדוגמה, באמצעות API של מודל שפה גדול (LLM), אפשר לאכוף מגבלת קצב על סמך מספר הטוקנים בבקשה או בתגובה, או בשניהם. בנוסף, מגבלות המכסה עצמן יכולות להיות דינמיות, כלומר אפשר להחיל מכסות מחמירות יותר כשהמערכת עמוסה יותר, או להקל על המכסות בשעות שאינן שעות שיא. מידע נוסף זמין במאמר בנושא הגדרת מכסות דינמיות.

אפשר גם להגדיר מכסות מותנות, שמאפשרות לקבוע אם מדיניות המכסות חלה על סמך הערכים של משתני זרימה. מידע על השימוש זמין במאמרים בנושא <Allow> ו-<Class>, וגם בדוגמה של הכיתה.

המדיניות הזו היא מדיניות ניתנת להרחבה, והשימוש בה עשוי להשפיע על העלויות או על הניצול, בהתאם לרישיון Apigee שלכם. מידע על סוגי המדיניות וההשלכות של השימוש זמין במאמר סוגי מדיניות.

סוגים של כללי מדיניות בנושא מכסות

מדיניות המכסות תומכת בכמה דרכים שונות שבהן מונה המכסות מתחיל ומתאפס. אפשר להגדיר באיזה מאפיין להשתמש באמצעות המאפיין type ברכיב <Quota>, כמו בדוגמה הבאה:

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

הערכים התקינים של type כוללים:

  • ‫calendar: הגדרת מכסה על סמך שעת התחלה מפורשת. המונה של המכסה עבור כל אפליקציה מתעדכן על סמך הערכים של <StartTime>,‏ <Interval> ו-<TimeUnit> שאתם מגדירים.
  • ‫rollingwindow: הגדרה של מכסה שמשתמשת ב'חלון נע' כדי לקבוע את השימוש במכסה. אתם מציינים את גודל החלון באמצעות הרכיבים <Interval> ו-<TimeUnit>. לדוגמה, יום אחד. כשמתקבלת בקשה חדשה, Apigee סופר את מספר הבקשות שהתקבלו במהלך המרווח הקודם. לדוגמה, אם חלון הזמן הוא יום אחד, כשמתקבלת בקשה בשעה 17:01, המדיניות סופרת את מספר הבקשות שהתקבלו מאז השעה 17:01 ביום הקודם כדי לקבוע אם הבקשה האחרונה תחרוג מהמכסה.
  • ‫flexi: מגדיר מכסת שימוש שגורמת למונה להתחיל לפעול כשמתקבלת הודעת הבקשה הראשונה מאפליקציה, ומתאפס על סמך הערכים של <Interval> ו-<TimeUnit>.

בטבלה הבאה מפורט מתי המכסה מתאפסת לכל סוג:

יחידת זמן סוג
‫default (או null) calendar flexi
דקה תחילת הדקה הבאה דקה אחרי <StartTime> דקה אחת אחרי הבקשה הראשונה
hour בתחילת השעה הבאה שעה אחרי <StartTime> שעה אחרי הבקשה הראשונה
יום חצות לפי שעון גריניץ' של היום הנוכחי 24 שעות אחרי <StartTime> ‫24 שעות אחרי הבקשה הראשונה
שבוע חצות שעון גריניץ' ביום ראשון בסוף השבוע שבוע אחרי <StartTime> שבוע אחרי הבקשה הראשונה
month חצות לפי שעון GMT ביום האחרון של החודש חודש אחד (28 ימים) אחרי <StartTime> חודש (28 ימים) אחרי הבקשה הראשונה

עבור type="calendar", צריך לציין את הערך של <StartTime>.

בטבלה לא מצוין מתי הספירה מתאפסת עבור סוג rollingwindow. הסיבה לכך היא שמכסות של חלון מתגלגל פועלות בצורה קצת שונה, על סמך חלון מבט לאחור, כמו שעה או יום. בסוג rollingwindow, הדלפק אף פעם לא מתאפס, אבל הוא מחושב מחדש בכל בקשה. כשמתקבלת בקשה חדשה, המדיניות קובעת אם חרגתם מהמכסה בחלון הזמן האחרון.

לדוגמה, אתם מגדירים חלון של שעתיים שמאפשר 1,000 בקשות. בקשה חדשה מתקבלת בשעה 16:45.המדיניות מחשבת את מספר הבקשות בחלון של שעתיים אחורה, כלומר מספר הבקשות מאז השעה 14:45. אם לא חרגתם ממגבלת המכסה בחלון הזמן של שעתיים, הבקשה תאושר.

דקה לאחר מכן, בשעה 16:46, מתקבלת בקשה נוספת. עכשיו המדיניות מחשבת את מספר המכסות מאז 14:46 כדי לקבוע אם חרגתם מהמגבלה.

הסבר על מוני המכסות

כשמדיניות מכסה מופעלת בתהליך של proxy ל-API, מוסיפים 1 למונה המכסה. כשהמונה מגיע למגבלה שלו, לא ניתן לבצע עוד קריאות ל-API שמשויכות למונה הזה. בהתאם להגדרה שבה אתם משתמשים למוצר ה-API, מדיניות הקצאה יכולה להשתמש בדלפק יחיד או בכמה דלפקים עצמאיים. חשוב להבין את התרחישים שבהם נעשה שימוש בכמה מוניטורים, ואיך הם מתנהגים.

הגדרת מכסות למוצרי API

במוצר API אפשר לציין הגדרות של מכסת שימוש ברמת המוצר או ברמת הפעולה הספציפית, או בשתי הרמות. אם proxy ל-API שלכם כלול במוצר API, אתם יכולים להגדיר את מדיניות המכסה כדי להשתמש בהגדרות המכסה (מספר ההקצאות, יחידת הזמן והמרווח) שמוגדרות במוצר הזה. הדרך הכי קלה לעשות את זה היא באמצעות הרכיב useQuotaConfigInAPIProduct. אפשרות אחרת היא להפנות להגדרות האלה במדיניות המכסות באמצעות הפניות למשתנים ספציפיים.

איך המכסות נספרות

כברירת מחדל, Apigee שומר על מונה נפרד של מכסת שימוש לכל פעולה שמוגדרת במוצר API, והכללים הבאים חלים:

  • אם לפעולה מוגדרת מכסה, הגדרות המכסה של הפעולה מקבלות עדיפות על פני הגדרות המכסה שמוגדרות ברמת המוצר.
  • אם לא מוגדרת מכסה לפעולה מסוימת, המערכת תחיל את הגדרות המכסה ברמת המוצר.
  • אם מוצר ה-API לא כולל הגדרות מכסה – לא ברמת המוצר ולא ברמת הפעולה – חלות הגדרות המכסה של מדיניות המכסה שצוינו לגבי מספר ההרשאות, יחידת הזמן והמרווח.

בכל המקרים, Apigee שומרת על מונה מכסה נפרד לכל פעולה שמוגדרת במוצר API. כל קריאה ל-API שתואמת לפעולה מסוימת תגדיל את הערך של המונה שלה.

הגדרת מדיניות המכסות לשימוש בהגדרות המכסות של מוצר ה-API

כדי להגדיר את מדיניות המכסות כך שתשתמש בהגדרות מכסות ממוצר API שאליו שייך ה-Proxy:

  1. יוצרים או מעדכנים מוצר API ומציינים את מאפיין quotaCounterScope כ-PRODUCT כדי לאכוף את המכסה ברמת מוצר ה-API, או מציינים את מאפיין quotaCounterScope כ-PROXY כדי לאכוף את המכסה ברמת ה-proxy ל-API.
  2. לכל פרוקסי API במוצר ה-API, מוסיפים מדיניות VerifyAPIKey או מדיניות OAuthv2 עם פעולת VerifyAccessToken בזרימת הבקשות לפני מדיניות Quota. במסגרת המדיניות הזו, מוצר ה-API מזוהה לכל בקשה.
  3. מגדירים את מדיניות המכסה כדי להשתמש במגבלות שמוגדרות במוצר ה-API, באמצעות UseQuotaConfigInAPIProduct.

הגדרת מוניטורים ברמת שרת ה-proxy של ה-API

אפשר להגדיר מוצר API כך שישמור על ספירת מכסה בהיקף של proxy ל-API. במקרה הזה, הגדרת המכסה שצוינה ברמת מוצר ה-API משותפת לכל הפעולות שלא צוינה להן מכסה משלהן. ההגדרה הזו יוצרת מונה ברמת ה-API proxy עבור מוצר ה-API הזה.

כדי להגדיר את התצורה הזו, צריך להשתמש ב-Apigee API‏/apiproducts כדי ליצור או לעדכן את המוצר ולהגדיר את המאפיין quotaCounterScope לערך PROXY בבקשת היצירה או העדכון. בהגדרה PROXY, בקשות שתואמות לאחת מהפעולות שהוגדרו למוצר ה-API שמשויך לאותו שרת proxy, ושאין להן הגדרות מכסה משלהן, ישתמשו במכסת בקשות משותפת לאותו שרת proxy.

באיור 1, פעולה 1 ופעולה 2 משויכות ל-Proxy1, ופעולה 4 ופעולה 5 משויכות ל-Proxy3. מכיוון שההגדרה quotaCounterScope=PROXY מוגדרת במוצר ה-API, כל אחת מהפעולות האלה משתמשת בהגדרת המכסה ברמת מוצר ה-API. פעולה 1 ו-2, שמשויכות ל-Proxy1, משתמשות בדלפק משותף, ופעולה 4 ו-5, שמשויכות ל-Proxy3, משתמשות בדלפק משותף נפרד. לפעולה 3 יש הגדרת מכסת שימוש משלה, ולכן היא משתמשת במונה משלה, בלי קשר לערך של מאפיין quotaCounterScope.

איור 1: שימוש בדגל quotaCounterScope

איך המכסות נספרות אם לא נעשה שימוש במוצרי API

אם אין מוצר API שמשויך לשרת proxy ל-API, מדיניות הקצאה שומרת על מונה יחיד, ללא קשר למספר הפעמים שמתייחסים אליו בשרת proxy ל-API. השם של מונה המכסות מבוסס על המאפיין name של המדיניות.

לדוגמה, יוצרים מדיניות מכסה בשם MyQuotaPolicy עם מגבלה של 5 בקשות ומציבים אותה בכמה תהליכים (תהליך א', תהליך ב' ותהליך ג') ב-proxy ל-API. למרות שהיא משמשת בכמה תהליכים, היא שומרת על מונה יחיד שמתעדכן על ידי כל המופעים של המדיניות:

  • תהליך A מבוצע -> מדיניות MyQuota מבוצעת והמונה שלה = 1
  • תהליך B מופעל -> מדיניות MyQuotaPolicy מופעלת והמונה שלה = 2
  • תהליך A מבוצע -> מדיניות MyQuota מבוצעת והמונה שלה = 3
  • תהליך C מופעל -> מדיניות MyQuotaPolicy מופעלת והמונה שלה = 4
  • תהליך A מבוצע -> מדיניות המכסה שלי מבוצעת והמונה שלה = 5

הבקשה הבאה לאחד משלושת התהליכים נדחית כי מונה המכסה הגיע למגבלה שלו.

שימוש באותה מדיניות מכסה ביותר ממקום אחד בתהליך של proxy ל-API, שעלול לגרום למכסה להיגמר מהר יותר מהצפוי, הוא דפוס אנטי שמתואר במאמר מבוא לדפוסי אנטי.

אפשרות אחרת היא להגדיר כמה מדיניות מכסה ב-proxy ל-API ולהשתמש במדיניות שונה בכל זרימה. לכל מדיניות מכסת שימוש יש מונה משלה, שמבוסס על מאפיין name של המדיניות.

יצירת כמה מונים באמצעות הגדרת מדיניות

אפשר להשתמש ברכיבים <Class> או <Identifier> במדיניות מכסת השימוש כדי להגדיר כמה מוני נפרדים במדיניות אחת. באמצעות הרכיבים האלה, אפשר להגדיר מדיניות אחת עם מוני נפרדים בהתאם לאפליקציה ששולחת את הבקשה, למפתח האפליקציה ששולח את הבקשה, למזהה לקוח או למזהה לקוח אחר ועוד. למידע נוסף על השימוש ברכיבים <Class> או <Identifier>, אפשר לעיין בדוגמאות שלמעלה.

סימון זמן

כל השעות שמוגדרות במכסת השימוש הן לפי אזור הזמן זמן אוניברסלי מתואם (UTC).

הפורמט של זמן המכסה הוא פורמט התאריך הבינלאומי שמוגדר בתקן הבינלאומי ISO 8601.

התאריכים מוגדרים כשנה, חודש ויום, בפורמט הבא: YYYY-MM-DD. לדוגמה, 2021-02-04 מייצג את התאריך 4 בפברואר 2021.

השעה ביום מוגדרת כשעות, דקות ושניות בפורמט הבא: hours:minutes:seconds. לדוגמה, 23:59:59 מייצג את השעה שנייה אחת לפני חצות.

שימו לב שיש שני סימונים, 00:00:00 ו-24:00:00, כדי להבחין בין שתי חצות שאפשר לשייך לתאריך אחד. לכן, 2021-02-04 24:00:00 הוא אותו תאריך ושעה כמו 2021-02-05 00:00:00. בדרך כלל עדיף להשתמש בסימון השני.

קבלת הגדרות מכסה מהגדרת מוצר ה-API

אפשר להגדיר מגבלות על מכסת השימוש בהגדרות של מוצרי API. המגבלות האלה לא אוכפות את המכסה באופן אוטומטי. במקום זאת, צריך להוסיף גם מדיניות מכסה ל-API Proxy כדי לקרוא את הערכים של מוצר ה-API. אלה כמה יתרונות להגדרת מכסה במוצר ה-API:

  • במדיניות בנושא מכסות אפשר להשתמש בהגדרה אחידה בכל שרתי ה-proxy של ה-API במוצר ה-API.
  • אפשר לבצע שינויים בהגדרת המכסה של מוצר API בזמן ריצה, ומדיניות המכסות שמפנה לערך הזה תתעדכן אוטומטית.

מידע נוסף על שימוש בהגדרות מכסה ממוצר API זמין בדוגמה 'מכסה דינמית' שבהמשך.

מידע על הגדרת מוצרי API עם מכסות זמין במאמר בנושא ניהול מוצרי API.

הגדרת מוני מכסה משותפים

במקרה הפשוט, מדיניות המכסה מגדילה את המונה שלה פעם אחת עבור כל בקשה שנשלחת ל-proxy ל-API, במהלך העיבוד הראשוני של הבקשה. במקרים מסוימים, יכול להיות שתרצו לבדוק אם חרגתם מהמכסה בטיפול הראשוני בבקשה הנכנסת, אבל להגדיל את המונה רק במהלך הטיפול בתגובה. השיטה הזו מתאימה אם אפשר לדעת את העלות או המשקל של קריאת ה-API רק אחרי שהמערכת במעלה הזרם או מערכת היעד מגיבה. במקרה של LLM API, יכול להיות שגודל התגובה בטוקנים יקבע את העלות. במקרה של BigQuery API, יכול להיות שהערך total_slot_ms בתשובה יקבע את העלות.

שלושה רכיבים של מדיניות המכסות – <SharedName>,‏ <CountOnly> ו-<EnforceOnly> – מאפשרים לכם, בשילוב, להתאים אישית את מדיניות המכסות כדי לאכוף את המכסה על הבקשה הנכנסת, ולצבור ספירות כנגד המכסה על סמך מידע שנגזר מתשובות היעד.

לדוגמה, נניח שיש לכם שרת proxy של API שמשתמש ב-LLM כיעד, ואתם רוצים לאכוף מכסה של 100,000 טוקנים לשעה. התשובות של ה-LLM מספקות ערך של totalTokenCount. כדי לעשות את זה:

  • מצרפים מדיניות Quota לזרימת הבקשות של ProxyEndpoint עם הגדרת האלמנט <SharedName> עם ערך שם והגדרת האלמנט <EnforceOnly> ל-true.
  • לזרימת התגובה של ProxyEndpoint, מצורפת מדיניות ExtractVariables כדי לחלץ את הערך totalTokenCount מהתגובה שהתקבלה מיעד ה-LLM.
  • מצרפים מדיניות מכסת שימוש שנייה לזרימת התגובה של ProxyEndpoint, כשהאלמנט <SharedName> מוגדר לאותו ערך שם כמו במדיניות מכסת השימוש הראשונה, והאלמנט <CountOnly> מוגדר ל-true. מגדירים את רכיב <MessageWeight> לשימוש בערך שחולץ totalTokenCount.

דוגמה לשימוש במונים משותפים מופיעה בקטע מונים משותפים בדוגמאות.

הגדרת מכסות דינמיות

מכסות דינמיות מאפשרות לכם להגדיר מדיניות מכסות אחת שמחילות הגדרות מכסות שונות על סמך מידע שמועבר למדיניות המכסות. מונח נוסף להגדרות מכסת נפח האחסון בהקשר הזה הוא תוכנית שירות. הקצאת נפח האחסון הדינמית בודקת את תוכנית השירות של האפליקציות ואז אוכפת את ההגדרות האלה.

אפשר להשתמש בכל משתנה כדי להגדיר את הפרמטרים של מדיניות המכסות. המשתנים האלה יכולים להגיע מהמקורות הבאים:

  • משתני זרימה
  • מאפיינים במוצר ה-API, באפליקציה או במפתח
  • מפת צמדי מפתח/ערך (KVM)
  • כותרת, פרמטר של שאילתה, פרמטר של טופס ועוד

לכל proxy ל-API אפשר להוסיף מדיניות מכסה שמפנה לאותו משתנה כמו כל שאר מדיניות המכסה בכל שאר הפרוקסי או למשתנים ייחודיים למדיניות ולפרוקסי הזה.

דוגמה להטמעה של מכסות דינמיות מופיעה במאמר בנושא מכסות דינמיות.

דוגמאות

בדוגמאות הקוד הבאות אפשר לראות איך מגדירים סוגים שונים של מכסות והגדרות שונות:

מכסות דינמיות

<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>

בדוגמה הזו, proxy ל-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 כדי להפנות למאפיינים המותאמים אישית שהוגדרו למפתח:

<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>

שעת התחלה

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2021-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

אם המכסה מוגדר עם type שמוגדר ל-calendar, צריך להגדיר ערך <StartTime> מפורש. ערך הזמן הוא הזמן לפי שעון GMT, ולא הזמן המקומי. אם לא מספקים ערך <StartTime> למדיניות מסוג calendar, ‏ Apigee מציג שגיאה.

מונה המכסה של כל אפליקציה מתעדכן על סמך הערכים <StartTime>,‏ <Interval> ו-<TimeUnit>. בדוגמה הזו, המכסה מתחילה להיספר ב-18 בפברואר 2021 בשעה 10:30 (GMT), ומתרעננת כל 5 שעות. לכן, הרענון הבא יהיה ב-18 בפברואר 2021 בשעה 15:30 לפי שעון GMT.

מונה גישה

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

ל-proxy ל-API יש גישה למשתני הזרימה שהוגדרו על ידי מדיניות מכסה. אפשר לגשת למשתני הזרימה האלה ב-proxy ל-API כדי לבצע עיבוד מותנה, לעקוב אחרי המדיניות כשהיא מתקרבת למגבלת המכסה, להחזיר את מונה המכסה הנוכחי לאפליקציה או מסיבות אחרות.

הגישה למשתני הזרימה של המדיניות מבוססת על המאפיין name של המדיניות. לכן, כדי לגשת למשתני הזרימה של המדיניות שצוינה למעלה ושמה <Quota>, צריך להשתמש בפורמט הבא:

  • ‫ratelimit.QuotaPolicy.allowed.count: מספר הפעמים שמותר להשתמש בשיטה.
  • ‫ratelimit.QuotaPolicy.used.count: הערך הנוכחי של המונה.
  • ‫ratelimit.QuotaPolicy.expiry.time: השעה לפי שעון UTC שבה הדלפק מתאפס.

יש עוד הרבה משתני זרימה שאפשר לגשת אליהם, כמו שמתואר בהמשך.

לדוגמה, אפשר להשתמש במדיניות AssignMessage הבאה כדי להחזיר את הערכים של משתני זרימת המכסות ככותרות תגובה:

<AssignMessage 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>

מונים משותפים

בדוגמה הבאה מוצג אופן ההגדרה של מונה משותף ל-API Proxy, שבו מונה המכסה גדל גם כשסטטוס התגובה של היעד הוא 200 HTTP. מכיוון ששתי מדיניות המכסות משתמשות באותו ערך <SharedName>, הן ישתמשו באותו מונה מכסות. מידע נוסף זמין במאמר בנושא הגדרת מוני מכסות משותפים.

דוגמה להגדרת ProxyEndpoint: 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>Quota-Enforce-Only</Name>
      </Step>
    </Request>
    <Response>
      <Step>
        <Name>EV-Token-Count</Name>
      </Step>
      <Step>
        <Name>Quota-Count-Only</Name>
      </Step>
    </Response>
    <Response/>
  </PreFlow>
  <Flows/>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <HTTPProxyConnection>
    <BasePath>/quota-shared-name</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="noroute"/>
</ProxyEndpoint>

דוגמה ראשונה למדיניות בנושא מכסה:

<Quota name="Quota-Enforce-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</Quota>

דוגמה למדיניות ExtractVariable:

<ExtractVariables name='EV-Token-Count'>
  <Source>response</Source>
  <VariablePrefix>extracted</VariablePrefix>
  <JSONPayload>
    <Variable name='tokenCount'>
      <JSONPath>$[1].usageMetadata.totalTokenCount</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

דוגמה שנייה למדיניות בנושא מכסות:

<Quota name="Quota-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>  <!-- Same name as the first Quota policy -->
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <MessageWeight ref="extracted.tokenCount"/>
</Quota>

בקשה ראשונה

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

אפשר להשתמש בקוד לדוגמה הזה כדי לאכוף מכסה של 10,000 קריאות לשעה. המדיניות מאפסת את מונה המכסה בראש כל שעה. אם המונה מגיע למכסת 10,000 שיחות לפני סוף השעה, שיחות מעבר למכסה הזו יידחו.

לדוגמה, אם המונה מתחיל ב-2021-07-08 07:00:00, הוא יתאפס ל-0 ב-2021-07-08 08:00:00 (שעה אחרי זמן ההתחלה). אם ההודעה הראשונה מתקבלת בשעה 2021-07-08 07:35:28 ומספר ההודעות מגיע ל-10,000 לפני השעה 2021-07-08 08:00:00, שיחות מעבר למספר הזה יידחו עד שהמספר יתאפס בתחילת השעה.

השעה לאיפוס המונה מבוססת על השילוב של <Interval> ושל <TimeUnit>. לדוגמה, אם מגדירים את <Interval> ל-12 עבור <TimeUnit> של שעה, המונה מתאפס כל 12 שעות. אפשר להגדיר את <TimeUnit> לדקה, לשעה, ליום, לשבוע או לחודש.

אפשר להפנות למדיניות הזו בכמה מקומות ב-proxy ל-API. לדוגמה, אפשר למקם אותו ב-Proxy PreFlow כדי שהוא יופעל בכל בקשה. לחלופין, אפשר למקם אותו בכמה רכיבי Flow ב-proxy ל-API. אם משתמשים במדיניות הזו בכמה מקומות בשרת הפרוקסי, היא שומרת על מונה יחיד שמתעדכן על ידי כל המופעים של המדיניות.

אפשרות אחרת היא להגדיר כמה כללי מדיניות לגבי מכסת בקשות ב-proxy ל-API. לכל מדיניות מכסה יש מונה משלה, שמבוסס על מאפיין name של המדיניות.

הגדרת מזהה

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2021-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"/>

אם משתמשים במדיניות 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. אם הערך של הכותרת לא תקין, המדיניות מחזירה שגיאה של חריגה מהמכסה.

רכיב <Quota>

אלה המאפיינים ורכיבי הצאצא של <Quota>. חשוב לדעת שחלק מהשילובים של רכיבים הם בלעדיים או לא נדרשים. דוגמאות לשימוש ספציפי

המשתנים verifyapikey.my-verify-key-policy.apiproduct.* שבהמשך זמינים כברירת מחדל כשמשתמשים במדיניות VerifyAPIKey שנקראת my-verify-key-policy כדי לבדוק את מפתח ה-API של האפליקציה בבקשה. ערכי המשתנים מגיעים מהגדרות המכסה במוצר ה-API שאליו משויך המפתח, כפי שמתואר במאמר קבלת הגדרות המכסה מהגדרת מוצר ה-API.

<Quota continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <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.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

המאפיינים הבאים ספציפיים למדיניות הזו:

מאפיין תיאור ברירת מחדל נוכחות
סוג

מגדירים את סוג מדיניות המכסה, שקובע מתי ואיך מונה המכסה בודק את השימוש במכסה ואיך הוא מתאפס.

אם לא מגדירים את type, המונה מתחיל בתחילת הדקה/השעה/היום/השבוע/החודש.

הערכים התקפים כוללים:

  • calendar
  • rollingwindow
  • flexi

תיאור מלא של כל סוג מופיע במאמר סוגים של מדיניות מכסות.

 לא רלוונטי אופציונלי

בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

מאפיין תיאור ברירת מחדל נוכחות
name

השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים.

אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.

 לא רלוונטי חובה
continueOnError

מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות.

הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף:

 FALSE אופציונלי
enabled

מגדירים את המדיניות למצב true כדי לאכוף אותה.

מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.

 TRUE אופציונלי
async

המאפיין הזה הוצא משימוש.

 FALSE הוצא משימוש

אלמנט <DisplayName>

משתמשים בו בנוסף למאפיין name כדי לתת למדיניות שם אחר בשפה טבעית, לסימון המדיניות בכלי לעריכת פרוקסי בממשק המשתמש לניהול.

<DisplayName>Policy Display Name</DisplayName>
ברירת מחדל

לא רלוונטי

אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין name של המדיניות.
נוכחות אופציונלי
סוג String

<Allow>

מציין את מגבלת הספירה של המכסה. אם מונה המדיניות מגיע לערך המגבלה הזה, בקשות נוספות נדחות עד שהמונה מתאפס.

יכול להכיל גם רכיב <Class> שיוצר תנאי לרכיב <Allow> על סמך משתנה של זרימת העבודה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג Integer או Complex
רכיב אב <Quota>
רכיבי צאצא <Class>

בהמשך מוצגות שלוש דרכים להגדיר את הרכיב <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.

אפשר גם לציין רכיב <Class> כרכיב צאצא של <Allow> כדי לקבוע את מספר המדיניות המותר על סמך משתנה זרימה. מערכת Apigee מתאימה את הערך של משתנה זרימה למאפיין class של רכיב <Allow>, כמו שמוצג בהמשך:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

בטבלה הבאה מפורטים המאפיינים של <Allow>:

מאפיין תיאור ברירת מחדל נוכחות
ספירה

משמש לציון מספר ההודעות במכסת נפח האחסון.

לדוגמה, אם ערך המאפיין count הוא 100, ערך המאפיין Interval הוא 1 וערך המאפיין TimeUnit הוא month, המשמעות היא מכסת 100 הודעות בחודש.

 2000 אופציונלי
countRef

משמש לציון משתנה של זרימת עבודה שמכיל את מספר ההודעות של מכסת השימוש. המאפיין countRef מקבל עדיפות על פני המאפיין count.

 ללא אופציונלי

<Class>

מאפשר להגדיר תנאי לערך של רכיב <Allow> על סמך הערך של משתנה זרימה. לכל תג צאצא <Allow> שונה של <Class>, המדיניות שומרת על מונה שונה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <Allow>
רכיבי צאצא ‫<Allow> (ילד/ה של <Class>)

כדי להשתמש ברכיב <Class>, מציינים משתנה של זרימת נתונים באמצעות המאפיין ref של הרכיב <Class>. ‫Apigee משתמש בערך של משתנה הזרימה כדי לבחור באחד מרכיבי הצאצא <Allow> כדי לקבוע את מספר הפעמים המותר של המדיניות. ‫Apigee מתאים את הערך של משתנה זרימה למאפיין 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. אם פרמטר השאילתה מכיל ערך לא תקין, המדיניות מחזירה שגיאה של חריגה מהמכסה.

בטבלה הבאה מפורטים המאפיינים של <Class>:

מאפיין תיאור ברירת מחדל נוכחות
ref משתמשים במשתנה הזה כדי לציין משתנה של זרימה שמכיל את סוג המכסה של מכסה מסוימת. ללא חובה

<Allow> (ילד של <Class>)

מציין את המגבלה של מונה מכסת השימוש שהוגדר על ידי הרכיב <Class>. לכל תג צאצא שונה של <Allow> <Class>, המדיניות שומרת על מונה שונה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <Class>
רכיבי צאצא ללא

לדוגמה:

    <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow count="5000"/>
        <Allow count="1000"/>
      </Class>
    </Allow>

בדוגמה הזו, מדיניות הקצאה לשירות שומרת שני מוני מכסה בשמות peak_time ו-off_peak_time. השימוש באחד מהם תלוי בפרמטר השאילתה שמועבר, כפי שמוצג בדוגמה <Class>.

בטבלה הבאה מפורטים המאפיינים של <Allow>:

מאפיין תיאור ברירת מחדל נוכחות
מחלקה ההגדרה הזו מגדירה את השם של מונה המכסות. ללא חובה
ספירה מציינת את מגבלת המכסה של הדלפק. ללא חובה

<Interval>

מציין את מספר התקופות שבהן מחושבות המכסות.

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג מספר שלם
רכיב אב <Quota>
רכיבי צאצא ללא

משתמשים במאפיין הזה כדי לציין מספר שלם (לדוגמה, 1, 2, 5, 60 וכן הלאה) שיוצמד לרכיב <TimeUnit> שציינתם (דקה, שעה, יום, שבוע או חודש) כדי לקבוע תקופת זמן שבמהלכה Apigee מחשב את השימוש במכסה.

לדוגמה, אינטרוול של 24 עם <TimeUnit> של hour פירושו שהמכסה תחושב במהלך 24 שעות.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

בטבלה הבאה מפורטים המאפיינים של <Interval>:

מאפיין תיאור ברירת מחדל נוכחות
ref

משתמשים בו כדי לציין משתנה של זרימת עבודה שמכיל את המרווח של מכסת שימוש. הערך ref מקבל עדיפות על פני ערך מפורש של מרווח זמן. אם מציינים גם הפניה וגם ערך, ההפניה מקבלת עדיפות. אם הערך ref לא נפתר בזמן הריצה, המערכת משתמשת בערך.

 ללא אופציונלי

<TimeUnit>

מציינת את יחידת הזמן שחלה על המכסה.

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג String
רכיב אב <Quota>
רכיבי צאצא ללא

בוחרים מתוך minute, hour, day, week, month או year.

לדוגמה, אם Interval הוא 24 ו-TimeUnit הוא hour, המכסה תחושב במהלך 24 שעות.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
ברירת מחדל: ללא
נוכחות: חובה
סוג: String

בטבלה הבאה מפורטים המאפיינים של <TimeUnit>:

מאפיין תיאור ברירת מחדל נוכחות
ref מציין משתנה של תהליך עבודה שמכיל את יחידת הזמן למכסת השימוש. ref מקבל עדיפות על פני ערך מפורש של פרק זמן. אם ref לא נפתר בזמן הריצה, נעשה שימוש בערך המרווח. ללא אופציונלי

<StartTime>

אם הערך של type הוא calendar, מציינים את התאריך והשעה שבהם מתחיל מונה המכסה, ללא קשר לשאלה אם התקבלו בקשות מאפליקציות כלשהן.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי (חובה אם הערך של type הוא calendar)
סוג מחרוזת בפורמט תאריך ושעה של ISO 8601
רכיב אב <Quota>
רכיבי צאצא ללא

לדוגמה:

<StartTime>2021-7-16 12:00:00</StartTime>

<Distributed>

המדיניות קובעת אם Apigee משתמש בצומת אחד או יותר כדי לעבד בקשות.

ערך ברירת המחדל FALSE
חובה? אופציונלי
סוג בוליאני
רכיב אב <Quota>
רכיבי צאצא ללא

הערך true מציין שהמדיניות צריכה לשמור על מונה מרכזי ולסנכרן אותו באופן רציף בכל הצמתים. הצמתים יכולים להיות באזורי זמינות שונים או באזורים שונים.

אם משתמשים בערך ברירת המחדל false, יכול להיות שתחרגו מהמכסה כי הספירה של כל צומת לא משותפת:

<Distributed>false</Distributed>

כדי להבטיח שהמונים מסונכרנים ומתעדכנים בכל בקשה, מגדירים את <Distributed> ואת <Synchronous> ל-true:

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous>

קובעת אם לעדכן מונה מכסה מבוזר באופן סינכרוני.

ערך ברירת המחדל FALSE
חובה? אופציונלי
סוג בוליאני
רכיב אב <Quota>
רכיבי צאצא ללא

הערך true מאפשר לעדכן באופן סינכרוני את מונה המכסה המבוזר. כלומר, העדכונים של המונים מתבצעים באותו הזמן שבו המכסה נבדקת בבקשה שנשלחת אל ה-API. מגדירים את הערך true אם חשוב לכם שלא לאפשר קריאות ל-API מעבר למכסה.

מגדירים את הערך false כדי לעדכן את מונה המכסות באופן אסינכרוני. המשמעות היא שאולי חלק מהקריאות ל-API שחורגות מהמכסה יתבצעו, בהתאם למועד שבו מונה המכסות במאגר המרכזי מתעדכן באופן אסינכרוני. עם זאת, לא תיתקלו בהשפעות פוטנציאליות על הביצועים שקשורות לעדכונים סינכרוניים.

ברירת המחדל של מרווח העדכון האסינכרוני היא 10 שניות. כדי להגדיר את ההתנהגות האסינכרונית הזו, משתמשים ברכיב <AsynchronousConfiguration>.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

המדיניות הזו מגדירה את מרווח הזמן בין סנכרונים של מוני מכסות מבוזרים, אם רכיב ההגדרה של המדיניות <Synchronous> לא קיים או קיים ומוגדר לערך false. מערכת Apigee מתעלמת מהאלמנט הזה אם המדיניות <Synchronous> מוגדרת כ-true.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <Quota>
רכיבי צאצא <SyncIntervalInSeconds>
<SyncMessageCount>

אפשר לציין את אופן הסנכרון באמצעות רכיבי הצאצא <SyncIntervalInSeconds> או <SyncMessageCount>. אפשר להשתמש באחד מהאלמנטים או בשניהם. לדוגמה,

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

או

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • אם מופיע רק <SyncIntervalInSeconds>, המכסה מסתנכרנת כל N שניות, כאשר N הוא הערך שצוין ברכיב, ללא קשר למספר ההודעות שטופלו.
  • אם מופיע רק <SyncMessageCount>, המכסה מסתנכרן כל M הודעות, כאשר M הוא הערך שצוין ברכיב, או כל 10 שניות, לפי המוקדם מביניהם.
  • אם שני הרכיבים קיימים, המכסה מסתנכרנת כל M הודעות או כל N שניות, לפי המוקדם מביניהם.
  • אם התג <AsynchronousConfiguration> לא מופיע או שאף אחד מהרכיבים המשניים לא מופיע, המכסה מסתנכרנת כל 10 שניות, בלי קשר למספר ההודעות שטופלו.

<SyncIntervalInSeconds>

ההגדרה הזו מבטלת את התנהגות ברירת המחדל, שבה מתבצעים עדכונים אסינכרוניים אחרי מרווח של 10 שניות.

ערך ברירת המחדל ‫10 שניות
חובה? אופציונלי
סוג מספר שלם
רכיב אב <AsynchronousConfiguration>
רכיבי צאצא ללא
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

מרווח הסנכרון צריך להיות גדול מ-10 שניות או שווה לו, כפי שמתואר במגבלות.

<SyncMessageCount>

מציינת את מספר הבקשות לעיבוד לפני סנכרון מונה המכסה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג מספר שלם
רכיב אב <AsynchronousConfiguration>
רכיבי צאצא ללא
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

אם משתמשים בהגדרה שבדוגמה הזו, בכל צומת, ספירת המכסה תסתנכרן אחרי כל 5 בקשות, או כל 10 שניות, לפי מה שיקרה קודם.

<Identifier>

הגדרת המדיניות ליצירת מוניטורים ייחודיים על סמך משתנה זרימה.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג String
רכיב אב <Quota>
רכיבי צאצא ללא

באמצעות רכיב המזהה, אפשר להקצות ספירות של שיחות לדליים נפרדים שמוגדרים לפי הערך במשתנה של זרימת נתונים. לדוגמה, אפשר להשתמש במשתנה developer.id, שאוכלס אחרי מדיניות VerifyAPIKey, כדי לאכוף מגבלת מכסה אחת על כל המופעים של כל האפליקציות שנוצרו על ידי כל מפתח ספציפי, או להשתמש במשתנה client_id כדי לאכוף מגבלת מכסה על כל אפליקציה ספציפית. ההגדרה של האפשרות השנייה נראית כך:

<Identifier ref="client_id"/>

אפשר להפנות למשתנה מותאם אישית שאולי הגדרתם באמצעות המדיניות AssignMessage או המדיניות JavaScript, או למשתנה שמוגדר באופן מרומז, כמו משתנים שמוגדרים באמצעות המדיניות VerifyAPIKey או המדיניות VerifyJWT. מידע נוסף על משתנים זמין במאמר שימוש במשתני Flow. רשימה של משתנים מוכרים שמוגדרים על ידי Apigee זמינה במאמר Flow variables reference.

אם לא משתמשים ברכיב הזה, המדיניות מקצה את כל מספרי השיחות למונה יחיד עבור מדיניות המכסות הספציפית.

האלמנט הזה מוסבר גם במאמר איך פועלת מדיניות המכסה כשלא מצוין מזהה?

בטבלה הבאה מתוארים המאפיינים של <Identifier>:

מאפיין תיאור ברירת מחדל נוכחות
ref

מציינים משתנה של זרימת נתונים שמזהה את המונה שבו רוצים להשתמש לבקשה. המשתנה יכול להתייחס לכותרת HTTP, לפרמטר של שאילתה, לפרמטר של טופס או לאלמנט של תוכן ההודעה, או לערך אחר כלשהו שמזהה איך להקצות את מספר השיחות.

המשתנה הנפוץ הוא client_id. הטוקן client_id נקרא גם מפתח API או טוקן צרכן, והוא נוצר לאפליקציה כשהיא נרשמת בארגון ב-Apigee. אפשר להשתמש במזהה הזה אם הפעלתם מדיניות הרשאות של מפתח API או OAuth עבור ה-API שלכם.

 לא רלוונטי אופציונלי

<MessageWeight>

מציין את המשקל שמוקצה לכל הודעה לצורך מכסת השימוש. אם לא מציינים את <MessageWeight>, כל הבקשות מקבלות את אותו משקל בספירת המכסה. משתמשים באלמנט הזה כדי להגדיר מכסות משוקללות על סמך תוכן או סוג ההודעה.

לדוגמה, אפשר להשתמש במשקל ההודעה כדי לציין שהודעות POST צורכות יותר מכסה מהודעות GET.

כשעובדים עם ממשקי API שמבוססים על LLM, אפשר להקצות משקלים שונים על סמך מספר הטוקנים בבקשות, בתגובות או בשניהם.

ערך ברירת מחדל לא רלוונטי
חובה? אופציונלי
סוג מספר שלם
רכיב אב <Quota>
רכיבי צאצא ללא

אם רוצים שמשקלן של POST הודעות יהיה כפול ממשקלן של GET הודעות, צריך להגדיר את <MessageWeight> ל-2 עבור POST ול-1 עבור GET. אם המכסה הוא 10 הודעות בדקה, ושרת ה-proxy מעבד 5 בקשות POST ב-35 השניות הראשונות, השרת דוחה בקשות נוספות, POST או GET, עד שהמונה מתאפס.

צריך לציין ערך שמייצג את <MessageWeight> באמצעות משתנה של זרימת נתונים. אפשר לחלץ את הערך מכותרות HTTP, מפרמטרים של שאילתות, ממטען ייעודי (payload) של בקשת XML או JSON או מכל משתנה אחר של זרימת נתונים. לדוגמה, אפשר לחלץ את הערך ממטען ייעודי (payload) של תגובה למשתנה בשם extracted.message_weight, ואז להשתמש בו בשביל <MessageWeight>:

<MessageWeight ref="extracted.message_weight"/>

אם משתנה הזרימה הוא 0, הבקשה לא תשפיע על המונה.

<UseQuotaConfigInAPIProduct>

הגדרות מכסת השימוש במוצר API, כמו יחידות הזמן, המרווח והערך המקסימלי המותר.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <Quota>
רכיבי צאצא <DefaultConfig>

אם מוסיפים את הרכיב <UseQuotaConfigInAPIProduct> למדיניות בנושא מכסות, מערכת Apigee מתעלמת מכל רכיבי הצאצא <Allow>, ‏<Interval> ו-<TimeUnit> של <Quota>.

הרכיב <UseQuotaConfigInAPIProduct> הוא פשוט קונטיינר להגדרות ברירת המחדל שאתם מגדירים באמצעות הרכיב <DefaultConfig>, כמו בדוגמה הבאה:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

אפשר להשתמש במאפיין stepName כדי להפנות אל מדיניות VerifyAPIKey או אל פעולת מדיניות ValidateToken של מדיניות OAuthv2 בתהליך.

בטבלה הבאה מתוארים המאפיינים של <UseQuotaConfigInAPIProduct>:

מאפיין תיאור ברירת מחדל נוכחות
stepName מזהה את השם של מדיניות האימות בתהליך. יעד יכול להיות מדיניות VerifyAPIKey או מדיניות OAuthv2. לא רלוונטי חובה

למידע נוסף, קראו את המאמרים הבאים:

<DefaultConfig>

מכיל ערכי ברירת מחדל למכסה של מוצר API. כשמגדירים <DefaultConfig>, צריך להגדיר גם את שלושת רכיבי הצאצא.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג סוג מורכב
רכיב אב <UseQuotaConfigInAPIProduct>
רכיבי צאצא <Allow>
<Interval>
<TimeUnit>

אפשר להגדיר את הערכים האלה גם בפעולה של מוצר ה-API (באמצעות ממשק המשתמש או API products API) וגם במדיניות בנושא מכסות. אבל אם תעשו את זה, ההגדרות במוצר ה-API יקבלו עדיפות והמערכת תתעלם מההגדרות במדיניות בנושא מכסות.

התחביר של הרכיב הזה הוא:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

בדוגמה הבאה מצוינת מכסת שימוש של 10,000 כל שבוע:

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

למידע נוסף, קראו את המאמרים הבאים:

<SharedName>

מציין שמדיניות המכסות הזו היא משותפת. כל כללי המכסה ב-proxy ל-API עם אותו ערך <SharedName> חולקים את אותו מונה מכסה בסיסי.

מידע נוסף ודוגמאות זמינים במאמר בנושא הגדרת מוני מכסות משותפים.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג String
רכיב אב <Quota>
רכיבי צאצא ללא

<CountOnly>

מציבים מדיניות Quota עם הרכיב הזה שמוגדר ל-true בשלב בתהליך התגובה של ProxyEndpoint כדי להגדיל את מונה המכסה הבסיסי בלי לשלוח שגיאה בחזרה ללקוח כשחורגים ממגבלת המכסה. אם הרכיב הזה קיים, צריך לציין גם את הרכיב <SharedName> ואסור לציין את הרכיב <EnforceOnly>.

מידע נוסף ודוגמאות זמינים במאמר בנושא הגדרת מוני מכסות משותפים.

ערך ברירת מחדל FALSE
חובה? אופציונלי
סוג בוליאני
רכיב אב <Quota>
רכיבי צאצא ללא

<EnforceOnly>

מציבים מדיניות מכסה עם הרכיב הזה שמוגדר ל-true בתהליך הבקשה של proxy ל-API כדי לאכוף מכסה בלי להגדיל את מונה המכסה. ההגדרה הזו מאפשרת אכיפה מושהית של מגבלות קצב על סמך משקלי הודעות שאפשר לדעת רק בתהליך התגובה. אם הרכיב הזה קיים, חובה לציין גם את <SharedName> ואסור לציין את הרכיב <CountOnly>.

מידע נוסף ודוגמאות זמינים במאמר בנושא הגדרת מוני מכסות משותפים.

ערך ברירת המחדל FALSE
חובה? אופציונלי
סוג בוליאני
רכיב אב <Quota>
רכיבי צאצא ללא

משתני זרימה

משתני ה-Flow המוגדרים מראש הבאים מאוכלסים באופן אוטומטי כשמדיניות Quota מופעלת. מידע נוסף זמין במאמר חומר עזר בנושא משתני זרימה.

משתנים סוג הרשאות תיאור
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 (באלפיות שנייה), שקובעת מתי המכסה מסתיימת ומתי מתחיל מרווח הזמן החדש של המכסה.

אם סוג המדיניות של המכסה הוא rollingwindow, הערך הזה לא תקין כי מרווח המכסה אף פעם לא פג.
ratelimit.{policy_name}.identifier String קריאה בלבד מחזירה את ההפניה למזהה (הלקוח) שמצורפת למדיניות
ratelimit.{policy_name}.class String קריאה בלבד הפונקציה מחזירה את המחלקה שמשויכת למזהה הלקוח.
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).

הפניה לשגיאה

בקטע הזה מתוארים קודי התקלה והודעות השגיאה שמוחזרים, ומשתני התקלה שמוגדרים על ידי Apigee כשמדיניות כזו מפעילה שגיאה. חשוב לדעת את המידע הזה אם אתם מפתחים כללי תקלות לטיפול בתקלות. מידע נוסף על שגיאות שקשורות למדיניות ועל טיפול בשגיאות

שגיאות זמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד תקלה סטטוס HTTP מטרה תיקון
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 השגיאה מתרחשת אם הרכיב <Interval> לא מוגדר במדיניות Quota. האלמנט הזה הוא חובה ומשמש לציון מרווח הזמן שרלוונטי למכסה. מרווח הזמן יכול להיות דקות, שעות, ימים, שבועות או חודשים, כפי שמוגדר ברכיב <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 השגיאה מתרחשת אם רכיב <TimeUnit> לא מוגדר במדיניות Quota. הרכיב הזה הוא חובה ומשמש לציון יחידת הזמן שחלה על המכסה. מרווח הזמן יכול להיות בדקות, בשעות, בימים, בשבועות או בחודשים.
policies.ratelimit.InvalidMessageWeight 500 השגיאה מתרחשת אם הערך של רכיב <MessageWeight> שצוין באמצעות משתנה של זרימת נתונים לא תקין (ערך שאינו מספר שלם).
policies.ratelimit.QuotaViolation 500 הייתה חריגה ממגבלת המכסה. לא רלוונטי

שגיאות בהטמעה

שם השגיאה מטרה תיקון
InvalidQuotaInterval אם מרווח המכסה שצוין ברכיב <Interval> הוא לא מספר שלם, פריסת ה-proxy ל-API תיכשל. לדוגמה, אם מרווח המכסה שצוין הוא 0.1 ברכיב <Interval>, פריסת ה-proxy ל-API תיכשל.
InvalidQuotaTimeUnit אם יחידת הזמן שצוינה ברכיב <TimeUnit> לא נתמכת, פריסת ה-proxy ל-API תיכשל. יחידות הזמן הנתמכות הן minute,‏ hour,‏ day,‏ week ו-month.
InvalidQuotaType אם סוג המכסה שצוין במאפיין type ברכיב <Quota> לא תקין, פריסת ה-proxy ל-API תיכשל. סוגי המכסות הנתמכים הם default,‏ calendar,‏ flexi ו-rollingwindow.
InvalidStartTime אם הפורמט של השעה שצוינה ברכיב <StartTime> לא תקין, פריסת ה-proxy ל-API תיכשל. הפורמט התקין הוא yyyy-MM-dd HH:mm:ss, שהוא פורמט התאריך והשעה של ISO 8601. לדוגמה, אם השעה שצוינה ברכיב <StartTime> היא 7-16-2017 12:00:00, פריסת ה-proxy ל-API תיכשל.
StartTimeNotSupported אם מציינים את הרכיב <StartTime> שסוג המכסה שלו לא מוגדר כ-calendar, פריסת proxy ל-API תיכשל. האלמנט <StartTime> נתמך רק בסוג המכסה calendar. לדוגמה, אם המאפיין type מוגדר לערך flexi או rollingwindow ברכיב <Quota>, הפריסה של proxy ל-API תיכשל.
InvalidSynchronizeIntervalForAsyncConfiguration אם הערך שצוין לרכיב <SyncIntervalInSeconds> בתוך הרכיב <AsynchronousConfiguration> במדיניות Quota קטן מאפס, הפריסה של proxy ל-API נכשלת.
InvalidAsynchronizeConfigurationForSynchronousQuota אם הערך של רכיב <AsynchronousConfiguration> מוגדר כ-true במדיניות Quota, שמוגדרת בה גם הגדרה אסינכרונית באמצעות רכיב <AsynchronousConfiguration>, הפריסה של ה-proxy ל-API תיכשל.

משתני תקלות

המשתנים האלה מוגדרים כשהמדיניות הזו מפעילה שגיאה. מידע נוסף על שגיאות שקשורות למדיניות

משתנים כאשר: דוגמה
fault.name="fault_name" ‫fault_name הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. 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>

סכימות

נושאים קשורים

מדיניות ResetQuota

מדיניות SpikeArrest

השוואה בין מדיניות הגבלת קצב הבקשות