سياسة RaiseFault

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

الأدوات المستخدمة

تنشئ هذه السمة رسالة مخصّصة استجابةً لحالة خطأ. استخدِم 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، يتم نقل عنصر التحكّم من التدفق الحالي إلى تدفق Error، الذي يعرض بعد ذلك استجابة الخطأ المحدّدة إلى تطبيق العميل الذي أرسل الطلب. وعندما ينتقل تدفق الرسائل إلى تدفق Error، لا تتم معالجة أي سياسات أخرى. يتم تخطّي جميع خطوات المعالجة المتبقية، ويتم عرض استجابة الخطأ مباشرةً للتطبيق الذي أرسل الطلب.

يمكنك استخدام 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">

يصف الجدول التالي السمات المشتركة بين جميع العناصر الرئيسية للسياسة:

&lt;DisplayName&gt; عنصر

استخدِمه مع السمة 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 لضبط عنوان في استجابة الخطأ:

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

أو، اعتبارًا من الإصدار السحابي 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. لمزيد من المعلومات عن متغيرات Flow، يُرجى الاطّلاع على مرجع المتغيرات.

مثال على استخدام 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.

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

يُرجى الاطّلاع على التعامل مع الأخطاء.