המדיניות של GrowFault

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

מה

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

מידע כללי על טיפול בתקלות זמין במאמר טיפול בתקלות.

דוגמאות

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

מידע על המדיניות IncreaseFault

באמצעות Apigee Edge אפשר לבצע טיפול בחריגים בהתאמה אישית באמצעות מדיניות מסוג IncreaseFault. מדיניות IncreaseFault, שדומה AssignMessage policy מאפשרת ליצור תגובה מותאמת אישית לתקלה בתגובה לתנאי שגיאה.

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

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

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

הפניה לרכיב

בהפניה לרכיב מתוארים הרכיבים והמאפיינים של מדיניות UploadFault.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

<RaiseFault> מאפיינים

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

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

<DisplayName> רכיב

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

<DisplayName>Policy Display Name</DisplayName>

<IgnoreUnresolvedVariables> רכיב

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

<FaultResponse> רכיב

(אופציונלי) מגדיר את הודעת התגובה שמוחזרת ללקוח ששלח את הבקשה. שימושים ב-FultResponse אותן הגדרות כמו מדיניותAssignMessage (לא זמינה ב-Apigee Edge לענן פרטי).

<FaultResponse><AssignVariable> רכיב

מקצה ערך למשתנה מסוג 'נתיב יעד'. אם משתנה הזרימה לא קיים, AssignVariable יוצר אותו.

לדוגמה, אפשר להשתמש בקוד הבא כדי להגדיר את המשתנה בשם myFaultVar במדיניות IncreaseFault:

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

לאחר מכן תוכלו להפנות למשתנה הזה בתבניות של הודעות מאוחר יותר במדיניות IncreaseFault. כמו כן, מדיניות שמצורפת ל-FultRule יכולה לגשת למשתנה. לדוגמה, המדיניות AssignMessage משתמשת במשתנה שהוגדר ב-IncreaseFault כדי להגדיר כותרת תגובה שגויה:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

התחביר של <AssignVariable> במדיניות IncreaseFault זהה לזה של הרכיב <AssignVariable> במדיניות AssignMessage שימו לב שהפונקציונליות הזו לא זמינה כרגע ב-Apigee Edge לענן פרטי.

<FaultResponse><Add>/<Headers> רכיב

הוספת כותרות HTTP להודעת השגיאה. שימו לב שהכותרת הריקה <Add><Headers/></Add> לא מוסיפה אף כותרת. הזה מעתיק את הערך של משתנה הזרימה request.user.agent לתוך הכותרת.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

<FaultResponse><Copy> רכיב

העתקת מידע מתוך ההודעה שצוינה המאפיין source בהודעת השגיאה.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
        <ReasonPhrase/>
    </Copy>

מאפיינים

 <Copy source="response">

<FaultResponse><Copy>/<Headers> רכיב

העתקה של כותרת ה-HTTP שצוינה מהמקור להודעת השגיאה. כדי להעתיק את כל הכותרות, ציון <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>      
        <Header name="headerName"/>
    </Headers> 
</Copy>

אם יש כמה כותרות עם אותו שם, צריך להשתמש בתחביר הבא:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

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

<FaultResponse><Copy>/<StatusCode> רכיב

קוד מצב ה-HTTP להעתקה מהאובייקט שצוין על ידי מאפיין המקור לשגיאה הודעה.

<Copy source='response'>
    <StatusCode>404</StatusCode>      
</Copy>

<FaultResponse><Copy>/<ReasonPhrase> רכיב

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

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

<FaultResponse><Remove>/<Headers> רכיב

מסיר את כותרות ה-HTTP שצוינו מהודעת השגיאה. כדי להסיר את כל הכותרות, צריך לציין <Remove><Headers/></Remove> הדוגמה הזו מסירה הכותרת user-agent בהודעה.

<Remove>     
    <Headers>      
        <Header name="user-agent"/>     
    </Headers> 
</Remove>

אם יש כמה כותרות עם אותו שם, צריך להשתמש בתחביר הבא:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

בדוגמה הזו מסירים את 'h1', 'h2' ואת הערך השני של 'h3'. אם 'h3' יש רק אחד ערך מסוים, הוא לא יוסר.

<FaultResponse><Set> רכיב

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

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
        <ReasonPhrase/>
    </Set>

<FaultResponse>/<Set>/<Headers> רכיב

מגדיר או מחליף כותרות HTTP בהודעת השגיאה. שימו לב שהכותרת הריקה <Set><Headers/></Set> לא מגדירה אף כותרת. הדוגמאות האלה מגדירות הכותרת user-agent למשתנה ההודעה שצוין עם רכיב <AssignTo>.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>     
    </Headers>
</Set>

<FaultResponse>/<Set>/<Payload> רכיב

מגדיר את המטען הייעודי (Payload) של הודעת השגיאה.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

מגדירים מטען ייעודי (payload) של JSON:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

במטען ייעודי (payload) של JSON, אפשר להוסיף משתנים באמצעות variablePrefix וגם מאפייני variableSuffix עם תווים מפרידים כמו שמתואר בהמשך לדוגמה.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

או, החל מגרסה 16.08.17 של ענן, אפשר גם להוסיף סוגריים מסולסלים כדי להוסיף משתנים:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

הגדרת מטען ייעודי (payload) מעורב ב-XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

מאפיינים

 
<Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

<FaultResponse>/<Set>/<StatusCode> רכיב

הגדרת קוד הסטטוס של התגובה.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

<FaultResponse>/<Set>/<ReasonPhrase> רכיב

הגדרת הביטוי של הסיבה לתשובה.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

<ShortFaultReason> רכיב

מציינת שיש בתשובה סיבה קצרה לתקלה:

<ShortFaultReason>true|false</ShortFaultReason>

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

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

כדי להפוך את ההודעה לקריאה יותר, אפשר להגדיר את הרכיב <ShortFaultReason> ל-TRUE כדי לקצר את faultstring רק לשם המדיניות:

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

ערכים חוקיים: true/false(ברירת מחדל).

משתני זרימה

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

שימוש לדוגמה ב-IncreaseFault

הדוגמה הבאה משתמשת בתנאי כדי לאכוף את הנוכחות של queryparam בשם zipcode בבקשה הנכנסת. אם המיקום אם queryparam לא קיים, הזרימה תתרחש תקלה באמצעות IncreaseFault:

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>

<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

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

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

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

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

שגיאות פריסה

ללא.

משתני כשל

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

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

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

סכימה

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

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

למידע נוסף על טיפול בתקלות