טיפול בכשלים

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

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

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

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

סרטונים

מומלץ לצפות בסרטונים הבאים כדי לקבל מידע נוסף על טיפול בתקלות.

איך מתרחשות השגיאות

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

שגיאות אוטומטיות

שרת proxy ל-API משמיע שגיאה באופן אוטומטי במצבים הבאים:

• מדיניות מקפיצה הודעת שגיאה. לדוגמה, אם קריאה ל-API שולחת מפתח שפג תוקפו, מדיניות VerifyAPIKey מקפיצה שגיאה באופן אוטומטי. או אם מספר הקריאות ל-API חורגים מהמגבלה מסוימת, המדיניות בנושא מכסה או מדיניות SpikeArrest גורמת לשגיאה. (אפשר לעיין בחומר העזר בנושא שגיאות שקשורות למדיניות כדי לקבל סוגים שונים של שגיאות שמדיניות זו עשויה לגרום).
• יש בעיה בתהליך ההודעה ב-Proxy ל-API, כמו שגיאה בניתוב.
• יש כשל בקצה העורפי, כמו שגיאת HTTP בגלל כשלים ברמת הפרוטוקול או עם TLS/SSL (אבטחת שכבת התעבורה) או שירות יעד לא זמין.
• יש כשל ברמת המערכת, למשל חריג בזיכרון.

מידע נוסף על השגיאות האלה זמין בטקסונומיית התקלות בנושא הזה.

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

במצבים שבהם אין שגיאה אוטומטית, ייתכן שתרצו להקפיץ הודעת שגיאה מותאמת אישית. עבור לדוגמה, אם תשובה מכילה את המילה "unavailable" (לא זמין), או אם קוד הסטטוס של HTTP גדול יותר מ-201. כדי לעשות זאת, מוסיפים מדיניות UploadFault את המקום המתאים בתהליך ה-proxy של API.

אפשר להוסיף מדיניות IncreaseFault לתהליך של שרת proxy ל-API באותו אופן שבו עושים זאת בכל מדיניות אחרת. לחשבון הדוגמה הבאה להגדרה של שרת proxy, המדיניות Raise-Fault-1 מצורפת אל התגובה של TargetEndpoint. אם המילה 'לא זמין' נמצא בתגובה מהיעד השירות, מדיניות IncreaseFault מופעלת וגורמת לשגיאה.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

רצינו רק להראות לך שיש לך אפשרות לזרוק שגיאות מותאמות אישית. נפרט יותר לעומק מדיניות IncreaseFault בנושא FaultRules לעומת HearFault .

תוכלו למצוא דוגמאות נוספות בפוסטים הבאים בפורומים של הקהילה של Apigee:

• הפניה למשתני JavaScript ב-IncreaseFault

מה עושים שרתי proxy ל-API כשמתרחשות שגיאות

זה מה שקורה כששרת proxy מציג שגיאה.

יוצאים מצינור עיבוד הנתונים של שרת ה-proxy

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

לדוגמה, נניח שלשרת proxy ל-API יש כללי מדיניות בסדר הבא ב-ProxyEndpoint בקשה:

1. אימות מפתח ה-API
2. מכסה
3. JSON ל-XML

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

חיפוש כללי FaultRule

במצב שגיאה, שרתי proxy ל-API בודקים גם את הנוכחות של הפריטים הבאים (לפי הסדר) ב- הגדרה של שרת proxy ל-API לפני החזרת הודעת שגיאה שמוגדרת כברירת מחדל לאפליקציית הלקוח:

1. קטע <FaultRules>, שמכיל את הלוגיקה של תפעיל הודעות שגיאה בהתאמה אישית (וכללי מדיניות אחרים) על סמך תנאים ספציפיים להגדיר.
2. קטע <DefaultFaultRule>, שמפעיל ברירת מחדל הודעת שגיאה במצבים הבאים:
   • לא הוגדרו <FaultRules>.
   • לא בוצע הרצה של <FaultRules> קיים.
   • הגדרת הרכיב <AlwaysEnforce> היא True.

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

דוגמה פשוטה לטיפול בתקלות

נתחיל בדוגמה פשוטה, שבה קריאה לשרת proxy של API לא מכילה ממשק API נדרש מקש. כברירת מחדל, זו התגובה שמוחזרת לאפליקציית הלקוח:

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

יכול להיות שמשתמשי ה-API יוכלו לפענח את הודעת השגיאה, אבל יכול להיות שלא. וברירות מחדל רבות הן עדינות יותר וקשה יותר לפענח אותן.

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

הנה דוגמה בסיסית לאופן שבו אפשר ליצור הודעת שגיאה מותאמת אישית כדי לטפל בשגיאה הזו. הזה נדרשת 1) מדיניות שמגדירה את ההודעה המותאמת אישית, וגם 2) כלל FaultRule שמפעיל את המדיניות כששרת ה-proxy עובר למצב שגיאה.

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

קודם כול, יוצרים מדיניות שמגדירה את הודעת השגיאה המותאמת אישית. אפשר להשתמש בכל סוג של מדיניות, כמו AssignMessage (מדיניות הקצאה), שיכולה להגדיר מטען ייעודי (payload) וכותרות HTTP אופציונליות כגון קוד סטטוס וביטוי הסיבות. האפשרות 'הקצאת הודעה' מתאימה במיוחד למטרה הזו. היא מאפשרת לשלוט במטען הייעודי (payload) של ההודעות, להגדיר קוד מצב HTTP שונה, להגדיר ביטוי שונה של סיבת HTTP ולהוסיף כותרות HTTP.

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

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

לפניכם דוגמה למדיניות AssignMessage:

• מחזירה הודעת JSON.
• מגדיר קוד מצב HTTP (911, שהוא קוד סטטוס ברור שלא קיים) תמחיש את הגמישות שיש לכם). קוד הסטטוס מופיע בכותרת ה-HTTP.
• מגדיר את ביטוי הסיבה ל-HTTP (כדי להחליף את ביטוי הסיבה שמוגדר כברירת מחדל בתור 'לא מורשה') שגיאה של מפתח API חסר). ביטוי הסיבה מופיע לצד קוד הסטטוס ב-HTTP הכותרת.
• יוצר ומאכלס כותרת HTTP חדשה בשם invalidKey.

<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

כן, זה קצת מטופש, אבל זה מראה מה אפשרי. לפחות עכשיו למפתחים מקבל את ההודעה יודע שהוא שכח לכלול מפתח API כפרמטר של שאילתה.

אבל איך המדיניות הזו באה לידי ביטוי? בקטע הבא תראו.

2. יוצרים את <FaultRule> שתפעיל את המדיניות

בקטעים <ProxyEndpoint> או <TargetEndpoint> של בהגדרה של שרת ה-proxy יש להוסיף בלוק XML <FaultRules> שמכיל או יותר אוספים אישיים של <FaultRule>. כל FaultRule מייצג שבה רוצים לטפל. בדוגמה הפשוטה הזו נשתמש רק ב-FultRule אחד כדי להראות לכם שהוא מורכב מהם.

צריך להוסיף גם <DefaultFaultRule> כדי לספק שגיאה כללית בהתאמה אישית אם אף אחד מכללי FaultRules לא הופעל.

דוגמה

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

נקודות עיקריות:

• ה-FultRules מוגדרים ב-ProxyEndpoint. זה חשוב. מידע נוסף על תלישה FaultRules ב-ProxyEndpoint לעומת TargetEndpoint מאוחר יותר.
• <Name> – שם המדיניות להפעלה. השם מגיע מהמאפיין name של המדיניות ברכיב ההורה, כפי שמוצג את הדוגמה הקודמת.

• <Condition> – דפדפן Edge בודק את התנאי ו מפעיל את המדיניות רק אם התנאי מתקיים. אם יש כמה כללי שגיאה אם הערך יהיה True, Edge יריץ את הבדיקה הראשונה שרלוונטית. (חשוב: הסדר שבו מתבצעת הערכה של כללי השגיאה, מלמעלה למטה או מלמטה למעלה, שונה נקודת הקצה targetEndpoint ו-ProxyEndpoint, כמתואר בקטע הקטע FaultRules and performance Logic.) אם לא כוללים תנאי, FaultRule מוגדר באופן אוטומטי. אבל זו לא שיטה מומלצת. לכל FaultRule צריך להיות משלו תנאי.

• <DefaultFaultRule> – אם אין כלל כשל בהתאמה אישית הוא מתבצעת, הפקודה <DefaultFaultRule> מתבצעת, והתוצאה שמתקבלת היא הודעה מותאמת אישית במקום ההודעה המוצפנת שנוצרה כברירת מחדל שנוצרה על ידי Edge. א' גם ל-<DefaultFaultRule> יכול להיות <Condition>, אבל בתוך ברוב המקרים לא תכללו מודל אחד, כי אתם רוצים שהוא יופעל, לא משנה מה היה אתר נופש גדול.

  ערך DefaultFaultRule משמש בדרך כלל להחזרת הודעת שגיאה כללית שגיאה לא צפויה. לדוגמה: הודעה שמכילה פרטים ליצירת קשר עם תמיכה טכנית. תשובת ברירת המחדל הזו משרתת את שתי המטרה: מידע ידידותי למפתחים תוך ערפול קוד (obfuscation) של כתובות URL של קצה עורפי או מידע אחר עלול לשמש לפגיעה במערכת.

כללי כשל ולוגיקת ביצוע מרובים

בקטע דוגמה לטיפול פשוט בתקלות השתמשנו בדוגמה פשוטה של FaultRule ותנאי אחד. בפרויקט API בעולם האמיתי, עם כל השגיאות האפשריות שיכול לקרות, סביר להניח שיש כמה FaultRules ו-DefaultFaultRule <ProxyEndpoint> וגם <TargetEndpoint> אבל בסופו של דבר, רק FaultRule אחד מופעל כששרת proxy ל-API עובר למצב שגיאה.

בקטע הזה מתואר הלוגיקה שבה משתמש Edge בטיפול ב-FultRules, מהאופן שבו הוא מגיע יחיד FaultRule כדי לבצע איך "inner" מתבצע טיפול בתנאים של שלבים כשה-FultRule שלהם הוא מופעל. בקטע הזה גם מוסבר מתי להגדיר כללי כשל <ProxyEndpoint> לעומת <TargetEndpoint>, ומתואר הקשר בין FaultRules לבין מדיניות UploadFault.

ביצוע של כללי FaultRule

בקיצור, זו הלוגיקה שבה משתמש Edge משתמש כששרת proxy ל-API עובר למצב שגיאה. שימו לב יש הבדל קטן בין הערכת FaultRules בנקודת הקצה ProxyEndpoint נקודת קצה ביעד.

1. Edge מעריך את כללי השגיאה ב-ProxyEndpoint או ב-TargetEndpoint, בהתאם שבו אירעה השגיאה:
   • ProxyEndpoint – דפדפן Edge מתחיל בחלק התחתית <FaultRule> ב-XML של התצורה ועוברת הלאה, <Condition> של כל <FaultRule> (ה"חלק החיצוני" ולא את "הפנימי" <Step> תנאים).
   • TargetEndpoint – דפדפן Edge מתחיל בלמעלה <FaultRule> ב-XML של התצורה ופועלת למטה, תוך הערכה <Condition> של כל <FaultRule> (ה"חלק החיצוני" ולא את "הפנימי" <Step> תנאים).
2. מפעיל את כלל השגיאה הראשון שהתנאי שלו מתקיים. אם ל-FultRule יש הפרמטר no condition (לא הוגדר) הוא True כברירת מחדל.
   • כשמריצים FaultRule, כל השלבים בתוך FaultRule מוערכים לפי הסדר. מלמעלה למטה בתצורת ה-XML. שלבים ללא תנאים מבוצעים אוטומטית (כללי המדיניות מופעלים), ושלבים שיש להם <Condition> הערך יהיה 'TRUE' מתבצעות (תנאים שהערך שלהם הוא 'false' לא ).

   • אם בוצע פעולת FaultRule, אבל לא בוצעו שלבים ב-FaultRule (בגלל שהפעולות שלהם התנאי מקבל את הערך 'false'), הודעת השגיאה שנוצרה כברירת מחדל שנוצרה על ידי Edge מוחזרת אל את אפליקציית הלקוח. הפקודה <DefaultFaultRule> לא מתבצעת, כי Edge כבר ביצע את FaultRule אחד.

3. אם לא בוצעה FaultRule, דפדפן Edge יריץ את <DefaultFaultRule>, אם כיום.

בהמשך מוצגות דוגמאות עם תגובות בגוף ההודעה.

הפעלת ProxyEndpoint

ההערכה של ProxyEndpoint FaultRules נמצאת מלמטה עד למעלה, אז צריך להתחיל לקרוא בסוף בדוגמה הבאה, FaultRule ומתקדמים הלאה. בדקו את DefaultFaultRule לאחרונה.

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

ביצוע של נקודת קצה (TargetEndpoint)

ההערכה של targetEndpoint FaultRules נמצאת מהתחתית, אז כדאי להתחיל לקרוא קודם FaultRule בדוגמה הבאה, ומנסה לרדת לרמה הבאה. בדקו את DefaultFaultRule לאחרונה.

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

הסדר של כללי השגיאה

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

לדוגמה:

כללי המדיניות שייכללו

אפשר ליישם כל מדיניות מ-FultRule על ידי הכנסתה לשלבים. לדוגמה, אפשר: מפעילים מדיניות AssignMessage כדי לעצב תשובה לאפליקציית הלקוח, ולאחר מכן רושמים הודעה ביומן למדיניות MessageLogging. כללי המדיניות מופעלים לפי הסדר שבו הם נקבעו (מלמעלה למטה ב-XML).

כללי השגיאה מופעלים רק במצב שגיאה (מידע על continueOnError)

יכול להיות שהכותרת תיראה כאילו אנחנו חוזרים על עצמנו, אבל יש ניואנס אחד ספציפי לשים לב לשגיאה בחיבור לשרת שגורמת לשרת proxy של API להיכנס למצב שגיאה, או לא להזין מצב שגיאה: המאפיין continueOnError המדיניות בנושא

לסיכום: שרת proxy ל-API מעריך את <FaultRules> ואת <DefaultFaultRule> רק אם שרת ה-proxy נכנס למצב שגיאה. ש כלומר, גם אם תנאי של FaultRule מקבל את הערך True, הוא לא יופעל אם שרת ה-proxy לא במצב שגיאה.

אבל הנה דוגמה לשגיאה שמתרחשת ושרת ה-Proxy לא נכנס למצב שגיאה. במצב מופעל כל מדיניות, אפשר להגדיר מאפיין ברכיב ההורה שנקרא continueOnError. המאפיין הזה חשוב מאוד לטיפול בתקלות, כי הוא קובע אם לא שרת ה-proxy נכנס למצב שגיאה אם המדיניות נכשלת. ברוב המקרים כדאי להשאיר את ברירת המחדל של continueOnError="false", שמעביר את שרת ה-Proxy למצב שגיאה אם המדיניות תיכשל, והמערכת תפעיל את הטיפול בשגיאות בהתאמה אישית. אבל אם continueOnError="true" (לדוגמה, אם לא רוצים שהשירות נכשל הסבר להפסקת ההפעלה של שרת ה-proxy, שרת ה-proxy לא יעבור למצב שגיאה אם המדיניות נכשלת, ושרת ה-proxy לא יבדוק את כללי FaultRule.

מידע על שגיאות רישום ביומן כאשר continueOnError="true" מופיע במאמר טיפול בתקלות במדיניות בתהליך הנוכחי.

איפה כדי להגדיר FaultRules: ProxyEndpoint או TargetEndpoint

כששרת proxy ל-API נתקל בשגיאה, השגיאה מתרחשת <ProxyEndpoint> (בקשה מאפליקציית לקוח או תשובה לאפליקציית הלקוח) או <TargetEndpoint> (בקשה לשירות היעד או תגובה ממנו). בכל מקום שבו כש-Edge מחפש את FaultRules,

לדוגמה, אם שרת יעד לא זמין (קוד סטטוס HTTP 503), שרת ה-proxy ל-API יפעל. למצב שגיאה בתגובה <TargetEndpoint>, וב-Proxy הרגיל ל-API הזרימה לא תמשיך אל <ProxyEndpoint>. אם הגדרתם כללי FaultRules רק ב-<ProxyEndpoint>, הם לא יטפלו בשגיאה הזו.

כאן יש דוגמה נוספת. אם מדיניות UploadFault בעמודה <ProxyEndpoint> תשובה גורמת לשגיאה, כלל FaultRule ב-<TargetEndpoint> לא מקבל בוצעה.

FaultRules לעומת מדיניות IncreaseFault

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

בקצרה:

• כללי תקלות תמיד מוערכים כששרת proxy ל-API מזין שגיאה .

• מדיניות RaiseFault מאפשרת להעביר שרת proxy ל-API במצב שגיאה. כאשר שגיאה לא הייתה מתרחשת בדרך אחרת.

  לדוגמה, אם אתם רוצים להקפיץ הודעת שגיאה אם קוד מצב ה-HTTP של התגובה מ- שירות היעד גדול מ-200, צריך להוסיף בתשובה מדיניות UploadFault . כתוב האתר שלך תיראה כך:

  <TargetEndpoint name="default">
      <PreFlow name="PreFlow">
  ...
          <Response>
              <Step>
                  <Name>Raise-Fault-1</Name>
  <!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                  <Condition>(response.status.code GreaterThan "200")</Condition>
              </Step>
          </Response> 

  בנוסף, מדיניות IncreaseFault שולחת הודעת שגיאה לאפליקציית הלקוח.

מה קורה כשמדיניות IncreaseFault יוצרת שגיאה שגורמת לשגיאה מה יכול להפעיל FaultRule? כאן העסק יכול להיות קצת יותר מורכב. אם המיקום מדיניות IncreaseFault מחזירה הודעת שגיאה וגם מופעלת FaultRule מחזירה הודעת שגיאה. מה מוחזר לאפליקציית הלקוח?

• מכיוון שה-FultRule או DefaultFaultRule מופעלים אחרי מדיניות IncreaseFault,. נתוני התגובה של FaultRule זוכים במנצחים.
• נתוני התגובה למדיניות IncreaseFault (קוד סטטוס, ביטוי סיבה או מטען ייעודי של הודעה) הם משמש אם הנתונים האלה לא מוגדרים על ידי FaultRule או DefaultFaultRule.
• אם גם במדיניות IncreaseFault וגם ב-FaultRule נוספו כותרות HTTP מותאמות אישית, שתיהן נכללות את התשובה. בשמות כפולים של כותרות, הכותרת נוצרת עם כמה ערכים.

הנה דוגמה להגדרה של מדיניות IncreaseFault ו-FaultRule, ומה מקבל שהוחזרו לאפליקציית הלקוח. הדוגמאות נועדו בקצרה, ולא לצורך שיטות מומלצות.

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: woops,gremlins

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: gremlins

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

תנאי הבניינים

התנאים הם המפתח להפעלה של כלל ה-FultRule. יוצרים את תנאי FaultRule באותו אופן. עושים זאת בתנאים אחרים ב-Edge, למשל, לתהליכים מותנים או לתנאים של IncreaseFault.

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

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

משתנים ספציפיים למדיניות שגיאות

המשתנים fault.name ו-{policy_namespace}.{policy_name}.failed זמינים כאשר מדיניות מקפיצה הודעת שגיאה.

fault.name

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

<Condition>(fault.name = "policy_error_name")</Condition>

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

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

התנאי ייראה כך:

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

להצגת שגיאה בנושא מדיניות רשימה של שגיאות מדיניות.

{policy_namespace}.{policy_name}.failed

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

• מדיניות LiftFault: raisefault.failed (כך גם כל כללי המדיניות של IncreaseFault)
• מדיניות VerifyAPIKey: oauthV2.{policy_name}.failed, עבור לדוגמה, oauthV2.Verify-API-Key-1.failed
• מדיניות המכסות והמדיניות של SpikeArrest: ratelimit.{policy_name}.failed, לדוגמה, ratelimit.Quota-1.failed

משתנים זמינים אחרים

כששרת proxy ל-API עובר למצב שגיאה, המשתנים הזמינים היחידים לשימוש בתנאים הן:

• המשתנים של המדיניות שנכשלו.
• המשתנים של הודעת ה-HTTP שקיימים בנקודת הכשל. לדוגמה, אם שגיאה היא שרץ בתגובה, מסוג FaultRule ב-<TargetEndpoint> עלול להשתמש ב-HTTP נתונים response.status.code, message.content, error.content וכן הלאה. לחלופין, אם מדיניות המכסה נכשלה, אפשר להשתמש משתנה ratelimit.{quota_policy_name}.exceed.count. שימוש בכלי המעקב ובמדיניות נושאים קשורים שיעזרו לכם להבין אילו משתנים ונתוני HTTP זמינים.

מידע נוסף

• תנאים: חומר עזר בנושא תנאים, משתני Flow וגם תנאים

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

שיטות מומלצות לטיפול בתקלות

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

ריכזנו כאן כמה שיטות מומלצות לתכנון ולטיפול בתקלות:

• לכל FaultRule, יש לציין 'שדה חיצוני' <Condition> (אח רכיב <Step>). כללי כשל ללא תנאי חיצוני שמתבצעת הערכה אוטומטית עד TRUE. "פנימי" תנאים של שלבים לא משמשים כדי לקבוע אם מתקיים כלל של FaultRule או FALSE. התנאים של השלבים מוערכים רק אחרי ש-Edge מבצע את FaultRule שמכיל אותם. ב-FultRule, בדרך כלל יש מספר שלבים עם מדיניות של הקצאת הודעה (או מדיניות אחרת), שבכל אחת מהן יש תנאי שלב.

• כדי לטפל בשגיאות בכמה כללי מדיניות מאותו סוג (לדוגמה, כמה מכסות) ), ליצור כלל שגיאה אחד לכל שגיאת מדיניות שסביר להניח שתקבלו. לדוגמה, ליצור כלל FaultRule לכל שגיאה אפשרית במדיניות המכסה, כמו QuotaViolation, InvalidMessageWeight StartTimeNotSupported. (מידע נוסף על שגיאות שקשורות למדיניות זמין כאן שגיאות שקשורות למדיניות. אם יזוהו שגיאות נוספות שצריך לטפל בהן, תהיה לך אפשרות לחזור אחורה מאוחר יותר ולהוסיף אותם לכללי FaultRule. זה בסדר להיות איטרטיבי, אבל זה כן מחייב פריסה מחדש של שרת proxy). הגישה הזו מאפשרת לזהות את אותו סוג של שגיאות, בלי קשר זורקת אותה, ולכן ה-XML של FaultRules יעיל.

  לאחר מכן כדאי להשתמש בתנאים של שלב פנימי אם דרושה לך שליטה פרטנית יותר בשגיאות. לדוגמה, אם אוכפים גם מכסת מפתחים נפרדים וגם מכסה גלובלית עם שני כללי מדיניות את תהליך הבקשה, מגדירים תנאי מסוג FaultRule יופעל שגיאה אחת (QuotaViolation) (שזורקת כשהמכסה חורגת בכל אחד מהמקרים). לאחר מכן צריך להגדיר תנאים לשלב כדי להעריך את המשתנים של exceed.count בשתי המכסה . רק השגיאה הרלוונטית נשלחת ללקוח (חריגה ממכסת המפתחים או שגיאה גלובלית חריגה מהמכסה). דוגמה להגדרה הזו:

  <FaultRule name="over_quota">
  <!-- This condition catches a QuotaViolation in *any* Quota policy -->
    <Condition>(fault.name = "QuotaViolation")</Condition>
    <Step>
      <Name>developer-over-quota-fault</Name>
      <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
    <Step>
      <Name>global-over-quota-fault</Name>
      <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
  </FaultRule>

  דוגמה נוספת: ראו את השרשור הזה של קהילת Apigee.

• כדי לטפל בשגיאות כשמשתמשים במדיניות אחת מסוג מסוים, כדאי להביא בחשבון טעות אחת כלל שמופעל כשמדיניות אחת נכשלת, וכולל כמה שלבים שממופים אל כל שגיאה אפשרית. כך ה-XML שלכם יעיל באמצעות FaultRule אחד במקום כמה כללי FaultRule (אחד לכל סוג שגיאה). לדוגמה:

  <FaultRule name="raise-fault-3">
  <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
    <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
    <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
    <Step>
      <Name>Generic-Key-Fault</Name>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-1</Name>
      <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-2</Name>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </Step>
  </FaultRule>

• מוסיפים כללי FaultRules שבהם השגיאות יתרחשו (בצד הלקוח <ProxyEndpoint>) או <TargetEndpoint> בצד היעד). צריך לכלול את כללי השגיאה בכל מדיניות מופיעה בכל אחד מהמיקומים.
• ב-FultRules, אפשר להפעיל כל סוג של מדיניות שיכולה להחזיר הודעה ללקוח אפליקציה. לשם כך, עדיף להשתמש במדיניות AssignMessage. כדאי גם לרשום את ההודעה ביומן באמצעות מדיניות MessageLogging כדי לעקוב אחר שגיאות.
• כשמשתמשים במדיניות IncreaseFault בשילוב עם FaultRules, צריך לתאם את התגובה. נתונים שנשלחים בחזרה כשמדיניות IncreaseFault ו-FaultRule מחזירים נתונים. עבור לדוגמה, אם מדיניות IncreaseFault מאפסת את קוד הסטטוס של HTTP, אין איפוס FaultRule את קוד הסטטוס. במקרה הגרוע ביותר, קוד הסטטוס שמוגדר כברירת מחדל מוחזר אפליקציית לקוח.
• ביצוע של <DefaultFaultRule>:
  • אם רוצים ש-<DefaultFaultRule> יופעל תמיד כשאין אפשרות אחרת פעולת FaultRule מתבצעת, אין לכלול בו <Condition>.
  • אם רוצים ש-<DefaultFaultRule> תמיד יופעל, גם אם FaultRule הופעל, צריך להוסיף את הפקודה רכיב צאצא <AlwaysEnforce>true</AlwaysEnforce>.

קו ביטול נעילה עבור טיפול מרוכז בתקלות רב-פעמיות

הפוסט הבא של קהילת Apigee מתאר דפוס לטיפול מרוכז בתקלות ללא כפילות של קוד:

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

יצירת כללי שגיאה

כדי להוסיף FaultRule, עליך לערוך את תצורת ה-XML של ProxyEndpoint נקודת קצה ביעד. אפשר לבצע את העריכה הזו בחלונית Code (קוד) בממשק המשתמש של Edge. פיתוח עבור שרת proxy ל-API, או עריכת קובץ ה-XML שמגדיר את נקודת ה-ProxyEndpoint נקודת קצה ביעד.

אם יוצרים כללי FaultRules בממשק המשתמש של הניהול, צריך קודם ליצור את כללי המדיניות שרוצים להפעיל. ואז להוסיף אותם להגדרה של FaultRule. (תופיע שגיאה בממשק המשתמש אם תנסו לשמור FaultRule שמפנה למדיניות שעדיין לא נוצרה).

הוספת מדיניות ל-FultRule

אפשר להוסיף כל מדיניות ב-FaultRule, אבל בדרך כלל משתמשים AssignMessage policy יוצר הודעת תגובה מותאמת אישית לתנאי שגיאה. AssignMessage מאפשר לך להגדיר תגובת HTTP עם מטען ייעודי (payload), קוד מצב HTTP, כותרות ולהציע אלמנטים של ביטויים.

הדוגמה הבאה מציגה הגדרה אופיינית של AssignMessage

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

עכשיו אפשר להשתמש במדיניות הזו ב-FaultRule. שימו לב איך אתם מפנים ל-AssignMessage המדיניות לפי השם ב-FultRule:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

כשפורסים את ההגדרות שלמעלה, שרת ה-proxy ל-API יריץ את המדיניות AssignMessage נקראת fault_invalidkey בכל פעם שאפליקציה מציגה מפתח API לא תקין.

אפשר להפעיל מספר כללי מדיניות ב-FultRule, כפי שמוצג בדוגמה הבאה:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

כללי המדיניות מופעלים לפי הסדר שהוגדר. לדוגמה, אפשר להשתמש מדיניותMessageLogging, מדיניות חילוץVariables, הקצאת מדיניות 'הקצאת הודעות', או כל מדיניות אחרת FaultRule. חשוב לדעת שהעיבוד של כלל ה-FultRule נפסק מיד אם אחד מהמצבים האלה קורה:

• כל מדיניות ב-FultRule גורמת לשגיאה
• כל כללי המדיניות ב-FaultRule הם מסוג IncreaseFault

מגדיר את הודעת שגיאה בהתאמה אישית שהוחזרה מ-FaultRule

מומלץ להגדיר תגובות ברורות לשגיאות מהקובץ ממשקי API. כך תוכלו לספק ללקוחות מידע שימושי ועקבי.

בדוגמה הבאה של AssignMessage policy אפשר להשתמש ב-<Payload>, תגים מסוג <StatusCode>, ו-<ReasonPhase> כדי להגדיר את התג המותאם אישית תגובת שגיאה נשלחה חזרה ללקוח בשגיאת InvalidApiKey (פרטים קודמים של FaultRules) לדוגמה).

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. 
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

התגובה הזו כוללת:

• המטען הייעודי (Payload) שמכיל את הודעת השגיאה וכתובת אימייל ליצירת קשר עם התמיכה.
• קוד מצב ה-HTTP שהוחזר בתגובה.
• ביטוי הסיבה, שהוא תיאור קצר של השגיאה.

יצירת DefaultFaultRule

DefaultFaultRule משמש כ-handler של חריג לכל שגיאה שלא מטופלת באופן מפורש על ידי כלל FaultRule נוסף. אם התנאים של כל כללי השגיאה לא תואמים לשגיאה, DefaultFaultRule מטפל בשגיאה. כדי להפעיל את ברירת המחדל לטיפול בתקלות, צריך להוסיף את הפונקציה התג <DefaultFaultRule> כרכיב צאצא של ProxyEndpoint או נקודת קצה ביעד.

לדוגמה, התצורה של TargetEndpoint הבאה מגדירה ערך DefaultFaultRule שמפעיל מדיניות בשם ReturnגנריError:

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

ב-DefaultFaultRule משתמשים בדרך כלל להחזיר הודעת שגיאה כללית במקרה של למשל הודעה שמכילה פרטים ליצירת קשר עם התמיכה הטכנית. ברירת המחדל הזו אותה מטרה משמשת לשתי מטרות: מתן מידע ידידותי למפתחים, ערפול קוד (obfuscation) של כתובות URL של קצה עורפי או מידע אחר שעלול לשמש לפגיעה במערכת.

לדוגמה, תגדיר את מדיניות AssignMessage הבאה כדי להחזיר שגיאה גנרית:

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

לכלול את הרכיב <AlwaysEnforce> <DefaultFaultRule> להפעלת DefaultFaultRule עבור כל שגיאה, גם אם כבר בוצע FaultRule אחר. DefaultFaultRule הוא תמיד FaultRule לבצע:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

אחד השימושים ב-DefaultFaultRule הוא לקבוע את סוג השגיאה שמתרחשת אחרת, לא ניתן לקבוע אותו. לדוגמה, שרת ה-proxy ל-API נכשל עבור שגיאה לא ניתן לקבוע. משתמשים ב-DefaultFaultRule כדי להפעיל את מדיניות AssignMessage הבאה. הזה המדיניות כותבת את הערך fault.name לכותרת בשם DefaultFaultHeader בתשובה:

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

לאחר מכן אפשר להציג את הכותרת בכלי מעקב הקצה או בתגובה כדי לראות מה גרם שגיאה.

הוספת רישום של הודעות ביומן ל PostClientFlow

PostClientFlow הוא התהליך היחיד שמופעל אחרי ששרת ה-Proxy מכניס את השגיאה. . אפשר לצרף לתהליך הזה רק את מדיניות MessageLogging, שמופעלת אחרי שהתשובה נשלחה בחזרה ללקוח. למרות שצירוף מדיניות MessageLogging לתהליך הזה, מבחינה טכנית לא לטיפול בשגיאות, אפשר להשתמש בו כדי לרשום מידע במקרה של שגיאה. כי זה גם אם שרת ה-Proxy הצליח וגם אם נכשל, אפשר להגדיר לרישום הודעות (Message Logging). ב-PostClientFlow ותוודאו שהם תמיד יופעלו.

טיפול בכשלים במדיניות בתהליך הנוכחי

בדוגמאות שהוצגו עד עכשיו נעשה שימוש ב-FultRule ב-ProxyEndpoint או ב-TargetEndpoint. שגיאות מדיניות כחלק ממצב השגיאה. הסיבה לכך היא שערך ברירת המחדל רכיב continueOnError של המדיניות הוא false. כלומר, כאשר שגיאה במדיניות, הבקרה מופנית למצב השגיאה. אחרי שבמצב שגיאה, לא יכולים להחזיר את הבקרה לצינור עיבוד הנתונים הרגיל, ובדרך כלל מחזירים סוג כלשהו של שגיאה הודעה לאפליקציית השיחות.

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

למטה מוצגת מדיניות VerifyAPIKey בשם verify-api-key עם הרכיב continueOnError הוגדר בתור true:

<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

אם מפתח ה-API חסר או לא חוקי, מדיניות VerifyAPIKey מגדירה את המשתנה oauthV2.verify-api-key.failed ל-true, אבל מתבצע עיבוד ממשיך בזרימה הנוכחית.

לאחר מכן מוסיפים את המדיניות VerifyAPIKey כשלב בקטע PreFlow של ProxyEndpoint:

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>      
</ProxyEndpoint>  

שימו לב איך השלב הבא ב-PreFlow משתמש בתנאי כדי לבדוק אם קיים שגיאה. אם אירעה שגיאה במדיניות VerifAPIKey, המדיניות שנקראת המדיניות FaultInFlow תופעל. אחרת, המדיניות FaultInFlow בוצע דילוג. למדיניות FaultInFlow יכולות להיות הרבה פעולות, כמו רישום של השגיאה ביומן, מנסה לתקן את השגיאה או לבצע פעולה אחרת.

הפעלת שגיאה באמצעות IncreaseFault מדיניות

אפשר להשתמש במדיניות UploadFault בכל שלב בתהליך כדי להפעיל שגיאה. כאשר מדיניות IncreaseFault מופעלת, מסיים את התהליך הנוכחי ומעבירה את הבקרה לשגיאה .

אחד השימושים במדיניות IncreaseFault הוא לבדוק תנאי ספציפי שמדיניות אחרת לא יכול לזהות. בדוגמה שלמעלה, הוספת תג <Condition> אל התג <Step> לפני הזרימה מראש שגרם להפעלת המדיניות FaultInFlow אם התנאי מתקיים. אם FaultInFlow הוא מדיניות IncreaseFault, אז בקרה מועברות למצב שגיאה. לחלופין, אפשר להכניס מדיניות IncreaseFault לתהליך לניפוי באגים לבדוק את כללי FaultRules.

כשמדיניות IncreaseFault גורמת לשגיאה, אפשר להשתמש ב-FultRule ובתנאי הבאים כדי לעבד אותו:

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

שימו לב שהתנאי בודק אם יש תקלה בשם RaiseFault. The riseFault המדיניות תמיד מגדירה את הערך של fault.name כ-RaiseFault.

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

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

כברירת מחדל, Edge מתייחס לקודי תגובה של HTTP בטווח 1xx-3xx כ'הצלחה' ול-HTTP קודי תגובה בטווח 4xx-5xx כ-'failure'. כלומר כל תגובה מהקצה העורפי עם קוד תגובת HTTP 4xx-5xx, ומצב השגיאה מופעל באופן אוטומטי, מחזירה הודעת שגיאה ישירות ללקוח שמגיש את הבקשה.

ניתן ליצור handlers מותאמים אישית לכל קוד תגובה של HTTP. לדוגמה, ייתכן שלא תרצו יש להתייחס לכל קודי התגובה של HTTP בטווח 4xx-5xx כ-'failure' אלא רק 5xx, או שאולי תרצו כדי להחזיר הודעות שגיאה מותאמות אישית עבור קודי התגובה 400 ו-500 של HTTP.

בדוגמה הבאה, משתמשים במאפיין success.codes כדי להגדיר את TargetEndpoint לטיפול בקודי תגובה 400 ו-500 של HTTP כהצלחה, יחד עם ברירת המחדל של HTTP קודים. על ידי התייחסות לקודים האלה כהצלחה, TargetEndpoint משתלטת על עיבוד הודעת תגובה, במקום להפעיל את מצב השגיאה:

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

כמו שאפשר לראות בדוגמה הזו, אפשר להשתמש בתווים כלליים לחיפוש כדי להגדיר את המאפיין success.codes לטווח של ערכים.

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

<Property name="success.codes">1xx,2xx,3xx,400</Property>

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

<Property name="success.codes">400</Property>

עכשיו אפשר להגדיר handlers מותאמים אישית לקודי תגובה 400 ו-500 של HTTP כדי להחזיר הודעת תגובה לאפליקציה ששלחה את הבקשה. נקודת הקצה (TargetEndpoint) הבאה משתמשת במדיניות שנקראת ReturnError כדי לטפל בקודי תגובה של HTTP 400 ו-500:

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

ההגדרה הזו של נקודת הקצה (TargetEndpoint) גורמת למדיניות שנקראת ReturnError לטפל את התגובה בכל פעם ש-TargetEndpoint נתקל בקוד תגובה 400 או 500 של HTTP.

טקסונומיית שגיאות

שירותי API מארגנים את התקלות בקטגוריות ובקטגוריות המשנה הבאות.

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

• סיבה
• מאפיינים מותאמים אישית בהגדרת המשתמש