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

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

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

می‌توانید از RaiseFault در ProxyEndpoint یا TargetEndpoint استفاده کنید. معمولاً، یک شرط را به خط‌مشی 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.

عنصر <FaultResponse>

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

عنصر <FaultResponse><AssignVariable>

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

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

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

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

<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 برای «ابر خصوصی» دردسترس نیست.

عنصر <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>

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

<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> را روی درست تنظیم کنید تا faultstring به نام خط‌مشی کوتاه شود:

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

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

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

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

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

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

<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 دردسترس است.

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

دیدن رسیدگی به خطاها