นโยบาย 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 จะโอนการควบคุมจากโฟลว์ปัจจุบันไปยังโฟลว์ข้อผิดพลาด ซึ่งจะส่งการตอบกลับข้อผิดพลาดที่กำหนดไปยังแอปไคลเอ็นต์ที่ส่งคำขอ เมื่อโฟลว์ข้อความเปลี่ยนเป็นโฟลว์ข้อผิดพลาด จะไม่มีการประมวลผลนโยบายเพิ่มเติม ระบบจะข้ามขั้นตอนการประมวลผลที่เหลือทั้งหมด และจะส่งกลับการตอบสนองของข้อผิดพลาดไปยังแอปที่ส่งคำขอโดยตรง

คุณสามารถใช้ RaiseFault ใน ProxyEndpoint หรือ TargetEndpoint โดยปกติแล้ว คุณจะแนบเงื่อนไขไว้กับนโยบาย RaiseFault หลังจากเรียกใช้ RaiseFault แล้ว Apigee จะทำการประมวลผลข้อผิดพลาดตามปกติ, ประเมิน Fault Rules หรือหากไม่มีการกำหนดกฎข้อผิดพลาดไว้ Apigee จะยุติการประมวลผลคำขอ

การอ้างอิงองค์ประกอบ

การอ้างอิงองค์ประกอบจะอธิบายองค์ประกอบและแอตทริบิวต์ของนโยบาย 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 เพื่อติดป้ายกำกับนโยบายในเครื่องมือแก้ไขพร็อกซี UI การจัดการด้วยชื่อที่เป็นภาษาธรรมชาติที่แตกต่างออกไป

<DisplayName>Policy Display Name</DisplayName>

องค์ประกอบ < ignoreUnresolvedVariable>

(ไม่บังคับ) ไม่สนใจข้อผิดพลาดของตัวแปรที่ยังไม่ได้แก้ไขในโฟลว์ ค่าที่ถูกต้อง: 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 สำหรับ 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>

Attributes

 <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" และค่าที่ 2 ของ "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>

หรือสำหรับ Cloud รุ่น 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>

Attributes

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

องค์ประกอบ <ShortFaultWhy>

ระบุให้แสดงเหตุผลข้อผิดพลาดสั้นๆ ในการตอบกลับ

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

ค่าที่ใช้ได้: true/false(default)

ตัวแปรโฟลว์

ตัวแปรโฟลว์จะเปิดใช้ลักษณะการทำงานแบบไดนามิกของนโยบายและโฟลว์ตอนรันไทม์ โดยอิงตามส่วนหัว 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

หัวข้อที่เกี่ยวข้อง

ดูการจัดการข้อผิดพลาด