אנטי-תבנית: שימוש במדיניות RaiseFault בתנאים לא מתאימים

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

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

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

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

תבנית אנטי

שימוש במדיניות RaiseFault בתוך FaultRules אחרי שמדיניות אחרת כבר הציגה שגיאה

בדוגמה הבאה, מדיניות OAuthV2 בתהליך של API Proxy נכשלה עם שגיאה InvalidAccessToken. אם הפעולה נכשלת, Apigee מגדיר את fault.name כ-InvalidAccessToken, עובר לזרימת השגיאות ומבצע את כללי השגיאות שהוגדרו. ב-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, המשתנים x_apigee_fault_code ו-x_apigee_fault_policy נדרסים. ב-API Monitoring, הערכים של Fault Code ושל Fault Policy נמחקים. ההתנהגות הזו מקשה על פתרון בעיות ועל קביעת המדיניות שבאמת גורמת לכשל.

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

שיטה מומלצת

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

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

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

קריאה נוספת

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