המדיניות של GrowFault

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

מה

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

למידע כללי על טיפול בתקלות, ניתן לעיין במאמר טיפול בפגמים.

טעימות

<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>

מידע על מדיניות RaiseFault

בעזרת Apigee Edge ניתן לבצע טיפול בחריג בהתאמה אישית באמצעות מדיניות מסוג RaiseFault. מדיניות RaiseFault, שדומה למדיניות assignMessage, מאפשרת לכם ליצור תגובת תקלה מותאמת אישית בתגובה לתנאי שגיאה.

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

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

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

הפניה לרכיב

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

<?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>

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

האלמנט <FaultResponse><הקצאהVariable>

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

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

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

לאחר מכן אפשר להתייחס למשתנה הזה בתבניות של הודעות בשלב מאוחר יותר במדיניות RaiseFault. בנוסף, מדיניות שמצורפת ל-FaultRule יכולה לגשת למשתנה. לדוגמה, במדיניות assignMessage הבאה משתמשים במשתנה שהוגדר ב-RaiseFault כדי להגדיר כותרת עליונה בתגובת השגיאה:

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

<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>

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

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

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

<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.

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

כדאי לעיין בטיפול בשגיאות