כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
המדיניות מסוג 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 |
לא רלוונטי | נדרש |
השם הפנימי של המדיניות. הערך של המאפיין אפשר להשתמש ברכיב |
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. אם מגדירים גם לדוגמה: <Rate ref="request.header.custom_rate">1pm</Rate> בדוגמה הזו, אם הלקוח לא מעביר את הכותרת 'custom_rate', התעריף של שרת ה-proxy ל-API הוא בקשה אחת לדקה לכל הלקוחות. אם הלקוח מעביר את הכותרת "custom_rate", מגבלת הקצב ליצירת בקשות הופכת ל-10 בקשות לשנייה לכל הלקוחות בשרת ה-proxy — עד שנשלחת בקשה בלי הכותרת "custom_rate". אפשר להשתמש ב- אם מציינים ערך ל- |
אופציונלי | לא רלוונטי |
<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 . |
build |
policies.ratelimit.InvalidMessageWeight |
500 |
השגיאה הזו מתרחשת אם הערך שצוין לרכיב <MessageWeight> באמצעות משתנה זרימה לא חוקי (ערך שאינו מספר שלם). |
build |
policies.ratelimit.SpikeArrestViolation |
429 |
חרגת ממגבלת הקצב של יצירת הבקשות. |
שגיאות בפריסה
השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.
שם השגיאה | סיבה | תיקון |
---|---|---|
InvalidAllowedRate |
אם שיעור מעצר השיא שצוין באלמנט <Rate> במדיניות Spike Arrest
אינו מספר שלם, או אם הקצב לא כולל את הסיומת ps או pm , הפריסה של שרת ה-proxy של ה-API תיכשל. |
build |
משתני שבר
המשתנים האלה מוגדרים כשמתרחשת שגיאה בזמן הריצה. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.
משתנים | מיקום | דוגמה |
---|---|---|
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.
נושאים קשורים
- מדיניות מכסות: מדיניות בנושא מכסות להגבלת התנועה של לקוחות ספציפיים
- הגבלת קצב של יצירת בקשות לקבלת סקירה כללית על הגבלת הקצב של יצירת הבקשות
- השוואה בין המדיניות בנושא מכסות לבין המדיניות של SpikeArrest
- דוגמאות עבודה של שרתי proxy ל-API