עיצוב נגדי: שימוש במדיניות RaiseFault בתנאים לא הולמים

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

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

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

<!-- /antipatterns/examples/raise-fault-conditions-1.xml  -->
<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>RF-Service-Unavailable</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
   </Step>
  </Response>
...

שם המדיניות RaiseFault מופיע בתור fault.name ב- API Monitoring ובתור x_apigee_fault_policy ביומני הגישה של Analytics ושל הנתב. כך ניתן לאבחן בקלות את הגורם לשגיאה.

דוגמת עיצוב

שימוש במדיניות RaiseFault במסגרת Fault Rules, אחרי שמדיניות אחרת כבר הובילה הודעת שגיאה

כדאי לעיין בדוגמה שבהמשך, שבה מדיניות OAuthV2 בתהליך ה-API של שרת ה-proxy נכשלה והתקבלה שגיאת InvalidAccessToken. במקרה של כשל, Edge יגדיר את fault.name בתור InvalidAccessToken, ייכנס לתהליך השגיאות ויפעיל את כללי Fault Rules שנקבעו. ב-FaultRule יש מדיניות RaiseFault בשם RaiseFault, ששולחת תגובה מותאמת אישית לשגיאה בכל פעם שמתרחשת שגיאה InvalidAccessToken. עם זאת, כשמשתמשים במדיניות RaiseFault ב-FaultRule, המשתנה fault.name מחליף ומיסוך את הסיבה האמיתית לכשל.

<!-- /antipatterns/examples/raise-fault-conditions-2.xml  -->
<FaultRules>
  <FaultRule name="generic_raisefault">
    <Step>
        <Name>RaiseFault</Name>
        <Condition>(fault.name equals "invalid_access_token") or (fault.name equals "InvalidAccessToken")</Condition>
    </Step>
  </FaultRule>
</FaultRules>

שימוש במדיניות RaiseFault ב-FaultRule בכל התנאים

בדוגמה הבאה, מדיניות RaiseFault בשם RaiseFault מופעלת אם הערך של fault.name הוא לא RaiseFault:

<!-- /antipatterns/examples/raise-fault-conditions-3.xml  -->
<FaultRules>
    <FaultRule name="fault_rule">
        ....
        <Step>
            <Name>RaiseFault</Name>
            <Condition>!(fault.name equals "RaiseFault")</Condition>
        </Step>
    </FaultRule>
</FaultRules>

כמו בתרחיש הראשון, משתני התקלה המרכזיים fault.name, fault.code ו-fault.policy מוחלפים בשם של מדיניות RaiseFault. בהתאם להתנהגות הזו, כמעט בלתי אפשרי לקבוע איזו מדיניות גרמה בפועל לכשל, בלי לגשת לקובץ מעקב שמציג את הכשל או משחזר את הבעיה.

שימוש במדיניות RaiseFault כדי להחזיר תגובת HTTP 2xx מחוץ לתהליך השגיאה.

בדוגמה הבאה, מדיניות RaiseFault בשם HandleOptionsRequest מופעלת כשהפועל של הבקשה הוא OPTIONS:

<!-- /antipatterns/examples/raise-fault-conditions-4.xml  -->
<PreFlow name="PreFlow">
    <Request>
        …
        <Step>
            <Name>HandleOptionsRequest</Name>
            <Condition>(request.verb Equals "OPTIONS")</Condition>
        </Step>
        …
</PreFlow>

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

השפעה

השימוש במדיניות RaiseFault כמו שמתואר למעלה, יגרום להחלפה של משתני השגיאה המרכזיים לשם המדיניות של RaiseFault במקום לשם של המדיניות שהכשל בה. ביומני Analytics ו-NGINX Access, המשתנים x_apigee_fault_code ו-x_apigee_fault_policy מוחלפים. ב-API Monitoring, השדות Fault Code ו-Fault Policy מוחלפים. אופן הפעולה הזה מקשה על פתרון הבעיות ולקבוע איזו מדיניות היא הגורם האמיתי לכשל.

בצילום המסך שמופיע בהמשך מ-API Monitoring, אפשר לראות שהמדיניות 'קוד תקלה' ומדיניות תקלה והוחלפו בערכי RaiseFault כלליים, ולכן לא ניתן לקבוע מהו שורש הבעיה לפי היומנים:

שיטה מומלצת

אם מדיניות Edge יוצרת תקלה ואתם רוצים להתאים אישית את הודעת השגיאה בתגובה, השתמשו במדיניות assignMessage או JavaScript במקום במדיניות RaiseFault.

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

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

קריאה נוספת

• טיפול בפגמים
• מדיניות RaiseFault
• דיון בקהילה לגבי דפוסים לטיפול בכשלים