רכיב RaiseFault

אתם צופים במסמכי התיעוד של 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, פרמטרים של שאילתה ומטען ייעודי (payload) של הודעה. תגובה מותאמת אישית לשגיאה יכולה להיות שימושית יותר למפתחי אפליקציות ולמשתמשי קצה של אפליקציות מאשר הודעות שגיאה כלליות או קודי תגובת HTTP.

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

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

הפניה לרכיב

הפניה לרכיב מתארת את הרכיבים והמאפיינים של מדיניות 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">

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

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

אלמנט <IgnoreUnresolvedVariables>

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

אלמנט <FaultResponse>

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

רכיב <FaultResponse><AssignVariable>

מקצה ערך למשתנה זרימה של יעד. אם משתנה הזרימה לא קיים, הפונקציה 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> במדיניות AssignMessage. שימו לב שהפונקציונליות הזו לא זמינה כרגע ב-Apigee Edge for Private Cloud.

‫<FaultResponse><Add>/<Headers>

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

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

‫<FaultResponse><Copy> element

מעתין מידע מהההודעה שצוינה במאפיין 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> element

מסירה כותרות 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> element

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

    <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(ברירת מחדל).

משתני זרימה

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

דוגמה לשימוש ברכיב 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.

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

מידע נוסף על טיפול בשגיאות