سياسة RaiseFault

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. المعلومات

الموضوع

تنشئ رسالة مخصّصة ردًا على حالة خطأ. ويمكنك استخدام riseFault لتحديد الاستجابة لخطأ يتم إرجاعه إلى التطبيق صاحب الطلب عند ظهور حالة معينة.

للحصول على معلومات عامة عن معالجة الأخطاء، يُرجى الاطّلاع على أخطاء المعالجة.

عيّنات

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

لمحة عن سياسة riseFault

يتيح لك Apigee Edge تنفيذ معالجة الاستثناء المخصّصة باستخدام سياسة من النوع riseFault. تتيح لك سياسة ClaimFault مماثلة لسياسة AssignMessage إمكانية إنشاء استجابة مخصّصة لخطأ معيّن استجابةً لحالة خطأ.

استخدِم سياسة GrowFault لتحديد الاستجابة لخطأ معيّن والتي يتم إرجاعها إلى التطبيق مقدّم الطلب عند ظهور حالة خطأ معيّنة. ويمكن أن تتكون استجابة الخطأ من عناوين HTTP ومَعلمات طلب البحث وحمولة الرسالة. يمكن أن تكون الاستجابة الخاصة بالأخطاء المخصّصة أكثر فائدة لمطوِّري التطبيقات ومستخدمي التطبيقات من رسائل الخطأ العامة أو رموز استجابة HTTP.

عند تنفيذها، تنقل سياسة riseFault عنصر التحكّم من التدفق الحالي إلى تدفق الخطأ، الذي يعرض بعد ذلك الاستجابة المحددة للخطأ لتطبيق العميل مقدّم الطلب. وعندما ينتقل تدفق الرسالة إلى مسار الخطأ، لا يتم إجراء أي معالجة أخرى للسياسة. يتم تجاوز جميع خطوات المعالجة المتبقية، ويتم إرجاع الاستجابة للخطأ مباشرةً إلى التطبيق الذي قدّم الطلب.

يمكنك استخدام riseFault في ProxyEndpoint أو TargetEndpoint يتم عادةً إرفاق شرط بسياسة LiftFault. بعد تنفيذ KeepFault، ستُجري Apigee معالجة للأخطاء بشكل طبيعي، وتقيّم قواعد FaultRules. وإذا لم تكن هناك قواعد خطأ محددة، تنهي معالجة الطلب.

مرجع العنصر

يصف مرجع العنصر عناصر وسمات سياسة ReceivedFault.

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

سمات <LetFault>

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

يوضِّح الجدول التالي السمات الشائعة لجميع العناصر الرئيسية للسياسة:

العنصر <DisplayName>

استخدِم هذه السمة بالإضافة إلى السمة name لتصنيف السياسة في محرِّر الخادم الوكيل لواجهة المستخدم الإدارية باستخدام اسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>

عنصر <تجاهلUnresolvedVariables>

(اختياري) يتجاهل أي خطأ متغير لم يتم حله في التدفق. القيم الصالحة: صحيح/خطأ. true التلقائي.

عنصر <FaultResponse>

(اختياري) تحدِّد رسالة الرد التي يتم عرضها للعميل الذي يقدم الطلب. تستخدم ميزة FaultResponse الإعدادات نفسها المستخدمة في سياسة تعيينMessage (غير متوفرة في Apigee Edge for Private Cloud).

العنصر <FaultResponse><AssignVariable>

تحدِّد قيمة لمتغيّر تدفق الوجهة. في حال عدم توفّر متغيّر التدفق، سيتم إنشاؤه من خلال AssignVariable.

على سبيل المثال، استخدِم الرمز التالي لضبط المتغيّر المسمى myFaultVar في سياسة ClaimFault:

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

ويمكنك بعد ذلك الرجوع إلى هذا المتغيّر في نماذج الرسائل لاحقًا في سياسة AcceleratedFault. ويمكن أيضًا لإحدى السياسات المرفقة بـ FaultRule الوصول إلى المتغيّر. على سبيل المثال، تستخدم سياسة AssignMessage التالية المتغيّر المعيّن في DrawFault لضبط عنوان في الاستجابة للخطأ:

<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> في سياسة riseFault بنية العنصر <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>/<reasonResult>

وصف السبب المطلوب نسخه من العنصر المحدّد من خلال سمة المصدر إلى رسالة الخطأ.

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

لضبط عبارة السبب للردّ

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

القيم الصالحة: صحيح/خطأ(تلقائي)

متغيرات التدفق

تعمل متغيرات التدفق على تفعيل السلوك الديناميكي للسياسات والمسارات في وقت التشغيل، استنادًا إلى عناوين HTTP أو محتوى الرسالة أو سياق التدفق. تتوفر متغيّرات التدفق المحدّدة مسبقًا التالية بعد تنفيذ سياسة ikeFault. لمزيد من المعلومات عن متغيّرات التدفق، يُرجى الاطّلاع على مرجع المتغيرات.

مثال على استخدام riseFault

يستخدم المثال التالي شرطًا لفرض توفُّر queryparam باسم zipcode في الطلب الوارد. في حال عدم توفّر السمة queryparam، سينتج عن المسار حدوث خطأ من خلال riseFault:

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

مواضيع ذات صلة

يُرجى الاطّلاع على أخطاء المناولة.