رسیدگی به عیوب

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

زمانی که پراکسی های API در حال سرویس دهی به درخواست های برنامه ها هستند، بسیاری از شرایط خطا ممکن است ایجاد شوند. برای مثال، پراکسی‌های API ممکن است هنگام برقراری ارتباط با سرویس‌های پشتیبان با مشکلات شبکه مواجه شوند، برنامه‌ها اعتبارنامه‌های منقضی شده را ارائه دهند، پیام‌های درخواستی ممکن است به اشتباه قالب‌بندی شده باشند و غیره.

هنگامی که پس از تماس برنامه مشتری با یک پروکسی API، خطایی رخ می دهد، یک پیام خطا به سرویس گیرنده برگردانده می شود. به طور پیش‌فرض، مشتری یک پیام خطای مرموز را بدون جزئیات یا راهنمایی دریافت می‌کند. اما اگر می‌خواهید پیام‌های خطای پیش‌فرض را با پیام‌های سفارشی مفیدتر جایگزین کنید و حتی آنها را با مواردی مانند هدرهای HTTP اضافی غنی کنید، باید مدیریت خطای سفارشی را در Edge تنظیم کنید.

مدیریت خطای سفارشی همچنین به شما امکان می دهد هر زمان که خطایی رخ می دهد، عملکردهایی مانند ثبت پیام را اضافه کنید.

قبل از اینکه در مورد پیاده سازی مدیریت خطای سفارشی در پراکسی های API خود صحبت کنیم، درک چگونگی رخ دادن خطاها و واکنش پراکسی های API به آنها مفید است.

ویدیوها

ویدیوهای زیر را تماشا کنید تا در مورد نحوه رسیدگی به خطا بیشتر بدانید.

چگونه خطاها رخ می دهد

ابتدا به سادگی نحوه رخ دادن خطاها را پوشش خواهیم داد. دانستن چگونگی رخ دادن خطاها به شما کمک می کند تا برای موقعیت های مختلفی که می خواهید مدیریت خطای سفارشی را پیاده سازی کنید، برنامه ریزی کنید.

خطاهای خودکار

یک پروکسی API در شرایط زیر به طور خودکار یک خطا ایجاد می کند:

• یک سیاست باعث خطا می شود. به عنوان مثال، اگر یک تماس API یک کلید منقضی شده ارسال کند، خط مشی VerifyAPIKey به طور خودکار یک خطا ایجاد می کند. یا اگر تعداد تماس های API از حد معینی بیشتر شود، خط مشی Quota یا خط مشی SpikeArrest خطایی ایجاد می کند. (برای انواع خطاهایی که سیاست ها می توانند ایجاد کنند ، مرجع خطای خط مشی را ببینید).
• مشکلی در جریان پیام پروکسی API وجود دارد، مانند خطای مسیریابی.
• یک خطای Backend وجود دارد، مانند یک خطای HTTP به دلیل نقص در سطح پروتکل، خطاهای TLS/SSL، یا یک سرویس هدف در دسترس نیست.
• یک نقص در سطح سیستم وجود دارد، مانند استثنای خارج از حافظه.

برای اطلاعات بیشتر در مورد این خطاها، طبقه بندی خطا را در این مبحث ببینید.

خطاهای سفارشی

برای موقعیت هایی که خطای خودکار وجود ندارد، ممکن است بخواهید یک خطای سفارشی ایجاد کنید. برای مثال، اگر یک پاسخ حاوی کلمه "unavailable" باشد، یا اگر کد وضعیت HTTP بزرگتر از 201 باشد. این کار را با افزودن یک خط مشی RaiseFault به مکان مناسب در یک جریان پراکسی API انجام دهید.

شما می توانید یک خط مشی RaiseFault را به یک جریان پراکسی API اضافه کنید، همانطور که هر خط مشی دیگری را انجام می دهید. در مثال پیکربندی پراکسی زیر، خط مشی Raise-Fault-1 به پاسخ TargetEndpoint متصل شده است. اگر کلمه "unavailable" در پاسخ سرویس مورد نظر وجود داشته باشد، خط مشی RaiseFault اجرا می شود و یک خطا ایجاد می کند.

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

این فقط به شما نشان می دهد که می توانید خطاهای سفارشی ایجاد کنید. در بخش خط مشی FaultRules در مقابل RaiseFault به جزئیات بیشتری در مورد خط مشی RaiseFault می پردازیم.

برای مثال‌های بیشتر، این پست‌ها را در انجمن انجمن Apigee ببینید:

• ارجاع به متغیرهای جاوا اسکریپت در RaiseFault

کاری که پراکسی های API هنگام بروز خطا انجام می دهند

زمانی که یک پروکسی خطا می دهد چه اتفاقی می افتد.

از خط لوله پروکسی خارج شوید

هنگامی که یک پروکسی API با یک خطا روبرو می شود، صرف نظر از نحوه رخ دادن آن، از خط لوله جریان عادی خارج می شود، وارد وضعیت خطا می شود و یک پیام خطا به برنامه مشتری برمی گرداند. هنگامی که پروکسی API وارد حالت خطا می شود، نمی تواند پردازش را به خط لوله جریان عادی برگرداند.

برای مثال، فرض کنید یک پروکسی API دارای خط‌مشی‌هایی به ترتیب زیر در درخواست ProxyEndpoint است:

1. کلید API را تأیید کنید
2. سهمیه
3. JSON به XML

اگر در حین تأیید کلید API خطایی رخ دهد، پراکسی API به حالت خطا منتقل می شود. خط‌مشی‌های Quota و JSON به XML اجرا نمی‌شوند، پروکسی به TargetEndpoint نمی‌رود و یک پیام خطا به برنامه مشتری بازگردانده می‌شود.

FaultRules را بررسی کنید

در حالت خطا، پراکسی‌های API نیز وجود موارد زیر را (به ترتیب) در پیکربندی پراکسی API قبل از بازگرداندن یک پیام خطای پیش‌فرض به برنامه مشتری بررسی می‌کنند:

1. یک بخش <FaultRules> که حاوی منطق راه اندازی پیام های خطای سفارشی (و سایر خط مشی ها) بر اساس شرایط خاصی است که شما تعریف می کنید.
2. یک بخش <DefaultFaultRule> ، که یک پیام خطای پیش فرض را در شرایط زیر راه اندازی می کند:
   • هیچ <FaultRules> تعریف نشده است.
   • هیچ <FaultRules> موجود اجرا نمی شود.
   • عنصر <AlwaysEnforce> روی true تنظیم شده است.

در اصل، پروکسی API به شما این فرصت را می دهد که یک پیام خطای سفارشی را برگردانید و منطق دیگر را راه اندازی کنید. اگر پراکسی هیچ یک از آن بخش ها را پیدا نکند، یا وجود داشته باشد اما هیچ خطای سفارشی ایجاد نشده باشد، پروکسی پیام پیش فرض تولید شده توسط Edge خود را ارسال می کند.

مثال ساده رسیدگی به خطا

بیایید با یک مثال ساده شروع کنیم، جایی که تماس با یک پراکسی 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 نیاز دارد که وقتی پروکسی به حالت خطا می رود، خط مشی را اجرا می کند.

1. یک خط مشی ایجاد کنید که پیام سفارشی را تعریف کند

ابتدا یک خط مشی ایجاد کنید که پیام خطای سفارشی را تعریف کند. می‌توانید از هر نوع خط‌مشی، مانند خط‌مشی AssignMessage ، استفاده کنید که می‌تواند یک بار و سرصفحه‌های اختیاری HTTP مانند کد وضعیت و عبارت دلیل را تنظیم کند. Assign Message برای این کار ایده آل است. این به شما امکان می دهد بار پیام را کنترل کنید، یک کد وضعیت HTTP متفاوت تنظیم کنید، یک عبارت دلیل HTTP متفاوت تنظیم کنید و سرصفحه های HTTP را اضافه کنید.

خط مشی را به هیچ جریانی در پروکسی API متصل نکنید. کافی است که به سادگی در بسته پروکسی وجود داشته باشد. برای انجام این کار در ویرایشگر پروکسی UI مدیریت، به تب Develop و در قسمت Navigation بروید و روی نماد + در نوار Policies کلیک کنید.

این به شما امکان می دهد یک خط مشی بدون پیوست کردن آن به جریانی در پروکسی 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> پیکربندی پروکسی، یک بلوک XML <FaultRules> را اضافه می‌کنید که حاوی یک یا چند بخش <FaultRule> منفرد است. هر FaultRule نشان دهنده خطای متفاوتی است که می خواهید با آن برخورد کنید. در این مثال ساده، ما فقط از یک FaultRule استفاده می کنیم تا به شما نشان دهیم از چه چیزی تشکیل شده است.

همچنین باید یک <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>

نکات کلیدی:

• FaultRules در ProxyEndpoint تعریف شده است. این مهم است. بیشتر در مورد قرار دادن FaultRules در ProxyEndpoint در مقابل TargetEndpoint بعداً.
• <Name> - نام سیاستی که باید اجرا شود. همانطور که در مثال خط مشی قبلی نشان داده شده است، نام از ویژگی name خط مشی در عنصر والد می آید.

• <Condition> - Edge شرط را ارزیابی می کند و سیاست را تنها در صورتی اجرا می کند که شرط درست باشد. اگر چندین FaultRule وجود داشته باشد که به درستی ارزیابی شود، Edge اولین مورد درست را اجرا می کند. ( مهم : ترتیب ارزیابی FaultRules، از بالا به پایین یا پایین به بالا، بین TargetEndpoint و ProxyEndpoint متفاوت است، همانطور که در بخش Multiple FaultRules و منطق اجرا توضیح داده شده است.) اگر شرطی را وارد نکنید، FaultRule به طور خودکار درست است. اما این بهترین تمرین نیست. هر FaultRule باید شرایط خاص خود را داشته باشد.

• <DefaultFaultRule> - اگر هیچ FaultRule سفارشی اجرا نشود، <DefaultFaultRule> اجرا می شود و یک پیام سفارشی عمومی تر به جای پیام مرموز پیش فرض Edge-generated ارسال می شود. یک <DefaultFaultRule> همچنین می تواند یک <Condition> داشته باشد، اما در بیشتر موارد شما یکی را شامل نمی شوید، زیرا می خواهید بدون توجه به آخرین راه حل اجرا شود.

  DefaultFaultRule معمولاً برای بازگرداندن یک پیام خطای عمومی برای هر خطای غیرمنتظره ای استفاده می شود. یک مثال می تواند پیامی باشد که حاوی اطلاعات تماس برای پشتیبانی فنی است. این پاسخ پیش‌فرض به هدف دوگانه ارائه اطلاعات مناسب برای توسعه‌دهنده عمل می‌کند و در عین حال نشانی‌های وب پشتیبان یا سایر اطلاعاتی را که ممکن است برای به خطر انداختن سیستم مورد استفاده قرار گیرند، مبهم می‌سازد.

قوانین خطای متعدد و منطق اجرا

در بخش Simple fault handling example ، از یک مثال ساده از یک FaultRule و شرط استفاده کردیم. در یک پروژه API دنیای واقعی، با تمام خطاهای احتمالی که ممکن است رخ دهد، احتمالاً چندین FaultRule و DefaultFaultRule در هر دو <ProxyEndpoint> و <TargetEndpoint> خود دارید. با این حال، در نهایت، تنها یک FaultRule زمانی که یک پروکسی API به حالت خطا می رود اجرا می شود.

این بخش، منطقی را که Edge در مدیریت FaultRule استفاده می‌کند، از نحوه رسیدن به یک FaultRule برای اجرا گرفته تا نحوه مدیریت شرایط Step «داخلی» در هنگام راه‌اندازی FaultRule توضیح می‌دهد. این بخش همچنین راهنمایی در مورد زمان تعریف FaultRules در <ProxyEndpoint> در مقابل <TargetEndpoint> ارائه می دهد و رابطه بین FaultRules و خط مشی RaiseFault را توضیح می دهد.

اجرای FaultRules

به طور خلاصه، در اینجا منطقی است که Edge زمانی که یک پروکسی API در حالت خطا قرار می گیرد استفاده می کند. توجه داشته باشید که بین ارزیابی FaultRules در ProxyEndpoint در مقابل TargetEndpoint تفاوت جزئی وجود دارد.

1. Edge بسته به محل وقوع خطا، FaultRules را در ProxyEndpoint یا TargetEndpoint ارزیابی می کند:
   • ProxyEndpoint - Edge با <FaultRule> پایین در پیکربندی XML شروع می‌شود و به سمت بالا پیش می‌رود و <Condition> هر <FaultRule> را ارزیابی می‌کند (شرایط "خارجی"، نه شرایط <Step> "درونی".
   • TargetEndpoint - Edge با <FaultRule> بالایی در پیکربندی XML شروع می‌شود و به سمت پایین حرکت می‌کند و <Condition> هر <FaultRule> را ارزیابی می‌کند (شرایط بیرونی، نه شرایط <Step> درونی).
2. اولین FaultRule را که شرط آن true است را اجرا می کند. اگر یک FaultRule هیچ شرطی نداشته باشد، به طور پیش فرض درست است.
   • هنگامی که یک FaultRule اجرا می شود، تمام مراحل داخل FaultRule به ترتیب، از بالا به پایین در پیکربندی XML ارزیابی می شوند. مراحل بدون شرط به طور خودکار اجرا می شوند (خط مشی ها اجرا می شوند)، و مراحلی که دارای یک <Condition> هستند که به "true" ارزیابی می شود، اجرا می شوند (شرایطی که به "false" ارزیابی می شوند، اجرا نمی شوند).

   • اگر یک FaultRule اجرا شود، اما هیچ مرحله‌ای در FaultRule اجرا نشود (زیرا شرایط آنها "نادرست" ارزیابی می‌شود)، پیام خطای پیش‌فرض 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>

دستور قانون خطا

همانطور که در مثال قبلی می بینید، ترتیب قرار دادن FaultRules بسته به اینکه آیا خطا در ProxyEndpoint در مقابل TargetEndpoint رخ می دهد، مهم است.

به عنوان مثال:

سیاست هایی که باید گنجانده شود

شما می توانید هر سیاستی را از یک FaultRule با قرار دادن آنها در Steps اجرا کنید. برای مثال، می‌توانید یک خط‌مشی AssignMessage را برای قالب‌بندی پاسخ به برنامه مشتری اجرا کنید، سپس پیامی را با خط‌مشی MessageLogging ثبت کنید. خط‌مشی‌ها به ترتیبی که قرار داده‌اید (از بالا به پایین در XML) اجرا می‌شوند.

قوانین خطا فقط در حالت خطا فعال می شوند (درباره continueOnError)

ممکن است عنوان به نظر برسد که ما داریم خودمان را تکرار می‌کنیم، اما یک نکته ظریف وجود دارد که باید در رابطه با خطای پروکسی که باعث می‌شود یک پروکسی API وارد حالت خطا شود – یا بهتر است بگوییم، وارد نشدن حالت خطا – یا بهتر بگوییم وارد نشدن حالت خطا، از یک نکته ظریف آگاه باشیم: ویژگی continueOnError در یک سیاست

برای جمع بندی: یک پراکسی API فقط در صورتی که پراکسی وارد حالت خطا شده باشد <FaultRules> و <DefaultFaultRule> را ارزیابی می کند. این بدان معنی است که حتی اگر یک شرط FaultRule به درستی ارزیابی شود، اگر پروکسی در حالت خطا نباشد، راه اندازی نمی شود.

با این حال، در اینجا مثالی از وقوع خطا و عدم ورود پراکسی به حالت خطا آورده شده است. در هر خط‌مشی، می‌توانید یک ویژگی روی عنصر والد به نام continueOnError تنظیم کنید. این ویژگی با توجه به رسیدگی به خطا بسیار مهم است، زیرا تعیین می کند که آیا در صورت شکست خط مشی، پروکسی وارد حالت خطا می شود یا خیر. در بیشتر موارد، می‌خواهید پیش‌فرض continueOnError="false" را حفظ کنید، که در صورت شکست خط‌مشی، پروکسی را در حالت خطا قرار می‌دهد و مدیریت خطای سفارشی شما فعال می‌شود. با این حال، اگر continueOnError="true" (به عنوان مثال، اگر نمی‌خواهید شکست سرویس Callout اجرای پراکسی را متوقف کند)، در صورت عدم موفقیت آن خط‌مشی، پراکسی به حالت خطا نمی‌رود ، و پراکسی نمی‌تواند. به FaultRules خود نگاه نکنید.

برای اطلاعات در مورد خطاهای ثبت‌نام در هنگام continueOnError="true" ، به رسیدگی به خطاهای خط مشی در جریان جاری مراجعه کنید.

محل تعریف FaultRules: ProxyEndpoint یا TargetEndpoint

هنگامی که یک پروکسی API با خطا مواجه می شود، خطا یا در <ProxyEndpoint> (درخواست از یا پاسخ به برنامه مشتری) یا در <TargetEndpoint> (درخواست به یا پاسخ از سرویس هدف) رخ می دهد. هر جا که این خطا رخ دهد، Edge به دنبال FaultRules می‌گردد.

به عنوان مثال، اگر یک سرور هدف در دسترس نباشد (کد وضعیت HTTP 503)، پراکسی API در پاسخ <TargetEndpoint> به حالت خطا می رود و جریان عادی پروکسی API به <ProxyEndpoint> ادامه نمی یابد. اگر FaultRules را فقط در <ProxyEndpoint> تعریف کرده باشید، آن خطا را کنترل نخواهند کرد.

در اینجا یک مثال دیگر است. اگر خط مشی RaiseFault در پاسخ <ProxyEndpoint> خطایی را ایجاد کند، یک FaultRule در <TargetEndpoint> اجرا نمی شود.

FaultRules در مقابل خط مشی RaiseFault

قوانین خطا و خط مشی RaiseFault ممکن است در ظاهر مانند روش های جایگزین برای انجام رسیدگی به خطا به نظر برسد. و از جهاتی این درست است. اما آنها با هم کار می کنند. این بخش رابطه بین این دو را توضیح می دهد. درک این رابطه باید به شما در طراحی مدیریت خطا کمک کند، به خصوص اگر می خواهید از هر دو استفاده کنید.

به طور خلاصه:

• قوانین خطا همیشه زمانی ارزیابی می شوند که یک پروکسی API وارد حالت خطا شود.

• خط مشی RaiseFault راهی برای قرار دادن یک پراکسی API در حالت خطا است در حالی که خطا در غیر این صورت رخ نمی داد.

  به عنوان مثال، اگر می خواهید خطای ارسال کنید اگر کد وضعیت HTTP در پاسخ از سرویس هدف بزرگتر از 200 باشد، یک خط مشی RaiseFault را در جریان پاسخ خود اضافه می کنید. چیزی شبیه به این خواهد بود:

  <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> 

  خط مشی RaiseFault همچنین یک پیام خطا به برنامه مشتری ارسال می کند.

وقتی خط مشی RaiseFault خطایی را راه‌اندازی می‌کند، که پروکسی را در حالت خطا قرار می‌دهد، که به طور بالقوه یک FaultRule را اجرا می‌کند، چه اتفاقی می‌افتد؟ اینجا جایی است که همه چیز می تواند کمی پیچیده شود. اگر خط مشی RaiseFault یک پیام خطا برگرداند و یک FaultRule راه اندازی شود و یک پیام خطا برگرداند، چه چیزی به برنامه مشتری بازگردانده می شود؟

• از آنجایی که FaultRule یا DefaultFaultRule بعد از خط مشی RaiseFault اجرا می شود، داده پاسخ FaultRule برنده می شود.
• داده‌های پاسخ خط مشی RaiseFault (کد وضعیت، عبارت دلیل یا بار پیام) در صورتی استفاده می‌شود که این داده‌ها توسط FaultRule یا DefaultFaultRule تنظیم نشده باشند.
• اگر هم خط مشی RaiseFault و هم FaultRule سرصفحه های سفارشی HTTP اضافه کنند، هر دو در پاسخ گنجانده می شوند. نام های تکراری سرصفحه ای با چندین مقدار ایجاد می کنند.

در اینجا نمونه‌ای از مواردی است که توسط یک خط‌مشی RaiseFault و یک 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

شرایط ساختمان

شرایط کلید اجرای FaultRule هستند. شما شرایط FaultRule را به همان روشی که برای سایر شرایط در Edge ایجاد می کنید، مانند برای جریان های شرطی یا شرایط RaiseFault ایجاد می کنید.

برای قرار دادن بقیه این بخش در زمینه، در اینجا یک قانون خطای نمونه وجود دارد که دارای یک شرط FaultRule بیرونی و یک شرط Step داخلی است.

<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 ، خطا را در یک شرط پیدا کنید. به عنوان مثال:

<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 برای خط مشی های مختلف آورده شده است. برای فضاهای نام خط مشی، متغیرهای جریان را در هر موضوع مرجع خط مشی ببینید.

• خط مشی RaiseFault : raisefault.failed (برای همه خط مشی های RaiseFault یکسان است)
• خط‌مشی VerifyAPIKey : oauthV2.{policy_name}.failed ، برای مثال، oauthV2.Verify-API-Key-1.failed
• خط مشی سهمیه و خط مشی SpikeArrest : ratelimit.{policy_name}.failed ، برای مثال ratelimit.Quota-1.failed

سایر متغیرهای موجود

هنگامی که یک پروکسی API به حالت خطا می رود، تنها متغیرهای موجود برای استفاده در شرایط عبارتند از:

• متغیرهای سیاست شکست خورده است.
• متغیرهای پیام HTTP که در نقطه شکست وجود دارند. برای مثال، اگر خطایی در پاسخ رخ دهد، یک FaultRule در <TargetEndpoint> می‌تواند از داده‌های HTTP response.status.code ، message.content ، error.content و غیره استفاده کند. یا اگر یک خط مشی سهمیه ناموفق بود، می توانید از متغیر ratelimit.{quota_policy_name}.exceed.count . از ابزار Trace و موضوعات مرجع خط مشی استفاده کنید تا به شما کمک کند بفهمید کدام متغیرها و داده های HTTP در دسترس هستند.

اطلاعات بیشتر

• شرایط : مرجع شرایط و متغیرها و شرایط جریان

• خطاها : مرجع خطای خط مشی
• متغیرها : متغیرها مرجع هستند و صفحات مرجع خط مشی جداگانه را برای متغیرهایی که با هر خط مشی در دسترس هستند، ببینید.

بهترین روش ها برای رسیدگی به خطا

مدیریت خطا یک کار طراحی معماری اصلی برای توسعه پروکسی API است. این مهم است که زمان بگذارید تا بفهمید که چگونه و چه زمانی می‌خواهید خطاها را مدیریت کنید، تعیین کنید که پیام‌های خطا چه می‌گویند و قالب‌های پیام خطا را طراحی کنید. پس از (یا هنگامی که) آن چیزها را فهمیدید، سپس از این بهترین شیوه ها برای کمک به شما در اجرای مدیریت خطا استفاده کنید.

در زیر برخی از بهترین شیوه ها در طراحی و مدیریت عیب در ساختمان آورده شده است:

• برای هر FaultRule، یک <Condition> "بیرونی" (برابر عنصر <Step> ) ارائه دهید. قوانین خطا بدون شرایط بیرونی به طور خودکار به درستی ارزیابی می شود. برای تعیین درست یا نادرست بودن یک FaultRule از شرایط گام "داخلی" استفاده نمی شود. شرایط مرحله فقط پس از اجرای FaultRule شامل Edge ارزیابی می شود. در یک FaultRule، معمولاً چندین مرحله با خط‌مشی‌های Assign Message (یا سایر موارد) وجود دارد که هر کدام دارای یک شرط Step هستند.

• برای رسیدگی به خطاها در چندین خط مشی از یک نوع (مثلاً چندین خط مشی Quota)، به ازای هر خطای خط مشی که احتمالاً دریافت خواهید کرد، یک FaultRule ایجاد کنید. به عنوان مثال، برای هر خطای احتمالی در خط مشی های Quota، مانند QuotaViolation ، InvalidMessageWeight ، StartTimeNotSupported یک FaultRule ایجاد کنید. (به مرجع خطای خط مشی برای خطاهای خط مشی رجوع کنید. همانطور که خطاهای دیگری را کشف می کنید که باید رسیدگی شوند، می توانید بعداً به عقب برگردید و آنها را به FaultRules خود اضافه کنید. اشکالی ندارد که تکرار شوند، اگرچه نیاز به استقرار مجدد پروکسی دارد.) این رویکرد اجازه می دهد تا شما می توانید همان نوع خطا را بدون توجه به اینکه کدام خط مشی ایجاد می کند، دریافت کنید، که باعث می شود FaultRules XML شما کارآمد باشد.

  سپس اگر به کنترل خطای دقیق تری نیاز دارید، از شرایط مرحله داخلی استفاده کنید. به عنوان مثال، اگر هم سهمیه توسعه‌دهنده فردی و هم سهمیه جهانی را با دو خط‌مشی در جریان درخواست خود اعمال می‌کنید، شرط FaultRule "خارجی" خود را طوری تنظیم کنید که در خطای QuotaViolation (که در هر صورت زمانی که سهمیه از بین می‌رود، ایجاد می‌شود) ایجاد شود. سپس شرایط Step را برای ارزیابی متغیرهای 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> ). شامل FaultRules برای هر خط مشی که در هر مکان ظاهر می شود.
• در FaultRules، می‌توانید هر نوع سیاستی را که می‌تواند پیامی را به برنامه مشتری بازگرداند، اجرا کنید. خط مشی AssignMessage برای این کار ایده آل است. همچنین اگر می‌خواهید خطاها را پیگیری کنید، پیامی را با سیاست MessageLogging ثبت کنید.
• هنگام استفاده از خط‌مشی‌های RaiseFault در ارتباط با FaultRules، داده‌های پاسخی را که هنگام بازگشت داده‌های خط‌مشی RaiseFault و FaultRule ارسال می‌شوند، هماهنگ کنید. به عنوان مثال، اگر خط مشی RaiseFault شما کد وضعیت 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

ایجاد FaultRules

برای اضافه کردن FaultRule باید پیکربندی XML ProxyEndpoint یا TargetEndpoint را ویرایش کنید. می‌توانید از رابط کاربری Edge برای انجام این ویرایش در پنجره کد نمای Develop برای یک پراکسی API استفاده کنید، یا فایل XML را که ProxyEndpoint یا TargetEndpoint را تعریف می‌کند، ویرایش کنید.

اگر FaultRules را در رابط کاربری مدیریت ایجاد می‌کنید، ابتدا سیاست‌هایی را که می‌خواهید اجرا کنید ایجاد کنید، سپس آنها را به پیکربندی FaultRule اضافه کنید. (اگر سعی کنید FaultRule را ذخیره کنید که به خط مشی ای اشاره می کند که هنوز ایجاد نشده است.)

افزودن خط مشی ها به FaultRule

در حالی که می توانید هر خط مشی را در FaultRule قرار دهید، معمولاً از خط مشی AssignMessage برای ایجاد یک پیام پاسخ سفارشی برای شرایط خطا استفاده می کنید. AssignMessage شما را قادر می سازد یک پاسخ HTTP را با بار، کد وضعیت 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 با نام در FaultRule توجه کنید:

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

هنگامی که پیکربندی بالا را اجرا می کنید، هر زمان که یک برنامه یک کلید API نامعتبر ارائه دهد، پروکسی API خط مشی AssignMessage به نام fault_invalidkey را اجرا می کند.

همانطور که مثال زیر نشان می دهد، می توانید چندین سیاست را در یک FaultRule اجرا کنید:

<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 ، سیاست ExtractVariables ، خط‌مشی AssignMessage یا هر خط‌مشی دیگری در FaultRule استفاده کنید. توجه داشته باشید که پردازش FaultRule در صورت وقوع هر یک از موارد زیر بلافاصله متوقف می شود:

• هر خط مشی در FaultRule باعث خطا می شود
• هر یک از سیاست های موجود در FaultRule از نوع RaiseFault است

تعریف پیغام خطای سفارشی بازگردانده شده از یک FaultRule

به عنوان بهترین روش، باید پاسخ های خطای واضحی را از API های خود تعریف کنید. به این ترتیب، اطلاعات منسجم و مفیدی را در اختیار مشتریان خود قرار می دهید.

مثال خط مشی AssignMessage زیر از تگ های <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>

این پاسخ شامل:

• محموله حاوی پیام خطا و آدرس ایمیل برای تماس با پشتیبانی.
• کد وضعیت HTTP در پاسخ بازگردانده شد.
• عبارت دلیل که شرح کوتاهی از خطا است.

ایجاد یک DefaultFaultRule

یک DefaultFaultRule یک کنترل کننده استثنا برای هر خطایی که به صراحت توسط FaultRule دیگری کنترل نمی شود عمل می کند. اگر شرایط همه FaultRule با خطا مطابقت نداشته باشد، DefaultFaultRule خطا را کنترل می کند. با افزودن تگ <DefaultFaultRule> به عنوان یک عنصر فرزند از یک ProxyEndpoint یا یک TargetEndpoint، مدیریت پیش فرض خطا را فعال کنید.

به عنوان مثال، پیکربندی TargetEndpoint زیر یک DefaultFaultRule را تعریف می کند که یک خط مشی به نام ReturnGenericError را فراخوانی می کند:

<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 معمولاً برای بازگرداندن یک پیام خطای عمومی برای هرگونه خطای غیرمنتظره، مانند پیامی که حاوی اطلاعات تماس برای پشتیبانی فنی است، استفاده می شود. این پاسخ پیش‌فرض به هدف دوگانه ارائه اطلاعات مناسب برای توسعه‌دهنده عمل می‌کند و در عین حال نشانی‌های وب پشتیبان یا سایر اطلاعاتی را که ممکن است برای به خطر انداختن سیستم مورد استفاده قرار گیرند، مبهم می‌سازد.

به عنوان مثال، سیاست 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 همیشه آخرین فاضلاب است که اجرا می کند:

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

یکی از استفاده از پیش فرض فلفل ، تعیین نوع خطایی است که در غیر این صورت نمی توانید آن را تعیین کنید. به عنوان مثال ، پروکسی API شما برای خطایی که نمی توانید تعیین کنید ، ناکام است. برای استناد به خط مشی AssignMessage زیر از DefaultFaultrule استفاده کنید. این خط مشی مقدار 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>

سپس می توانید هدر را در ابزار Edge Trace یا در پاسخ مشاهده کنید تا ببینید چه چیزی باعث خطا شده است.

اضافه کردن ورود به سیستم به PostcleientFlow

PostcleientFlow تنها جریانی است که پس از ورود پروکسی به حالت خطا اجرا می شود. فقط خط مشی پیام پیام می تواند به این جریان متصل شود ، که پس از ارسال پاسخ به مشتری اجرا می شود. اگرچه اتصال خط مشی پیام های پیام به این جریان از لحاظ فنی خطایی نیست ، اما در صورت بروز خطا می توانید از آن برای ورود به اطلاعات استفاده کنید. از آنجا که بدون در نظر گرفتن اینکه پروکسی موفق یا شکست خورده است ، می توانید سیاست های ورود به سیستم پیام را در PostclientFlow قرار دهید و تضمین می شود که همیشه اجرا می شوند.

رسیدگی به گسلهای خط مشی در جریان فعلی

مثالهای نشان داده شده تاکنون همه از یک فاکترول در ProxyendPoint یا TargetEndPoint استفاده می کنند تا هرگونه خطای خط مشی را به عنوان بخشی از حالت خطا برطرف کنند. دلیل این امر این است که مقدار پیش فرض عنصر continueOnError یک خط مشی false است ، به این معنی که وقتی خطایی در یک خط مشی رخ می دهد ، کنترل به حالت خطا هدایت می شود. هنگامی که در حالت خطا قرار دارید ، نمی توانید کنترل را به خط لوله عادی برگردانید و به طور معمول نوعی پیام خطا را به برنامه تماس باز می گردانید.

با این حال ، اگر عنصر continueOnError را برای یک خط مشی تنظیم کنید ، کنترل در جریان فعلی باقی می ماند و خط مشی بعدی در خط لوله پس از خط مشی که باعث خطا شده است ، اجرا true شود. مزیت رسیدگی به خطا در جریان فعلی این است که شما ممکن است راهی برای بازیابی از خطا برای تکمیل پردازش درخواست داشته باشید.

نشان داده شده در زیر یک سیاست تأییدیه apikey به نام 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 را به عنوان گامی در پیش نمایش 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 می تواند بسیاری از کارها را انجام دهد ، مانند ورود به خطا ، تلاش برای رفع خطا یا انجام برخی اقدامات دیگر.

با استفاده از خط مشی RaiseFault خطایی ایجاد می کند

شما می توانید از خط مشی RaiseFault در هر زمان در یک جریان استفاده کنید تا خطایی ایجاد شود. هنگامی که یک سیاست RaiseFault اجرا می شود ، جریان فعلی را خاتمه می دهد و کنترل را به حالت خطا منتقل می کند.

یکی از استفاده از خط مشی RaiseFault آزمایش یک شرط خاص است که ممکن است سیاست دیگری تشخیص ندهد. در مثال بالا ، شما یک برچسب <Condition> را به یک برچسب preflow <Step> اضافه کردید که باعث شده است که در صورت برآورده شدن شرط ، FaultInFlow سیاست را اجرا کند. اگر FaultInFlow یک خط مشی RaiseFault است ، سپس انتقال به حالت خطا را کنترل کنید. یا ممکن است شما یک خط مشی RaiseFault را در یک جریان برای اشکال زدایی و آزمایش فاضلاب های خود وارد کنید.

هنگامی که یک خط مشی RaiseFault خطایی ایجاد می کند ، می توانید از فاکترول و شرط زیر برای پردازش آن استفاده کنید:

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

توجه داشته باشید که آزمایش شرط برای یک گسل به نام RaiseFault است. خط مشی RaiseFault همیشه مقدار fault.name را به RaiseFault تعیین می کند.

رسیدگی سفارشی کدهای خطای HTTP از سرور هدف

نمونه های نشان داده شده در بخش های قبلی در مورد خطاهای ایجاد شده توسط سیاست ها اعمال می شود. با این حال شما همچنین می توانید یک پاسخ سفارشی برای خطاهای سطح حمل و نقل ایجاد کنید ، به این معنی که خطاهای HTTP از سرور هدف بازگردانده می شود. برای کنترل پاسخ از یک خطای HTTP ، یک نقطه هدف را برای پردازش کدهای پاسخ HTTP پیکربندی کنید.

به طور پیش فرض ، Edge کدهای پاسخ HTTP را در محدوده 1xx-3xx به عنوان "موفقیت" و کدهای پاسخ HTTP در محدوده 4xx-5xx به عنوان "شکست" درمان می کند. این بدان معناست که هرگونه پاسخ از سرویس باطن با کد پاسخ HTTP 4XX-5XX به طور خودکار حالت خطا را فراخوانی می کند ، که سپس یک پیام خطا را مستقیماً به مشتری درخواست کننده باز می گرداند.

می توانید برای هر کد پاسخ HTTP ، دستگیرنده های سفارشی ایجاد کنید. به عنوان مثال ، شما ممکن است بخواهید تمام کدهای پاسخ HTTP را در محدوده 4xx-5xx به عنوان "شکست" اما فقط 5xx درمان کنید ، یا ممکن است بخواهید پیام های خطای سفارشی را برای کدهای پاسخ HTTP 400 و 500 برگردانید.

در مثال بعدی ، شما از ویژگی Success.codes برای پیکربندی TargetEndPoint برای درمان کدهای پاسخ HTTP 400 و 500 به عنوان موفقیت استفاده می کنید ، به همراه کدهای پیش فرض 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>

همانطور که در این مثال مشاهده می کنید ، می توانید از Wildcards برای تنظیم موفقیت استفاده کنید. ویژگی های کد را به طیف وسیعی از مقادیر ..

تنظیم Success.Codes Properties مقادیر پیش فرض را بازنویسی می کند. بنابراین ، اگر می خواهید کد HTTP 400 را به لیست کدهای موفقیت پیش فرض اضافه کنید ، این ویژگی را به صورت: تنظیم کنید:

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

اما ، اگر فقط می خواهید HTTP Code 400 به عنوان یک کد موفقیت رفتار شود ، این ویژگی را به صورت: تنظیم کنید:

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

هم اکنون می توانید دستگیرندگان سفارشی را برای کدهای پاسخ HTTP 400 و 500 تعریف کنید تا یک پیام پاسخ سفارشی را به برنامه درخواست کننده برگردانید. 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 با کد پاسخ HTTP 400 یا 500 روبرو شود ، پاسخ را کنترل کند.

طبقه بندی گسسته

خدمات API گسل ها را در دسته ها و زیر شاخه های زیر سازماندهی می کند.

یک خطا همیشه با توضیحات متن دلیل عدم موفقیت همراه است. هنگامی که سیستم یک خطا را ایجاد می کند ، مجموعه ای از ویژگی ها برای کمک به عیب یابی جمع می شوند. یک خطا شامل اطلاعات زیر است:

• دلیل
• ویژگی های سفارشی تعریف شده توسط کاربر