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

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

הדף הזה רלוונטי ל-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> שעה אחרי הבקשה הראשונה
יום חצות לפי שעון גריניץ' (GMT) של היום הנוכחי 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 משותפת לכל הפעולות שלא צוינה להן מכסה משלהן. ההגדרה הזו יוצרת מונה ברמת שרת ה-proxy של ה-API עבור מוצר ה-API הזה.

כדי להגדיר את ההגדרה הזו, צריך להשתמש ב-/apiproducts Apigee API כדי ליצור או לעדכן את המוצר ולהגדיר את המאפיין 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 מופעל -> מדיניות הקצאה MyQuotaPolicy מופעלת והמונה שלה = 1
  • תהליך B מופעל -> מדיניות המכסה שלי מופעלת והמונה שלה = 2
  • תהליך A מבוצע -> מדיניות MyQuotaPolicy מבוצעת והמונה שלה = 3
  • תהליך C מבוצע -> מדיניות המכסה שלי מבוצעת והמונה שלה = 4
  • תהליך A מבוצע -> מדיניות MyQuota מבוצעת והמונה שלה = 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 רק אחרי שהמערכת במעלה הזרם או מערכת היעד מגיבה. במקרה של API של מודל שפה גדול (LLM), גודל התגובה בטוקנים עשוי לקבוע את העלות. במקרה של 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>

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

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

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

בדוגמה הבאה מוצג אופן ההגדרה של מונה משותף ל-proxy ל-API, שבו מונה המכסה גדל גם כשסטטוס התגובה של היעד הוא 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 השאילתות לפני סוף השעה, השאילתות מעבר ל-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> ל-hour (שעה), המונה מתאפס כל 12 שעות. אפשר להגדיר את <TimeUnit> ל-minute (דקה), hour (שעה), day (יום), week (שבוע) או month (חודש).

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

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

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

בטבלה הבאה מתוארים המאפיינים של <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> למדיניות בנושא מכסות, המערכת מתעלמת מכל רכיבי הצאצא <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>

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

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

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

<EnforceOnly>

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

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

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

משתנים בתהליך

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

אם סוג המדיניות של המכסה הוא 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 policy

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