מדיניות של SpikeArst

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

הסמל של Spike Arrest בממשק המשתמש של Edge

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

רכיב <SpikeArrest>

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

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

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

בדוגמה הבאה מוצגות הגדרות ברירת המחדל כשמוסיפים מדיניות Spike Arrest לזרימה בממשק המשתמש של 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 אלפיות שנייה (1,000/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 של המדיניות
סוג מחרוזת
רכיב הורה <PolicyElement>
רכיבי צאצא אין

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

תחביר

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

דוגמה

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

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

<Identifier>

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

אפשר להשתמש בו בשילוב עם הרכיב <MessageWeight> לשליטה פרטנית יותר בהגבלת בקשות.

אם משאירים את הרכיב <Identifier> ריק, המערכת תיאכף מגבלת קצב אחת לכל הבקשות לשרת ה-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 או באמצעות המדיניות AssignedMessage. לא רלוונטי חובה

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

<MessageWeight>

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

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

לדוגמה: אם הערך של Spike Arrest <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 אלפיות שנייה (1,000/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> והלקוח לא מעביר ערך, תופיע הודעת שגיאה על ידי המדיניות Spike Arrest.

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

<UseEffectiveCount>

חלוקת הספירות של Spike Arrest בין מעבדי ההודעות (MP) כשמשתמשים בקבוצות עם התאמה לעומס (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> חלקי המספר הנוכחי של חברי MP באותו רצף. המגבלה המצטברת היא הערך של <Rate>. כאשר חברי MP נוספים (או מסירים באופן דינמי), המגבלות הנפרדות של קצב השיא שלהם יגדלו (או יצטמצמו), אבל המגבלה המצטברת תישאר ללא שינוי.
  • 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 כאשר מספר חברי ה-MP ירד מ-4 ל-2.

משתני זרימה

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

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

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