مدیریت کردن خطاها

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

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

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

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

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

ویدیوها

برای کسب اطلاعات بیشتر درباره مدیریت خطا، ویدیوهای زیر را تماشا کنید.

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

نحوه وقوع خطاها

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

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

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

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

برای کسب اطلاعات بیشتر درباره این خطاها، رده‌بندی خطا را در این موضوع ببینید.

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

برای موقعیت‌هایی که خطای خودکار وجود ندارد، ممکن است بخواهید خطای سفارشی ایجاد کنید؛ برای مثال، اگر پاسخ حاوی کلمه «دردسترس نیست» باشد، یا اگر کد وضعیت HTTP بزرگ‌تر از ۲۰۱ باشد. این کار را با افزودن خط‌مشی 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 ببینید:

کارگزاران نیابتی API هنگام بروز خطا چه می‌کنند

در اینجا آنچه هنگام بروز خطا در پراکسی اتفاق می‌افتد آورده شده است.

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

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

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

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

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

بررسی FaultRules

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

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

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

به‌عنوان توسعه‌دهنده «میانای برنامه‌سازی کاربردی»، این شما هستید که باید این پیام را تغییر دهید تا نیازهای هر کسی که درنهایت پیام خطا را دریافت می‌کند برآورده شود، خواه توسعه‌دهنده برنامه iOS باشد یا گروه آزمایش داخلی که الزامات قالب پیام خطای خود را دارد.

در اینجا یک مثال ساده از نحوه ایجاد پیام خطای سفارشی برای مدیریت این خطا آورده شده است. این کار به ۱) خط‌مشی‌ای که پیام سفارشی را تعریف می‌کند و ۲) «قانون خطا» که خط‌مشی را وقتی پراکسی به حالت خطا می‌رود اجرا می‌کند نیاز دارد.

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

ابتدا خط‌مشی‌ای بسازید که پیام خطای سفارشی را تعریف کند. می‌توانید از هر نوع خط‌مشی‌ای، مثل خط‌مشی AssignMessage، استفاده کنید که می‌تواند بار و سرصفحه‌های اختیاری HTTP مثل کد وضعیت و عبارت دلیل را تنظیم کند. «اختصاص پیام» برای این کار ایده‌آل است. این ویژگی به شما امکان می‌دهد محتوای پیام را کنترل کنید، کد وضعیت HTTP متفاوتی تنظیم کنید، عبارت دلیل HTTP متفاوتی تنظیم کنید، و سراینده‌های HTTP اضافه کنید.

خط‌مشی را به هیچ جریانی در پراکسی API پیوست نکنید. کافی است که در بسته پراکسی وجود داشته باشد. برای انجام این کار در ویرایشگر پراکسی میانای کاربری مدیریت، به برگه «توسعه» بروید و در «پانل پیمایش» روی نماد + در نوار «خط‌مشی‌ها» کلیک کنید.

این کار به شما امکان می‌دهد بدون پیوست کردن خط‌مشی به جاری‌سازی در پراکسی API، خط‌مشی ایجاد کنید. خط‌مشی‌ای که به هیچ جریانی پیوست نشده باشد با نماد «جداشده» در فهرست «خط‌مشی‌ها» نشان‌گذاری می‌شود، همان‌طور که در کنار خط‌مشی پیام کلید API در شکل قبلی نشان داده شده است.

در زیر نمونه‌ای از خط‌مشی AssignMessage آمده است که:

  • پیام JSON برمی‌گرداند.
  • یک کد وضعیت HTTP (۹۱۱، که یک کد وضعیت غیرموجود آشکار است، صرفاً برای نشان دادن انعطاف‌پذیری شما) تنظیم می‌کند. کد وضعیت در سرصفحه 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 را به‌عنوان پارامتر پُرسمان اضافه کند.

اما این خط‌مشی چگونه اجرا می‌شود؟ بخش بعدی به شما نشان می‌دهد.

۲. ایجاد <FaultRule> که خط‌مشی را راه‌اندازی می‌کند

در بخش‌های <ProxyEndpoint> یا <TargetEndpoint> پیکربندی پراکسی، یک بلوک <FaultRules> XML اضافه می‌کنید که حاوی یک یا چند بخش <FaultRule> است. هر FaultRule نشان‌دهنده خطای متفاوتی است که می‌خواهید آن را مدیریت کنید. در این مثال ساده، فقط از یک FaultRule استفاده می‌کنیم تا به شما نشان دهیم از چه چیزی تشکیل شده است.

همچنین باید <DefaultFaultRule> را اضافه کنید تا اگر هیچ‌یک از «قوانین خطا» شما اجرا نشد، پیام خطای عمومی سفارشی ارائه شود.

مثال

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

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

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

چندین «قانون خطا» و منطق اجرا

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

این بخش منطقی را که Edge در مدیریت FaultRules استفاده می‌کند، از نحوه رسیدن به یک 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 را که شرط آن درست است اجرا می‌کند. اگر یک FaultRule شرطی نداشته باشد، به‌طور پیش‌فرض درست است.
    • وقتی FaultRule اجرا می‌شود، همه «مراحل» درون FaultRule به‌ترتیب، از بالا به پایین در پیکربندی XML ارزیابی می‌شوند. مراحل بدون شرط به‌طور خودکار اجرا می‌شوند (خط‌مشی‌ها اجرا می‌شوند) و مراحلی که <Condition> دارند و به «درست» ارزیابی می‌شوند اجرا می‌شوند (شرایطی که به «نادرست» ارزیابی می‌شوند اجرا نمی‌شوند).
    • اگر FaultRule اجرا شود، اما هیچ‌کدام از «مراحل» در FaultRule اجرا نشود (زیرا شرایط آن‌ها به «نادرست» ارزیابی می‌شود)، پیام خطای پیش‌فرض تولیدشده توسط Edge به برنامه مشتری برگردانده می‌شود. <DefaultFaultRule> اجرا نمی‌شود، زیرا Edge قبلاً FaultRule خود را اجرا کرده است.

  3. اگر هیچ FaultRule اجرا نشود، Edge <DefaultFaultRule> را درصورت وجود اجرا می‌کند.

در زیر نمونه‌هایی با نظرات درون‌خطی آورده شده است.

اجرای ProxyEndpoint

ارزیابی «قوانین خطای» ProxyEndpoint از پایین به بالا است، بنابراین خواندن را از آخرین «قانون خطا» در نمونه زیر شروع کنید و به بالا بروید. «قانون خطای پیش‌فرض» را در آخر بررسی کنید.

<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 از بالا به پایین است، بنابراین خواندن را از اولین FaultRule در نمونه زیر شروع کنید و به پایین بروید. «قانون خطای پیش‌فرض» را در آخر بررسی کنید.

<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، مهم است.

برای مثال:

ترتیب ProxyEndpoint ترتیب TargetEndpoint

در مثال زیر، چون ارزیابی از پایین به بالا است، FaultRule 3 اجرا می‌شود، که یعنی FaultRules 2 و 1 ارزیابی نمی‌شوند.

۵. FaultRule 1: FALSE

۴. FaultRule 2: TRUE

۳. FaultRule 3: TRUE

۲. FaultRule 4: FALSE

۱. FaultRule: 5 FALSE

در مثال زیر، چون ارزیابی از بالا به پایین است، FaultRule 2 اجرا می‌شود، که یعنی FaultRules 3،‏ 4، و 5 ارزیابی نمی‌شوند.

۱. FaultRule 1: FALSE

۲. FaultRule 2: TRUE

۳. ‫FaultRule 3: TRUE

۴. FaultRule 4: FALSE

۵. FaultRule: 5 FALSE

خط‌مشی‌های موردنظر برای افزودن

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

قوانین خطا فقط در وضعیت خطا راه‌اندازی می‌شوند (درباره continueOnError)

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

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

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

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

کجا برای تعریف FaultRules: ProxyEndpoint یا TargetEndpoint

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

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

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

قوانین خطا دربرابر خط‌مشی RaiseFault

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

به‌طور خلاصه:

  • وقتی کارگزار نیابتی API وارد وضعیت خطا می‌شود، قوانین خطا همیشه ارزیابی می‌شوند.
  • خط‌مشی RaiseFault روشی برای قرار دادن کارگزار پراکسی API در وضعیت خطا است وقتی خطایی رخ نمی‌دهد.

    برای مثال، اگر می‌خواهید درصورتی‌که کد وضعیت HTTP در پاسخ سرویس هدف بزرگ‌تر از ۲۰۰ باشد خطا ایجاد شود، خط‌مشی 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 برنده است.
  • اگر داده‌های پاسخ خطامطرح‌شده (کد وضعیت، عبارت دلیل، یا محتوای پیام) توسط 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

<- خط‌مشی RaiseFault این را تنظیم می‌کند:

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

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

دیگر متغیرهای دردسترس

وقتی پراکسی API به وضعیت خطا می‌رود، تنها متغیرهای دردسترس برای استفاده در شرایط عبارت‌اند از:

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

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

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

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

روال‌های مطلوب برای مدیریت خطا

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

در زیر، برخی‌از روال‌های مطلوب در طراحی و ساخت مدیریت خطا آورده شده است:

  • برای هر FaultRule، یک <Condition> «بیرونی» (هم‌سطح با عنصر <Step>) ارائه دهید. قانون‌های خطایی که وضعیت بیرونی ندارند به‌طور خودکار به درست ارزیابی می‌شوند. از شرایط مرحله «درونی» برای تعیین اینکه آیا یک FaultRule درست است یا نادرست استفاده نمی‌شود. شرایط مرحله فقط پس‌از اینکه Edge «قانون خطا» حاوی آن‌ها را اجرا کرد ارزیابی می‌شود. در FaultRule، معمولاً چندین «مرحله» با خط‌مشی‌های «اختصاص پیام» (یا خط‌مشی‌های دیگر) وجود دارد، که هرکدام وضعیت «مرحله» دارند.
  • برای مدیریت خطاها در چندین خط‌مشی از یک نوع (برای مثال، چندین خط‌مشی «سهمیه» )، برای هر خطای خط‌مشی که احتمالاً دریافت می‌کنید یک FaultRule ایجاد کنید. برای مثال، برای هر خطای احتمالی در خط‌مشی‌های «سهمیه»، مثل QuotaViolation،‏ InvalidMessageWeight، StartTimeNotSupported، یک FaultRule ایجاد کنید. (برای خطاهای خط‌مشی، مرجع خطای خط‌مشی را ببینید. وقتی خطاهای بیشتری را که باید مدیریت شوند کشف کردید، می‌توانید بعداً برگردید و آن‌ها را به FaultRules اضافه کنید. تکرار کردن اشکالی ندارد، هرچند که به استقرار مجدد پراکسی نیاز دارد.) این رویکرد به شما امکان می‌دهد که نوع یکسانی از خطا را صرف‌نظر از اینکه کدام خط‌مشی آن را ایجاد می‌کند، شناسایی کنید، که این امر باعث کارآمدی XML «قوانین خطا» می‌شود.

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

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

    <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>
  • «قوانین خطا» را در جایی که خطاها رخ می‌دهند (سمت کارخواه <ProxyEndpoint> یا سمت هدف <TargetEndpoint>) اضافه کنید. «قوانین خطا» را برای هر خط‌مشی که در هر مکان ظاهر می‌شود اضافه کنید.
  • در FaultRules، می‌توانید هر نوع خط‌مشی‌ای را که می‌تواند پیامی را به برنامه کارخواه برگرداند اجرا کنید. خط‌مشی AssignMessage برای این کار ایده‌آل است. همچنین اگر می‌خواهید خطاها را پیگیری کنید، پیامی را با خط‌مشی MessageLogging ثبت کنید.
  • وقتی از خط‌مشی‌های RaiseFault به‌همراه FaultRules استفاده می‌کنید، داده‌های پاسخی را که وقتی هم خط‌مشی RaiseFault و هم FaultRule داده برمی‌گردانند هماهنگ کنید. برای مثال، اگر خط‌مشی RaiseFault شما کد وضعیت HTTP را بازنشانی می‌کند، اجازه ندهید FaultRule کد وضعیت را بازنشانی کند. بدترین اتفاقی که ممکن است بیفتد این است که کد وضعیت پیش‌فرض به برنامه کارخواه برگردانده شود.
  • ‫<DefaultFaultRule> اجرا:
    • وقتی هیچ FaultRule دیگری اجرا نمی‌شود، <DefaultFaultRule> به‌طور خودکار اجرا می‌شود. عنصر فرزند <Condition> سطح قانون را در <DefaultFaultRule> اضافه نکنید. برای اجرای شرطی خط‌مشی در داخل <DefaultFaultRule>، <Condition> را روی عنصر فرزند <Step> آن قرار دهید.
    • اگر می‌خواهید <DefaultFaultRule> همیشه اجرا شود حتی وقتی «قانون خطا» دیگری اجرا شده است، عنصر فرزند <AlwaysEnforce>true</AlwaysEnforce> را اضافه کنید.

الگوی مدیریت خطای متمرکز و بازکاربردپذیر

پست زیر در «انجمن Apigee» الگویی برای مدیریت خطای متمرکز بدون تکرار کد را شرح می‌دهد:

الگوی مدیریت خطا برای پراکسی‌های Apigee

درحال ایجاد FaultRules

برای افزودن FaultRule باید پیکربندی زبان نشانه‌گذاری توسعه‌پذیر ProxyEndpoint یا TargetEndpoint را ویرایش کنید. می‌توانید از «میانای کاربر Edge» برای انجام این ویرایش در قاب کد نمای توسعه برای پراکسی 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

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

مثال خط‌مشی 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>

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

برای مثال، خط‌مشی 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 name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

یکی از کاربردهای DefaultFaultRule تعیین نوع خطایی است که وقتی نمی‌توانید آن را تعیین کنید رخ می‌دهد. برای مثال، کارگزار نیابتی 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>

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

افزودن گزارش پیام به PostClientFlow

PostClientFlow تنها جریانی است که پس‌از ورود پراکسی به حالت خطا اجرا می‌شود. فقط خط‌مشی MessageLogging می‌تواند به این جریان پیوست شود، که پس‌از ارسال پاسخ به کارخواه اجرا می‌شود. اگرچه پیوست کردن خط‌مشی MessageLogging به این جریان ازنظر فنی مدیریت خطا نیست، می‌توانید از آن برای ثبت اطلاعات درصورت بروز خطا استفاده کنید. ازآنجایی‌که این خط‌مشی بدون توجه به موفقیت یا عدم موفقیت پراکسی اجرا می‌شود، می‌توانید خط‌مشی‌های «گزارش‌گیری پیام» را در PostClientFlow قرار دهید و مطمئن باشید که همیشه اجرا می‌شوند.

رسیدگی به خطاهای خط‌مشی در جریان کنونی

مثال‌هایی که تاکنون نشان داده شده است، همه از FaultRule در 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>

توجه کنید که چگونه مرحله بعدی در «جریان پیش‌از اجرا» از شرطی برای آزمایش وجود خطا استفاده می‌کند. اگر خطایی در خط‌مشی VerifAPIKey رخ دهد، خط‌مشی با نام FaultInFlow خط‌مشی اجرا می‌شود. درغیراین‌صورت، خط‌مشی FaultInFlow رد می‌شود. خط‌مشی FaultInFlow می‌تواند کارهای زیادی انجام دهد، مثلاً خطا را ثبت کند، سعی کند خطا را برطرف کند، یا اقدام دیگری انجام دهد.

راه‌اندازی خطا بااستفاده از خط‌مشی RaiseFault

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

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

وقتی خط‌مشی RaiseFault باعث بروز خطا می‌شود، می‌توانید از FaultRule و شرط زیر برای پردازش آن استفاده کنید:

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

توجه داشته باشید که وضعیت برای خطایی به‌نام RaiseFault آزمایش می‌کند. خطمشی RaiseFault همیشه مقدار fault.name را روی RaiseFault تنظیم می‌کند.

مدیریت سفارشی کدهای خطای HTTP از سرور مقصد

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

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

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

در مثال بعدی، از دارایی success.codes برای پیکربندی «نقطه پایانی هدف» استفاده می‌کنید تا کدهای پاسخ 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>

همان‌طور که در این مثال می‌بینید، می‌توانید از نویسه‌های عام برای تنظیم دارایی success.codes روی محدوده‌ای از مقادیر استفاده کنید.

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

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

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

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

اکنون می‌توانید کارگزارهای سفارشی را برای کدهای پاسخ HTTP 400 و 500 تعریف کنید تا پیام پاسخ سفارشی‌شده‌ای به برنامه درخواست‌کننده برگردانند. «نقطه پایانی هدف» زیر از خط‌مشی‌ای به نام 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» خطاها را در دسته‌ها و زیردسته‌های زیر سازمان‌دهی می‌کند.

دسته مقوله فرعی نام خطا شرح
پیام‌رسانی خطاهایی که درطول جریان پیام رخ می‌دهند (شامل خطاهای خط‌مشی نمی‌شود)
خطاهای سفارشی {fault_name} هرگونه خطایی که توسط پراکسی API بااستفاده از خط‌مشی RaiseFault به‌طور صریح مدیریت می‌شود
کدهای پاسخ InternalServerError،‏ NotFound کدهای خطای HTTP 5xx،‏ 4xx
خطاهای مسیریابی NoRoutesMatched خطا در انتخاب «نقطه پایانی هدف» نام‌گذاری‌شده برای درخواست
خطاهای طبقه‌بندی NotFound خطاهایی که به‌دلیل عدم تطابق نشانی وب درخواست با هریک از پیکربندی‌های BasePath برای هریک از ProxyEndpoint رخ می‌دهد (یعنی هیچ‌یک از پراکسی‌های API با نشانی وب در درخواست برنامه کلاینت مطابقت ندارد)
حمل‌ونقل خطاهای سطح انتقال HTTP
اتصال‌پذیری ConnectionRefused،‏ ConnectionReset،‏ ConnectionTimeout هنگام ایجاد اتصال‌های سطح شبکه یا انتقال، خرابی رخ می‌دهد
درخواست اعتبارسنجی ContentLengthMissing, HostHeaderMissing خطاها درطول بررسی معناشناسی در هر درخواست رخ می‌دهد
اعتبارسنجی‌های پاسخ خطاها درحین بررسی معناشناسی در هر پاسخ رخ می‌دهد
خطاهای ورودی/خروجی SSLHandshakeError،‏ ReadTimeout،‏ ReadError،‏ WriteTimeout،‏ WriteError،‏ ChunkError خطاهای خواندن/نوشتن در نقاط پایانی کارخواه یا هدف، زمان‌های اتمام، خطاهای TLS/SSL، و خطاهای تکه‌تکه
سیستم خطاهای زمان اجرای تعریف‌نشده
حافظه OutOfMemory،‏ GCOverLimit خطاهای مربوط به حافظه
نخ RogueTaskTerminated خطاهایی مانند پایان دادن به تکالیف فراری
خط‌مشی خطاها برای هر نوع «خط‌مشی» در مرجع خط‌مشی تعریف شده است.

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

  • استدلال
  • مشخصه‌های سفارشی تعریف‌شده توسط کاربر