Antipattern: ใช้นโยบาย RaiseFault ภายใต้เงื่อนไขที่ไม่เหมาะสม

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่ เอกสารประกอบของ Apigee X info

นโยบาย RaiseFault ช่วยให้นักพัฒนา API เริ่มต้นโฟลว์ข้อผิดพลาด ตั้งค่าตัวแปรข้อผิดพลาด ในข้อความเนื้อหาของการตอบกลับ และตั้งค่ารหัสสถานะการตอบกลับที่เหมาะสมได้ นอกจากนี้ คุณยังใช้นโยบาย RaiseFault เพื่อตั้งค่าตัวแปรโฟลว์ที่เกี่ยวข้องกับข้อผิดพลาดได้ด้วย เช่น fault.name, fault.type, และ fault.category เนื่องจากตัวแปรเหล่านี้จะปรากฏในข้อมูลวิเคราะห์และบันทึกการเข้าถึงของ Router ที่ใช้สำหรับการแก้ไขข้อบกพร่อง จึงควรระบุข้อผิดพลาดอย่างถูกต้อง

คุณสามารถใช้นโยบาย RaiseFault เพื่อถือว่าเงื่อนไขที่เฉพาะเจาะจงเป็นข้อผิดพลาดได้ แม้ว่าจะไม่มีข้อผิดพลาดจริงเกิดขึ้นในนโยบายอื่นหรือในเซิร์ฟเวอร์แบ็กเอนด์ของพร็อกซี API ก็ตาม ตัวอย่างเช่น หากต้องการให้ พร็อกซีส่งข้อความแสดงข้อผิดพลาดที่กำหนดเองไปยังแอปของไคลเอ็นต์เมื่อใดก็ตามที่เนื้อหาของการตอบกลับแบ็กเอนด์มีสตริง unavailable คุณก็สามารถเรียกใช้นโยบาย RaiseFault ได้ตามที่แสดงในข้อมูลโค้ดด้านล่าง 

<!-- /antipatterns/examples/raise-fault-conditions-1.xml  -->
<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>RF-Service-Unavailable</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
   </Step>
  </Response>
...

ชื่อของนโยบาย RaiseFault จะปรากฏเป็น fault.name ใน API Monitoring และเป็น x_apigee_fault_policy ในบันทึกการเข้าถึงของ Analytics และ Router ซึ่งจะช่วยให้คุณวิเคราะห์หาสาเหตุของข้อผิดพลาดได้อย่างง่ายดาย

รูปแบบที่ไม่แนะนำ

การใช้นโยบาย RaiseFault ภายใน FaultRules หลังจากที่นโยบายอื่นแสดงข้อผิดพลาดแล้ว

พิจารณาตัวอย่างด้านล่าง ซึ่งนโยบาย OAuthV2 ในโฟลว์พร็อกซี API ไม่สำเร็จและแสดงข้อผิดพลาด InvalidAccessToken เมื่อไม่สำเร็จ Edge จะตั้งค่า fault.name เป็น InvalidAccessToken เข้าสู่ โฟลว์ข้อผิดพลาด และเรียกใช้ FaultRules ที่กำหนดไว้ ใน FaultRule มีนโยบาย RaiseFault ชื่อ RaiseFault ซึ่งส่งการตอบกลับข้อผิดพลาดที่กำหนดเองเมื่อใดก็ตามที่เกิดข้อผิดพลาด InvalidAccessToken อย่างไรก็ตาม การใช้นโยบาย RaiseFault ใน FaultRule หมายความว่าตัวแปร fault.name จะถูกเขียนทับและซ่อนสาเหตุที่แท้จริงของความล้มเหลว 

<!-- /antipatterns/examples/raise-fault-conditions-2.xml  -->
<FaultRules>
  <FaultRule name="generic_raisefault">
    <Step>
        <Name>RaiseFault</Name>
        <Condition>(fault.name equals "invalid_access_token") or (fault.name equals "InvalidAccessToken")</Condition>
    </Step>
  </FaultRule>
</FaultRules>

การใช้นโยบาย RaiseFault ใน FaultRule ภายใต้ทุกเงื่อนไข

ในตัวอย่างด้านล่าง นโยบาย RaiseFault ชื่อ RaiseFault จะทำงานหาก fault.name ไม่ใช่ RaiseFault 

<!-- /antipatterns/examples/raise-fault-conditions-3.xml  -->
<FaultRules>
    <FaultRule name="fault_rule">
        ....
        <Step>
            <Name>RaiseFault</Name>
            <Condition>!(fault.name equals "RaiseFault")</Condition>
        </Step>
    </FaultRule>
</FaultRules>

เช่นเดียวกับสถานการณ์แรก ตัวแปรข้อผิดพลาดหลัก fault.name, fault.code, และ fault.policy จะถูกเขียนทับด้วยชื่อของนโยบาย RaiseFault ลักษณะการทำงานนี้ทำให้ แทบเป็นไปไม่ได้เลยที่จะระบุนโยบายที่เป็นสาเหตุที่แท้จริงของความล้มเหลวโดยไม่เข้าถึงไฟล์การติดตาม ที่แสดงความล้มเหลวหรือสร้างปัญหาขึ้นใหม่

การใช้นโยบาย RaiseFault เพื่อแสดงการตอบกลับ HTTP 2xx นอกโฟลว์ข้อผิดพลาด

ในตัวอย่างด้านล่าง นโยบาย RaiseFault ชื่อ HandleOptionsRequest จะทำงานเมื่อ คำกริยาของคำขอคือ OPTIONS 

<!-- /antipatterns/examples/raise-fault-conditions-4.xml  -->
<PreFlow name="PreFlow">
    <Request>
        …
        <Step>
            <Name>HandleOptionsRequest</Name>
            <Condition>(request.verb Equals "OPTIONS")</Condition>
        </Step>
        …
</PreFlow>

โดยมีจุดประสงค์เพื่อแสดงการตอบกลับไปยังไคลเอ็นต์ API ทันทีโดยไม่ต้องประมวลผลนโยบายอื่นๆ อย่างไรก็ตาม การดำเนินการนี้จะทำให้ข้อมูลวิเคราะห์คลาดเคลื่อนเนื่องจากตัวแปรข้อผิดพลาดจะมีชื่อของ นโยบาย RaiseFault ซึ่งทำให้การแก้ไขข้อบกพร่องของพร็อกซีทำได้ยากขึ้น วิธีที่ถูกต้องในการใช้ ลักษณะการทำงานที่ต้องการคือการใช้โฟลว์ที่มีเงื่อนไขพิเศษตามที่อธิบายไว้ใน หัวข้อการเพิ่มการรองรับ CORS

ผลกระทบ

การใช้นโยบาย RaiseFault ตามที่อธิบายไว้ข้างต้นจะส่งผลให้ตัวแปรข้อผิดพลาดหลักถูกเขียนทับด้วยชื่อของนโยบาย RaiseFault แทนที่จะเป็นชื่อของนโยบายที่ไม่สำเร็จ ในบันทึกการเข้าถึงของ Analytics และ NGINX ตัวแปร x_apigee_fault_code และ x_apigee_fault_policy จะถูกเขียนทับ ใน API Monitoring ตัวแปร Fault Code และ Fault Policy จะถูกเขียนทับ ลักษณะการทำงานนี้ทำให้การแก้ปัญหาและ การระบุนโยบายที่เป็นสาเหตุที่แท้จริงของความล้มเหลวทำได้ยาก

ในภาพหน้าจอด้านล่างจาก API Monitoring คุณจะเห็นว่า Fault Code และ Fault Policy ถูกเขียนทับเป็นค่า RaiseFault ทั่วไป ซึ่งทำให้ไม่สามารถระบุสาเหตุหลักของความล้มเหลวจากบันทึกได้

แนวทางปฏิบัติแนะนำ

เมื่อนโยบาย Edge แสดงข้อผิดพลาดและคุณต้องการปรับแต่งข้อความแสดงข้อผิดพลาด ให้ใช้นโยบาย AssignMessage หรือ JavaScript แทนนโยบาย RaiseFault

ควรใช้นโยบาย RaiseFault ในโฟลว์ที่ไม่ใช่โฟลว์ข้อผิดพลาด นั่นคือ ให้ใช้ RaiseFault เพื่อถือว่าเงื่อนไขที่เฉพาะเจาะจง เป็นข้อผิดพลาดเท่านั้น แม้ว่าจะไม่มีข้อผิดพลาดจริงเกิดขึ้นในนโยบายหรือในเซิร์ฟเวอร์แบ็กเอนด์ ของพร็อกซี API ก็ตาม ตัวอย่างเช่น คุณสามารถใช้นโยบาย RaiseFault เพื่อส่งสัญญาณว่าไม่มีพารามิเตอร์อินพุตที่บังคับ หรือมีไวยากรณ์ไม่ถูกต้อง

นอกจากนี้ คุณยังใช้ RaiseFault ในกฎข้อผิดพลาดได้หากต้องการตรวจหาข้อผิดพลาดระหว่างการประมวลผลข้อผิดพลาด ตัวอย่างเช่น ตัวแฮนเดิลข้อผิดพลาดเองอาจทำให้เกิดข้อผิดพลาดที่คุณต้องการส่งสัญญาณโดยใช้ RaiseFault

อ่านเพิ่มเติม