خط مشی RaiseFault

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

چه

یک پیام سفارشی در پاسخ به یک وضعیت خطا تولید می‌کند. از RaiseFault برای تعریف یک پاسخ خطا استفاده کنید که در صورت بروز یک وضعیت خاص به برنامه درخواست‌کننده بازگردانده می‌شود.

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

نمونه‌ها

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

درباره سیاست RaiseFault

Apigee Edge شما را قادر می‌سازد تا با استفاده از یک سیاست از نوع RaiseFault، مدیریت خطای سفارشی را انجام دهید. سیاست RaiseFault که مشابه سیاست AssignMessage است، به شما امکان می‌دهد در پاسخ به یک وضعیت خطا، یک پاسخ خطای سفارشی ایجاد کنید.

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

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

شما می‌توانید از RaiseFault در یک ProxyEndpoint یا یک TargetEndpoint استفاده کنید. معمولاً، شما یک Condition را به سیاست RaiseFault پیوست می‌کنید. پس از اجرای RaiseFault، Apigee پردازش خطای معمولی را انجام می‌دهد، FaultRules را ارزیابی می‌کند، یا اگر هیچ قانون خطایی تعریف نشده باشد، پردازش درخواست را خاتمه می‌دهد.

مرجع عنصر

مرجع عنصر، عناصر و ویژگی‌های سیاست RaiseFault را توصیف می‌کند.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

ویژگی‌های <RaiseFault>

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>

عنصر <نادیده گرفتن متغیرهای حل نشده>

(اختیاری) هرگونه خطای متغیر حل نشده در Flow را نادیده می‌گیرد. مقادیر معتبر: true/false. مقدار پیش‌فرض true .

عنصر <FaultResponse>

(اختیاری) پیام پاسخی را که به کلاینت درخواست‌کننده برگردانده می‌شود، تعریف می‌کند. FaultResponse از همان تنظیمات سیاست AssignMessage استفاده می‌کند (در Apigee Edge برای Private Cloud در دسترس نیست).

عنصر <FaultResponse><AssignVariable>

مقداری را به متغیر جریان مقصد اختصاص می‌دهد. اگر متغیر جریان وجود نداشته باشد، AssignVariable آن را ایجاد می‌کند.

برای مثال، از کد زیر برای تنظیم متغیری به نام myFaultVar در سیاست RaiseFault استفاده کنید:

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

سپس می‌توانید بعداً در قالب‌های پیام در سیاست RaiseFault به آن متغیر ارجاع دهید. همچنین، یک سیاست متصل به یک FaultRule می‌تواند به متغیر دسترسی پیدا کند. برای مثال، سیاست AssignMessage زیر از متغیر تنظیم شده در RaiseFault برای تنظیم یک Header در پاسخ خطا استفاده می‌کند:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> در سیاست RaiseFault از همان سینتکس عنصر <AssignVariable> در سیاست AssignMessage استفاده می‌کند. توجه داشته باشید که این قابلیت در حال حاضر در Apigee Edge برای Private Cloud در دسترس نیست.

عنصر <FaultResponse><Add>/<Headers>

هدرهای HTTP را به پیام خطا اضافه می‌کند. توجه داشته باشید که هدر خالی <Add><Headers/></Add> هیچ هدری اضافه نمی‌کند. این مثال مقدار متغیر جریان request.user.agent را در هدر کپی می‌کند.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

عنصر <FaultResponse><Copy>

اطلاعات را از پیام مشخص شده توسط ویژگی source به پیام خطا کپی می‌کند.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
        <ReasonPhrase/>
    </Copy>

ویژگی‌ها

 <Copy source="response">

عنصر <FaultResponse><Copy>/<Headers>

هدر HTTP مشخص شده را از منبع به پیام خطا کپی می‌کند. برای کپی کردن همه هدرها، <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>      
        <Header name="headerName"/>
    </Headers> 
</Copy>

اگر چندین هدر با نام یکسان وجود دارد، از سینتکس زیر استفاده کنید:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

این مثال "h1"، "h2" و مقدار دوم "h3" را کپی می‌کند. اگر "h3" فقط یک مقدار داشته باشد، کپی نمی‌شود.

عنصر <FaultResponse><Copy>/<StatusCode>

کد وضعیت HTTP که باید از شیء مشخص شده توسط ویژگی منبع به پیام خطا کپی شود.

<Copy source='response'>
    <StatusCode>404</StatusCode>      
</Copy>

عنصر <FaultResponse><Copy>/<ReasonPhrase>

توضیح دلیل کپی کردن از شیء مشخص شده توسط ویژگی منبع به پیام خطا.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

عنصر <FaultResponse><Remove>/<Headers>

هدرهای HTTP مشخص شده را از پیام خطا حذف می‌کند. برای حذف همه هدرها، <Remove><Headers/></Remove> را مشخص کنید. این مثال هدر user-agent را از پیام حذف می‌کند.

<Remove>     
    <Headers>      
        <Header name="user-agent"/>     
    </Headers> 
</Remove>

اگر چندین هدر با نام یکسان وجود دارد، از سینتکس زیر استفاده کنید:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

این مثال "h1"، "h2" و مقدار دوم "h3" را حذف می‌کند. اگر "h3" فقط یک مقدار داشته باشد، حذف نمی‌شود.

عنصر <FaultResponse><Set>

اطلاعات را در پیام خطا تنظیم می‌کند.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
        <ReasonPhrase/>
    </Set>

عنصر <FaultResponse>/<Set>/<Headers>

هدرهای HTTP را در پیام خطا تنظیم یا بازنویسی می‌کند. توجه داشته باشید که هدر خالی <Set><Headers/></Set> هیچ هدری را تنظیم نمی‌کند. این مثال هدر user-agent را روی متغیر message که با عنصر <AssignTo> مشخص شده است، تنظیم می‌کند.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>     
    </Headers>
</Set>

عنصر <FaultResponse>/<Set>/<Payload>

میزان بار مفید پیام خطا را تنظیم می‌کند.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

یک payload از نوع JSON تنظیم کنید:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

در یک JSON payload، می‌توانید متغیرها را با استفاده از ویژگی‌های variablePrefix و variableSuffix با کاراکترهای جداکننده، همانطور که در مثال زیر نشان داده شده است، وارد کنید.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

یا، از نسخه ابری ۱۶.۰۸.۱۷، می‌توانید برای وارد کردن متغیرها از آکولاد نیز استفاده کنید:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

تنظیم یک payload ترکیبی در XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

ویژگی‌ها

 
<Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

عنصر <FaultResponse>/<Set>/<StatusCode>

کد وضعیت پاسخ را تنظیم می‌کند.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

عنصر <FaultResponse>/<Set>/<ReasonPhrase>

عبارت دلیل پاسخ را تنظیم می‌کند.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

عنصر <ShortFaultReason>

مشخص می‌کند که دلیل خطای کوتاهی در پاسخ نمایش داده شود:

<ShortFaultReason>true|false</ShortFaultReason>

به طور پیش‌فرض، دلیل خطا در پاسخ سیاست عبارت است از:

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

برای خواناتر کردن پیام، می‌توانید عنصر <ShortFaultReason> را روی true تنظیم کنید تا faultstring فقط به نام سیاست خلاصه شود:

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

مقادیر معتبر: درست/نادرست (پیش‌فرض).

متغیرهای جریان

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

مثال استفاده از RaiseFault

مثال زیر از یک شرط برای اعمال شرط وجود یک queryparam با نام zipcode در درخواست ورودی استفاده می‌کند. اگر آن queryparam وجود نداشته باشد، جریان از طریق RaiseFault خطایی ایجاد می‌کند:

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>

<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

خطاهای استقرار

هیچ کدام

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که یک خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.

نمونه پاسخ خطا

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

طرحواره

هر نوع سیاست توسط یک طرح XML ( .xsd ) تعریف می‌شود. برای مرجع، طرح‌های سیاست در GitHub موجود است.

مباحث مرتبط

به مدیریت خطاها مراجعه کنید