خط مشی 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>

عنصر <IgnoreUnresolvedVariables>

(اختیاری) هرگونه خطای متغیر حل نشده در جریان را نادیده می گیرد. مقادیر معتبر: 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 را با متغیر پیام مشخص شده با عنصر <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>

یک بار JSON را تنظیم کنید:

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

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

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

یا از انتشار ابری 16.08.17، همچنین می‌توانید برای درج متغیرها، بریس‌های فرفری درج کنید:

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

یک بار مختلط را در 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"}}}

مقادیر معتبر: true/false (پیش فرض).

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

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

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

مثال زیر از یک Condition برای اعمال یک 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 در دسترس هستند.

موضوعات مرتبط

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