מדיניות של SpikeArst

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

סמל של עצירת ביניים בממשק המשתמש של Edge

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

רכיב <SpikeArrest>

מגדיר את המדיניות בנושא מעצר שיא.

ערך ברירת מחדל מידע נוסף מופיע בכרטיסייה מדיניות ברירת המחדל למטה
חובה? אופציונלי
סוג התוצאות מורכבות מדי אובייקט
רכיב הורה לא רלוונטי
רכיבים צאצאים <Identifier>
<MessageWeight>
<Rate> (חובה)
<UseEffectiveCount>

תחביר

הרכיב <SpikeArrest> משתמש בתחביר הבא:

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <DisplayName>display_name</DisplayName>
  <Properties/>
  <Identifier ref="flow_variable"/>
  <MessageWeight ref="flow_variable"/>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

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

בדוגמה הבאה אפשר לראות את הגדרות ברירת המחדל כשמוסיפים מדיניות 'עצרת שיא' אל בממשק המשתמש של Edge:

<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest-1">
  <DisplayName>Spike Arrest-1</DisplayName>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

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

מאפיין ברירת מחדל חובה? תיאור
name לא רלוונטי נדרש

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

אפשר להשתמש ברכיב <DisplayName> כדי להוסיף תווית למדיניות בכלי לעריכת שרת proxy של ממשק המשתמש לניהול, ולהשתמש בשם אחר בשפה טבעית.
continueOnError false אופציונלי צריך להגדיר את הערך 'False' כדי להחזיר שגיאה כשהמדיניות נכשלת. זו התנהגות צפויה ברוב סוגי המדיניות. הערך של הפרמטר הוא TRUE כדי שביצוע הפעולות יתבצע גם אחרי שמדיניות תיכשל.
enabled true אופציונלי כדי לאכוף את המדיניות צריך להגדיר את הערך True. מגדירים את המדיניות כ-"false" כדי "להשבית" את המדיניות. המדיניות הזו לא תיאכף גם אם היא תצורף לתהליך.
async   false הוצא משימוש המאפיין הזה הוצא משימוש.

דוגמאות

בדוגמאות הבאות אפשר לראות חלק מהדרכים שבהן אפשר להשתמש במדיניות 'עצרת שיא':

דוגמה 1

בדוגמה הבאה הקצב נקבע ל-5 לשנייה:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

המדיניות מקלה את הקצב של בקשה אחת שמותרת כל 200 אלפיות השנייה (1000/5).

דוגמה 2

בדוגמה הבאה נקבע את הקצב ל-12 לדקה:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
</SpikeArrest>

המדיניות לדוגמה הזו מקלה את התעריף לבקשה אחת שמותרת בכל חמש שניות (60/12).

דוגמה 3

הדוגמה הבאה מגבילה את הבקשות ל-12 בקשות לדקה (בקשה אחת מותרת כל חמש בקשות שניות, או 60/12):

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
</SpikeArrest>

בנוסף, הרכיב <MessageWeight> מקבל ערך מותאם אישית ( הכותרת weight) להתאמה של משקלי ההודעה באפליקציות או בלקוחות ספציפיים. הזה מספקת שליטה נוספת על ויסות נתונים (throttle) לישויות שמזוהות <Identifier>.

דוגמה 4

הדוגמה הבאה מנחה את Spike Arrest לחפש ערך של זמן ריצה דרך בקשה שמועברת בתור משתנה הזרימה request.header.runtime_rate:

<SpikeArrest name="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
</SpikeArrest>

הערך של משתנה הזרימה חייב להיות בצורת intpm או intps

כדי לנסות את הדוגמה הזו, צריך להריץ בקשה כמו:

curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'

הפניה לרכיב צאצא

בקטע הזה מתוארים רכיבי הצאצא של <SpikeArrest>.

<DisplayName>

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

הרכיב <DisplayName> משותף לכל כללי המדיניות.

ערך ברירת מחדל לא רלוונטי
חובה? זה שינוי אופציונלי. אם משמיטים את הערך של <DisplayName>, נעשה שימוש במאפיין name של המדיניות
סוג מחרוזת
רכיב הורה &lt;PolicyElement&gt;
רכיבים צאצאים ללא

הרכיב <DisplayName> משתמש בתחביר הבא:

תחביר

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

דוגמה

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

לרכיב <DisplayName> אין מאפיינים או רכיבי צאצא.

<Identifier>

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

יש להשתמש בשילוב עם הרכיב <MessageWeight> כדי לבצע פעולות פרטניות יותר שליטה על ויסות נתונים (throttle) של בקשות.

אם משאירים את הרכיב <Identifier> ריק, המערכת אוכפת הגבלת קצב אחת לכל הבקשות באותו שרת Proxy ל-API.

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

תחביר

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Identifier ref="flow_variable"/>
</SpikeArrest>

דוגמה 1

הדוגמה הבאה מחילה את המדיניות Spike Arrest לפי מזהה מפתח:

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
</SpikeArrest>

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

מאפיין תיאור ברירת מחדל נוכחות
ref מזהה את המשתנה שלפיו Spike Arrest מקבץ בקשות נכנסות. אפשר להשתמש בכל משתנה זרימה כדי לציין לקוח ייחודי, כמו הלקוח הזמין עם VerifyAPIKey אפשר גם להגדיר משתנים מותאמים אישית באמצעות מדיניות JavaScript או מדיניות AssignMessage. לא רלוונטי חובה

המרכיב הזה מתואר גם בפוסט הבא של קהילת Apigee: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<MessageWeight>

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

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

לדוגמה, אם פרמטר 'מעצר ספייק' <Rate> הוא 10pm, ואפליקציה שולחת בקשות בעלות משקל של 2, ולאחר מכן מותרות רק חמש הודעות בדקה הלקוח הזה כי כל בקשה נחשבת ל-2.

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

תחביר

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <MessageWeight ref="flow_variable"/>
</SpikeArrest>

דוגמה 1

הדוגמה הבאה מגבילה את הבקשות ל-12 בקשות לדקה (בקשה אחת מותרת כל חמש בקשות שניות, או 60/12):

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
</SpikeArrest>

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

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

מאפיין תיאור נוכחות ברירת מחדל
ref מזהה את משתנה הזרימה שמכיל את משקל ההודעה של הלקוח הספציפי. זה יכול להיות כל משתנה זרימה, כפרמטר של שאילתת HTTP, כותרת או תוכן הודעה. מידע נוסף זמין במאמר הבא: חומר עזר על משתני זרימה. אפשר גם להגדיר משתנים מותאמים אישית באמצעות מדיניות JavaScript או מדיניות AssignMessage. חובה לא רלוונטי

<Rate>

מציין את הקצב שבו יש להגביל עליות חדות (או תפרצויות) בתנועה על ידי הגדרת מספר בקשות שמותרות במרווחים של דקה או לשנייה. אפשר להשתמש ברכיב הזה גם ביחד עם <Identifier> ו-<MessageWeight> כדי ויסות חלק של תעבורת הנתונים בזמן הריצה על ידי קבלת ערכים מהלקוח.

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

תחביר

אפשר לציין תעריפים באחת מהדרכים הבאות:

  • קצב סטטי שמציינים כגוף הרכיב <Rate>
  • ערך משתנה, שהלקוח יכול להעביר. לזהות את שם משתנה הזרימה באמצעות המאפיין ref
<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

ערכי שער חוקיים (מוגדרים כערך משתנה או בגוף הרכיב) להיות בפורמט הבא:

  • intps (מספר הבקשות לשנייה, חלוקה למרווחי זמן מאלפיות שנייה)
  • intpm (מספר הבקשות לדקה, חלוקה למרווחי זמן) מתוך שניות)

הערך של int חייב להיות מספר שלם חיובי שאינו אפס.

דוגמה 1

בדוגמה הבאה הקצב נקבע ל-5 בקשות לשנייה:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

המדיניות מקלה את הקצב של בקשה אחת שמותרת כל 200 אלפיות השנייה (1000/5).

דוגמה 2

בדוגמה הבאה הקצב נקבע ל-12 בקשות לדקה:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
</SpikeArrest>

המדיניות לדוגמה הזו מקלה את התעריף לבקשה אחת שמותרת בכל חמש שניות (60/12).

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

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

אפשר גם להשתמש במשתנים מותאמים אישית באמצעות מדיניות JavaScript או מדיניות AssignMessage.

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

לדוגמה:

<Rate ref="request.header.custom_rate">1pm</Rate>

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

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

אם מציינים ערך ל-ref אבל לא מגדירים את התעריף בגוף התג הרכיב <Rate> והלקוח לא מעביר ערך, אז המדיניות 'מעצר יחיד' יקפיץ הודעת שגיאה.

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

<UseEffectiveCount>

מחלק את הספירות של עצירת הביניים בין מעבדי הודעות (MPs) בעת שימוש בהתאמה לעומס (auto-scaling) קבוצות.

תחביר

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

דוגמה 1

הדוגמה הבאה מגדירה את <UseEffectiveCount> כ-TRUE:

<SpikeArrest name='Spike-Arrest-1'>
  <Rate>40ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

הרכיב <UseEffectiveCount> הוא אופציונלי. ערך ברירת המחדל הוא false כשהאלמנט מושמט מהמדיניות Spike Arrest.

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

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

מאפיין תיאור ברירת מחדל נוכחות
ref מזהה את המשתנה שמכיל את הערך של <UseEffectiveCount>. סוג הפריט יכול להיות כל משתנה זרימה, למשל פרמטר של שאילתת HTTP, כותרת או תוכן הודעה. לקבלת מידע נוסף למידע נוסף, ראו הסבר על משתני זרימה. אפשר גם להגדיר משתנים מותאמים אישית באמצעות מדיניות JavaScript או מדיניות AssignMessage. לא רלוונטי אופציונלי

ההשפעה של <UseEffectiveCount> תלויה בערך שלו:

  • true: מגבלת קצב העלייה החדה ב-MP היא <Rate> חלקי מספר החברים הנוכחי באותו רצף מודעות. הגבול המצטבר הוא הערך מתוך <Rate>. כשמוסיפים חברי קהילה באופן דינמי (או מסירים אותם), העלייה החדה האישית שלהם מגבלות הקצב של יצירת הבקשות יעלו (או יקטנו), אבל המגבלה המצטברת תישאר ללא שינוי.
  • false (זהו ערך ברירת המחדל אם לא צוין): מגבלת קצב העלייה החדה בכל MP היא פשוט את הערך של <Rate> שלו. המגבלה המצטברת היא סכום התעריפים של כל חברי ה-MP. כשמוסיפים (או מסירים חברי MP) המגבלות הנפרדות של קצב העלייה החדה יישארו ללא שינוי, אבל המגבלה המצטברת תגדל (או ).

בטבלה הבאה מוצגת ההשפעה של <UseEffectiveCount> על מגבלת הקצב של יצירת הבקשות האפקטיביות של לכל MP:

הערך של <UseEffectiveCount>
false false false true true true
# חברי מועדון 8 4 2 8 4 2
הערך של <Rate> 10 10 10 40 40 40
שיעור אפקטיבי ל-MP 10 10 10 5 10 20
מגבלה מצטברת 80 40 20 40* 40* 40*
* כמו <Rate>.

בדוגמה הזו, שימו לב שכאשר מספר ה-MP יורד מ-4 ל-2, ו- <UseEffectiveCount> הוא false, התעריף האפקטיבי ל-MP לא משתנה (בערך 10). אבל כשהערך של <UseEffectiveCount> הוא true, התעריף האפקטיבי ל-MP עולה מ-10 ל-20 כשמספר פיקסלים מ-4 ל-2.

משתני זרימה

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

משתנה סוג הרשאה תיאור
ratelimit.policy_name.failed ערך בוליאני הרשאת קריאה בלבד מציין אם המדיניות נכשלה או לא (true או false).

מידע נוסף זמין בחומר העזר בנושא משתני זרימה.

התייחסות לשגיאות

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

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

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

קוד תקלה סטטוס HTTP סיבה תיקון
policies.ratelimit.FailedToResolveSpikeArrestRate 500 השגיאה הזו מתקבלת אם ההפניה למשתנה שמכיל את הגדרת התעריף בתוך האלמנט <Rate> לא ניתן לקבוע ערך בתוך הרכיב Spike Arrest המדיניות בנושא הרכיב הזה הוא חובה ומשמש לציון שיעור השהיות השיא ב- בפורמט intpm או intps.
policies.ratelimit.InvalidMessageWeight 500 השגיאה הזו מתקבלת אם הערך שצוין לרכיב <MessageWeight> באמצעות משתנה זרימה אינו חוקי (ערך שאינו מספר שלם).
policies.ratelimit.SpikeArrestViolation 429

חריגה ממגבלת הקצב של יצירת הבקשות.

שגיאות פריסה

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

שם השגיאה סיבה תיקון
InvalidAllowedRate אם שיעור המעצרים של העלייה החדה צוין ברכיב <Rate> של 'מעצר העליונות' המדיניות היא לא מספר שלם, או אם הסיומת של שיעור ההמרה לא כוללת את ps או את pm, הפריסה של שרת ה-proxy ל-API נכשלת.

משתני כשל

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

משתנים איפה דוגמה
fault.name="fault_name" fault_name הוא שם התקלה, כפי שמצוין ב הטבלה שגיאות זמן ריצה למעלה. שם השגיאה הוא החלק האחרון של קוד התקלה. fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לבעיה. ratelimit.SA-SpikeArrestPolicy.failed = true

דוגמה לתגובת שגיאה

למטה מוצגת דוגמה לתגובת שגיאה:

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

דוגמה לכלל שגוי

למטה מוצגת דוגמה לכלל שגיאה לטיפול בתקלה מסוג SpikeArrestViolation:

<FaultRules>
    <FaultRule name="Spike Arrest Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "SpikeArrestViolation") </Condition>
        </Step>
        <Condition>ratelimit.Spike-Arrest-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

קוד מצב ה-HTTP הנוכחי לחריגה ממגבלת קצב שהוגדרה במדיניות Quota או המדיניות בנושא עצירת ביניים הוא 429 (יותר מדי בקשות). כדי לשנות את קוד מצב ה-HTTP ל-500 (שגיאת שרת פנימית), מגדירים את האפשרות נכס features.isHTTPStatusTooManyRequestEnabled אל false באמצעות ה עדכון ה-API של מאפייני הארגון.

לדוגמה:

curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.com/v1/organizations/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
        . . .
    </Properties>
</Organization>"

סכימות

כל סוג מדיניות מוגדר על ידי סכימת XML (.xsd). לידיעתך, סכימות של מדיניות זמינים ב-GitHub.

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