רכיב RaiseFault

מדיניות רגילה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

המדיניות הזו היא מדיניות רגילה ואפשר לפרוס אותה בכל סוג של סביבה. מידע על סוגי המדיניות והזמינות שלהם בכל סוג סביבה זמין במאמר סוגי מדיניות.

בהתאם לתרחיש השימוש, יכול להיות שתרצו להשתמש במדיניות RaiseFault או במדיניות AssignMessage.

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

דוגמאות

החזרת FaultResponse

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

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

החזרת מטען ייעודי (payload) של FaultResponse

דוגמה מורכבת יותר כוללת החזרה של מטען ייעודי (payload) של תגובת שגיאה מותאמת אישית, יחד עם כותרות HTTP וקוד סטטוס של HTTP. בדוגמה הבאה, תגובת השגיאה מאוכלסת בהודעת XML שמכילה את קוד הסטטוס של HTTP שהתקבל על ידי Apigee משירות ה-Backend, וכותרת שמכילה את סוג השגיאה שהתרחשה:

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact [e-mail]</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

רשימה של כל המשתנים שזמינים לאכלוס דינמי של הודעות FaultResponse מופיעה במאמר בנושא משתנים.

טיפול בשגיאות של בקשות להצעות מחיר לשירותים

דוגמה: לומדים תוך כדי עשייה!
בדוגמה הזו של Learn Apigee מוצג איך לבדוק את קוד ה-HTTP בתגובה של ServiceCallout ולזרוק חריגה מותאמת אישית על סמך ערך הקוד. בדוגמה מוחזרת הודעת שגיאה מותאמת אישית כשהשירות הממוקד מחזיר סטטוס 404. פשוט משכפלים את המאגר ופועלים לפי ההוראות בנושא הזה. בדוגמה מוצג דפוס נפוץ לטיפול בשגיאות של קריאות לשירות. .

---

הפניה לרכיב

הפניה לרכיב מתארת את הרכיבים והמאפיינים של מדיניות 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/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

מאפיינים של <RaiseFault>

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

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

מאפיין	תיאור	ברירת מחדל	נוכחות
name	השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים. אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.	לא רלוונטי	חובה
continueOnError	מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי	FALSE	אופציונלי
enabled	מגדירים את המדיניות למצב true כדי לאכוף אותה. מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
async	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

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

אלמנט <IgnoreUnresolvedVariables>

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

אלמנט <FaultResponse>

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

רכיב <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>
</AssignMessage>

‫<AssignVariable> במדיניות RaiseFault משתמש באותו תחביר כמו הרכיב <AssignVariable> במדיניות AssignMessage.

‫<FaultResponse><Add>/<Headers> element

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

האלמנט <Header> תומך בתכונה של החלפת מחרוזות דינמיות שנקראת תבניות הודעות.

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

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

‫<FaultResponse><Copy> element

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

מאפיינים

 <Copy source="response">

מאפיין	תיאור	נוכחות	סוג
מקור	מציין את אובייקט המקור של ההעתקה. אם לא מציינים מקור, ההודעה נחשבת להודעה פשוטה. לדוגמה, אם המדיניות נמצאת בתהליך הבקשה, המקור יהיה כברירת מחדל אובייקט הבקשה. אם המדיניות נמצאת בתהליך התגובה, ברירת המחדל היא אובייקט התגובה. אם לא מציינים את המקור, אפשר להשתמש בהפניה מוחלטת למשתנה של זרימת נתונים כמקור של העותק. לדוגמה, מציינים את הערך כ-{request.header.user-agent}. אם לא ניתן לפתור את משתנה המקור, או שהוא נפתר לסוג שאינו הודעה, הפעולה <Copy> לא תגיב.	אופציונלי	String

‫<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 יש רק ערך אחד, הוא לא מועתק.

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

אלמנט <FaultResponse><Copy>/<StatusCode>

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

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

ברירת מחדל:	FALSE
נוכחות:	אופציונלי
סוג:	String

‫<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, הוא לא יוסר.

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

‫<FaultResponse><Set> element

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

רכיבי המשנה של <Set> תומכים בתכונה של החלפת מחרוזות דינמיות שנקראת תבניות הודעות.

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

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	לא רלוונטי

אלמנט <FaultResponse>/<Set>/<Headers>

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

אלמנט <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>

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

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

ברירת מחדל:
נוכחות:	אופציונלי
סוג:	String

מאפיינים

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

מאפיין	תיאור	נוכחות	סוג
contentType	אם מציינים את contentType, הערך שלו מוקצה לכותרת Content-Type.	אופציונלי	String
variablePrefix	אופציונלי: מציין את התו המפריד הראשון במשתנה של זרימת נתונים, כי במטענים ייעודיים (payloads) בפורמט JSON אי אפשר להשתמש בתו ברירת המחדל '{'.	אופציונלי	Char
variableSuffix	אופציונלי: מציין את התו האחרון שמפריד בין משתנים בזרימה, כי אי אפשר להשתמש בתו ברירת המחדל '}' במטענים ייעודיים (payloads) של JSON.	אופציונלי	Char

אלמנט <FaultResponse>/<Set>/<StatusCode>

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

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

ברירת מחדל:	FALSE
נוכחות:	אופציונלי
סוג:	בוליאני

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

ברירת מחדל:	FALSE
נוכחות:	אופציונלי
סוג:	בוליאני

משתנים בתהליך

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

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

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

<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>
    </Set>
  </FaultResponse>
</RaiseFault>

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס HTTP	מטרה
steps.raisefault.RaiseFault	500	לצפייה במחרוזת השגיאה.

שגיאות בהטמעה

אין.

משתני תקלות

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

משתנים	כאשר:	דוגמה
fault.name="fault_name"	‫fault_name הוא שם התקלה, כפי שמופיע בטבלה שגיאות בזמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	fault.name = "RaiseFault"
raisefault.policy_name.failed	‫policy_name הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה.	raisefault.RF-ThrowError.failed = true

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

הערה: כדי לטפל בשגיאות, מומלץ ללכוד את החלק errorcode של תגובת השגיאה. אל תסתמכו על הטקסט ב-faultstring, כי הוא עשוי להשתנות.

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

סכימה

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

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

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