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

הוספת כותרות 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">

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

הגדרת מטען ייעודי (payload) מעורב ב-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

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

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

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