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

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

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

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

การจัดการข้อผิดพลาดที่กำหนดเองยังให้คุณเพิ่มฟังก์ชันการทำงานได้ เช่น การบันทึกข้อความเมื่อใดก็ตามที่ มีข้อผิดพลาดเกิดขึ้น

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

วิดีโอ

ดูวิดีโอต่อไปนี้เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการข้อผิดพลาด

ข้อผิดพลาดเกิดขึ้นได้อย่างไร

ก่อนอื่นเราจะพูดถึงวิธีที่ข้อผิดพลาดเกิดขึ้น การรู้ว่าข้อผิดพลาดเกิดขึ้นได้อย่างไรช่วยให้คุณวางแผน สำหรับสถานการณ์ต่างๆ ที่คุณต้องการใช้การจัดการข้อผิดพลาดที่กำหนดเอง

ข้อผิดพลาดอัตโนมัติ

พร็อกซี API จะแสดงข้อผิดพลาดโดยอัตโนมัติในสถานการณ์ต่อไปนี้

• นโยบายทำให้เกิดข้อผิดพลาด ตัวอย่างเช่น หากการเรียก API ส่งคีย์ที่หมดอายุแล้ว พารามิเตอร์ นโยบาย VerifyAPIKey แสดงข้อผิดพลาดโดยอัตโนมัติ หรือหากจำนวนการเรียก API เกินขีดจำกัดบางอย่าง นโยบายโควต้าหรือนโยบาย SpikeArrest มีข้อผิดพลาด (โปรดดูข้อมูลอ้างอิงเกี่ยวกับข้อผิดพลาดเกี่ยวกับนโยบายสำหรับ ประเภทข้อผิดพลาดที่อาจได้รับ)
• เกิดปัญหากับโฟลว์ข้อความพร็อกซี API เช่น ข้อผิดพลาดในการกำหนดเส้นทาง
• มีความล้มเหลวแบ็กเอนด์ เช่น ข้อผิดพลาด HTTP เนื่องจากข้อผิดพลาดระดับโปรโตคอล TLS/SSL หรือบริการเป้าหมายที่ไม่พร้อมใช้งาน
• มีการทำงานล้มเหลวระดับระบบ เช่น ข้อยกเว้นที่ไม่อยู่ในหน่วยความจำ

ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดเหล่านี้ได้ที่การจัดหมวดหมู่ข้อผิดพลาดในหัวข้อนี้

ข้อผิดพลาดที่กำหนดเอง

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

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

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

ข้อความนี้เป็นเพียงการแสดงว่าคุณสามารถแสดงข้อผิดพลาดที่กำหนดเองได้ เราจะลงลึกรายละเอียดเกี่ยวกับ นโยบาย RaiseFault ในนโยบาย FaultRules เทียบกับนโยบาย RaiseFault

ดูตัวอย่างเพิ่มเติมได้ในฟอรัมชุมชน Apigee

• การอ้างอิงตัวแปร JavaScript ใน RaiseFault

สิ่งที่พร็อกซี API ทำเมื่อเกิดข้อผิดพลาด

สิ่งที่จะเกิดขึ้นเมื่อพร็อกซีแสดงข้อผิดพลาด

ออกจากไปป์ไลน์พร็อกซี

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

เช่น สมมติว่าพร็อกซี API มีนโยบายตามลำดับต่อไปนี้ใน ProxyEndpoint คำขอ:

1. ยืนยันคีย์ API
2. โควต้า
3. JSON เป็น XML

หากเกิดข้อผิดพลาดระหว่างการยืนยันคีย์ API พร็อกซี API จะย้ายไปยังสถานะข้อผิดพลาด ไม่มีการบังคับใช้นโยบายโควต้าและ JSON เป็น XML พร็อกซีจะไม่ดำเนินการต่อไปยัง TargetEndpoint และข้อความแสดงข้อผิดพลาดจะแสดงผลไปยังแอปไคลเอ็นต์

ตรวจสอบ FaultRules

ในสถานะข้อผิดพลาด พร็อกซี API จะตรวจสอบการมีอยู่ต่อไปนี้ (ตามลำดับ) ใน การกำหนดค่าพร็อกซี API ก่อนแสดงข้อความแสดงข้อผิดพลาดเริ่มต้นไปยังแอปไคลเอ็นต์

1. ส่วน <FaultRules> ซึ่งมีตรรกะเพื่อ เรียกข้อความแสดงข้อผิดพลาดที่กำหนดเอง (และนโยบายอื่นๆ) ตามเงื่อนไขเฉพาะที่คุณ นิยาม
2. ส่วน <DefaultFaultRule> ซึ่งจะเรียกใช้ค่าเริ่มต้น ในสถานการณ์ต่อไปนี้
   • ไม่มีการกำหนด <FaultRules>
   • ไม่มีการดำเนินการ <FaultRules> ที่มีอยู่
   • องค์ประกอบ <AlwaysEnforce> ได้รับการตั้งค่าเป็น "จริง"

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

ตัวอย่างการจัดการข้อผิดพลาดทั่วไป

เรามาเริ่มจากตัวอย่างง่ายๆ ที่การเรียกใช้พร็อกซี API ไม่มี API ที่จำเป็น โดยค่าเริ่มต้น ต่อไปนี้คือการตอบกลับที่ส่งคืนไปยังแอปไคลเอ็นต์

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

ผู้ใช้ API ของคุณอาจทราบข้อความแสดงข้อผิดพลาด แต่อาจไม่เห็น และค่าเริ่มต้นหลายรายการ จะเข้าใจได้ลึกกว่าและตีความได้ยากกว่า

ในฐานะนักพัฒนา API คุณสามารถเปลี่ยนแปลงข้อความนี้เพื่อตอบสนองความต้องการของผู้ที่จะ ได้รับข้อความแสดงข้อผิดพลาดในที่สุด ไม่ว่าจะเป็นนักพัฒนาแอป iOS หรือการทดสอบภายใน ที่มีข้อกำหนดรูปแบบข้อความแสดงข้อผิดพลาดของตนเอง

ต่อไปนี้เป็นตัวอย่างพื้นฐานของวิธีสร้างข้อความแสดงข้อผิดพลาดที่กำหนดเองเพื่อจัดการข้อผิดพลาดนี้ ช่วงเวลานี้ กําหนดให้ 1) นโยบายที่กําหนดข้อความที่กําหนดเอง และ 2) FaultRule ที่ดําเนินการนโยบาย เมื่อพร็อกซีอยู่ในสถานะข้อผิดพลาด

1. สร้างนโยบาย ซึ่งระบุข้อความที่กำหนดเอง

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

อย่าแนบนโยบายกับขั้นตอนในพร็อกซี API ก็เพียงพอแล้วที่จะมีอยู่ใน พร็อกซี ในการดำเนินการนี้ในตัวแก้ไขพร็อกซี UI การจัดการ ให้ไปที่แท็บพัฒนา และใน แผงการนำทาง แล้วคลิกไอคอน + ในแถบนโยบาย

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

ต่อไปนี้คือตัวอย่างนโยบาย AssignMessage ที่

• แสดงผลข้อความ JSON
• ตั้งรหัสสถานะ HTTP (911 ซึ่งเป็นรหัสสถานะที่ไม่มีอยู่จริงอย่างชัดเจนเพื่อ เพื่อแสดงถึงความยืดหยุ่นที่คุณมี) รหัสสถานะจะปรากฏในส่วนหัวของ HTTP
• ตั้งค่าวลีเหตุผลของ HTTP (เพื่อแทนที่วลีเหตุผล "ไม่ได้รับอนุญาต" เริ่มต้นสําหรับกรณีนี้ ไม่มีข้อผิดพลาดคีย์ API) วลีเหตุผลปรากฏข้างรหัสสถานะใน HTTP ส่วนหัว
• สร้างและป้อนข้อมูลส่วนหัว HTTP ใหม่ที่มีชื่อว่า invalidKey

<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

เมื่อบังคับใช้นโยบายนี้ การตอบกลับแอปไคลเอ็นต์จะมีลักษณะดังต่อไปนี้ เปรียบเทียบกับคำตอบเริ่มต้นที่แสดงก่อนหน้านี้

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

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

แต่นโยบายนี้จะดำเนินการอย่างไร ส่วนถัดไปจะแสดงข้อมูล

2. สร้าง <FaultRule> ซึ่งจะทริกเกอร์นโยบาย

ในส่วน <ProxyEndpoint> หรือ <TargetEndpoint> ของ การกำหนดค่าพร็อกซี คุณจะเพิ่มบล็อก XML <FaultRules> ที่มี ส่วนละ <FaultRule> ส่วนขึ้นไป FaultRule แต่ละรายการแสดง ที่คุณต้องจัดการ ในตัวอย่างง่ายๆ นี้ เราจะใช้ FaultRule เพียงรายการเดียวเพื่อแสดง จะประกอบด้วยองค์ประกอบ

คุณควรเพิ่ม <DefaultFaultRule> ด้วยเพื่อระบุข้อผิดพลาดทั่วไปที่กำหนดเอง หากไม่มีการเรียกใช้ FaultRules เลย

ตัวอย่าง

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

ข้อมูลสำคัญ

• ระบบจะกำหนด FaultRules ใน ProxyEndpoint เรื่องนี้สำคัญมาก ข้อมูลเพิ่มเติมเกี่ยวกับการส่ง FaultRules ใน ProxyEndpoint เทียบกับ TargetEndpoint
• <Name> - ชื่อนโยบายที่จะดำเนินการ ชื่อ มาจากแอตทริบิวต์ name ของนโยบายในองค์ประกอบระดับบนสุด ดังที่แสดงใน ตัวอย่างนโยบายก่อนหน้านี้

• <Condition> - Edge จะประเมินเงื่อนไขและ จะบังคับใช้นโยบายก็ต่อเมื่อเงื่อนไขเป็นจริงเท่านั้น หากมี FaultRules หลายรายการ ประเมินเป็น true แล้ว Edge จะใช้รายการแรกที่เป็นจริง (สำคัญ: ลำดับที่มีการประเมิน FaultRules ได้แก่ จากบนลงล่างหรือล่างขึ้นบน แตกต่างกันระหว่าง TargetEndpoint และ ProxyEndpoint ตามที่อธิบายไว้ในMultiple FaultRule และตรรกะการดำเนินการ) หากไม่ระบุเงื่อนไข ระบบจะใช้ FaultRule เป็นจริงโดยอัตโนมัติ แต่นั่นไม่ใช่แนวทางปฏิบัติแนะนำ FaultRule แต่ละรายการควรมี

• <DefaultFaultRule> - หากไม่มี FaultRule ที่กำหนดเองคือ ดำเนินการ <DefaultFaultRule> แล้ว ซึ่งส่ง ข้อความที่กำหนดเอง แทนข้อความเริ่มต้นที่เข้ารหัสลับซึ่งสร้างขึ้นจาก Edge ต <DefaultFaultRule> อาจมี <Condition> ได้ด้วย แต่ กรณีส่วนใหญ่ที่คุณจะไม่ต้องรวมรหัสดังกล่าว เพราะคุณต้องการให้ระบบเรียกใช้ ไม่ว่าจะเป็นเหตุการณ์สุดท้าย รีสอร์ต

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

FaultRule หลายรายการและตรรกะการดำเนินการ

ในส่วนตัวอย่างการจัดการข้อผิดพลาดอย่างง่าย เราใช้ตัวอย่างง่ายๆ ของ FaultRule และเงื่อนไขเดียว ในโปรเจ็กต์ API ในชีวิตจริง โดยมีข้อผิดพลาดทั้งหมดที่อาจเกิดขึ้น จึงเป็นไปได้ว่าจะมี FaultRules และ DefaultFaultRule หลายรายการทั้ง <ProxyEndpoint> และ <TargetEndpoint> แต่ในที่สุดแล้ว จะเรียกใช้ FaultRule เพียงรายการเดียวเมื่อพร็อกซี API อยู่ในสถานะข้อผิดพลาด

ส่วนนี้จะอธิบายตรรกะ Edge ที่ใช้ในการจัดการ FaultRules, ตั้งแต่วิธีที่มาถึง FaultRule เดียวที่จะทำงานตาม "ภายใน" ระบบจะจัดการเงื่อนไขขั้นตอนเมื่อ FaultRule ทริกเกอร์ ส่วนนี้ยังมีคำแนะนำเกี่ยวกับเวลาที่ควรกำหนด FaultRules ใน <ProxyEndpoint> เทียบกับ <TargetEndpoint> และอธิบาย ความสัมพันธ์ระหว่าง FaultRules กับนโยบาย RaiseFault

การดำเนินการ FaultRules

กล่าวโดยสรุปคือ Logic Edge จะใช้เมื่อพร็อกซี API อยู่ในสถานะข้อผิดพลาด โปรดทราบว่า มีความแตกต่างเล็กน้อยระหว่างการประเมิน FaultRules ใน ProxyEndpoint และ TargetEndpoint

1. Edge จะประเมิน FaultRules ใน ProxyEndpoint หรือ TargetEndpoint ทั้งนี้ ที่เกิดข้อผิดพลาด
   • ProxyEndpoint - Edge เริ่มต้นด้วย bottom <FaultRule> ใน XML การกำหนดค่าและความคืบหน้าในการดำเนินการ ประเมิน <Condition> ของแต่ละ <FaultRule> ("ด้านนอก" สภาพ ซึ่งไม่ใช่ "ภายใน" <Step> เงื่อนไข)
   • TargetEndpoint - Edge เริ่มต้นด้วยด้านบนสุด <FaultRule> ใน XML การกำหนดค่าและเลื่อนลงมา ประเมินผล <Condition> ของแต่ละ <FaultRule> ("ด้านนอก" สภาพ ซึ่งไม่ใช่ "ภายใน" <Step> เงื่อนไข)
2. เรียกใช้ FaultRule แรกซึ่งมีเงื่อนไขเป็นจริง หาก FaultRule มี ไม่มีเงื่อนไข ระบบจะเป็นจริงโดยค่าเริ่มต้น
   • เมื่อเรียกใช้ FaultRule จะมีการประเมินขั้นตอนทั้งหมดใน FaultRule ตามลำดับ จากบนลงล่างในการกำหนดค่า XML ระบบจะดำเนินการตามขั้นตอนที่ไม่มีเงื่อนไขโดยอัตโนมัติ (มีการบังคับใช้นโยบาย) และขั้นตอนที่มี <Condition> ที่ ประเมินเป็น "จริง" ดำเนินการ (เงื่อนไขที่ประเมินค่าเป็น "เท็จ" จะไม่ใช่ ดำเนินการแล้ว)

   • หากดำเนินการตาม FaultRule แต่ไม่มีการดำเนินการขั้นตอนใน FaultRule (เนื่องจาก ประเมินได้เป็น "เท็จ") ข้อความแสดงข้อผิดพลาดเริ่มต้นที่สร้างโดย Edge จะส่งกลับไปยัง แอปไคลเอ็นต์ ไม่ได้ดำเนินการ <DefaultFaultRule> เนื่องจาก Edge ได้เรียกใช้ FaultRule ไปแล้ว 1 รายการ

3. หากไม่มีการเรียกใช้ FaultRule แล้ว Edge จะใช้ <DefaultFaultRule> หาก ปัจจุบัน

ต่อไปนี้เป็นตัวอย่างความคิดเห็นแบบแทรกในบรรทัด

การดำเนินการของ ProxyEndpoint

การประเมิน ProxyEndpoint FaultRules จะเรียงจากด้านล่างสุดเพื่อให้เริ่มอ่านที่ท้ายสุด FaultRule ในตัวอย่างต่อไปนี้และความคืบหน้าของคุณ ลองดูที่ DefaultFaultRule เป็นลำดับสุดท้าย

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

การดำเนินการปลายทางเป้าหมาย

การประเมิน TargetEndpoint FaultRules เป็นแบบบนลงล่างสุด ดังนั้นให้เริ่มอ่านตอนแรก FaultRule ในตัวอย่างต่อไปนี้และไล่ระดับลง ลองดูที่ DefaultFaultRule เป็นลำดับสุดท้าย

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

ลำดับของกฎข้อผิดพลาด

ดังที่คุณเห็นในตัวอย่างก่อนหน้านี้ ลำดับที่คุณใส่ FaultRules คือ ขึ้นอยู่กับว่าข้อผิดพลาดนั้นเกิดขึ้นใน ProxyEndpoint กับ TargetEndpoint

เช่น

นโยบายที่จะรวม

คุณบังคับใช้นโยบายจาก FaultRule ได้โดยใส่นโยบายในขั้นตอน ตัวอย่างเช่น คุณสามารถ เรียกใช้นโยบาย AssignMessage เพื่อจัดรูปแบบการตอบกลับไปยังแอปไคลเอ็นต์ จากนั้นบันทึกข้อความ ตามนโยบายการบันทึกข้อความ ระบบจะดำเนินการตามนโยบายตามลำดับที่คุณกำหนด (จากบนลงล่างใน XML)

กฎความผิดพลาดจะทำงานเมื่ออยู่ในสถานะข้อผิดพลาดเท่านั้น (เกี่ยวกับ ContinueOnError)

หัวเรื่องนี้อาจจะดูเหมือนว่าเราจะกล่าวซ้ำไปซ้ำมา แต่จริงๆ แล้วมีความแตกต่างอยู่เล็กน้อยอย่างหนึ่งคือ ทราบข้อผิดพลาดเกี่ยวกับพร็อกซีที่ทำให้พร็อกซี API ป้อนสถานะข้อผิดพลาด หรือ แต่ไม่ป้อนสถานะข้อผิดพลาด: แอตทริบิวต์ continueOnError ใน

สรุป: พร็อกซี API จะประเมิน <FaultRules> และ <DefaultFaultRule> เฉพาะเมื่อพร็อกซีป้อนสถานะข้อผิดพลาด นั่น หมายความว่าแม้ว่าเงื่อนไข FaultRule จะประเมินค่าเป็นจริง ก็จะไม่มีการทริกเกอร์หากพร็อกซี ไม่อยู่ในสถานะข้อผิดพลาด

อย่างไรก็ตาม ต่อไปนี้คือตัวอย่างของข้อผิดพลาดที่เกิดขึ้นและพร็อกซีไม่ป้อนสถานะข้อผิดพลาด เปิด นโยบายใดก็ได้ คุณสามารถตั้งแอตทริบิวต์ในองค์ประกอบระดับบนที่ชื่อว่า continueOnError แอตทริบิวต์นั้นสำคัญมากเกี่ยวกับการจัดการข้อผิดพลาด เนื่องจากจะกำหนดว่า ไม่ใช่พร็อกซีป้อนสถานะข้อผิดพลาดหากนโยบายล้มเหลว ในกรณีส่วนใหญ่ คุณจะต้องให้แท็ก continueOnError="false" ซึ่งจะทำให้พร็อกซีอยู่ในสถานะข้อผิดพลาดหาก นโยบายล้มเหลว และการจัดการข้อผิดพลาดที่กำหนดเองจะถูกเรียกใช้ อย่างไรก็ตาม หาก continueOnError="true" (เช่น หากไม่ต้องการให้บริการล้มเหลว ข้อความเสริมให้หยุดการดำเนินการของพร็อกซี) พร็อกซีจะไม่มีสถานะเป็นข้อผิดพลาดหากเป็นเช่นนั้น นโยบายล้มเหลวและพร็อกซีจะไม่ดู FaultRules ของคุณ

โปรดดูข้อมูลเกี่ยวกับข้อผิดพลาดในการบันทึกเมื่อ continueOnError="true" ที่หัวข้อการจัดการข้อผิดพลาดด้านนโยบายภายในโฟลว์ปัจจุบัน

สถานที่ เพื่อกำหนด FaultRules: ProxyEndpoint หรือ TargetEndpoint

เมื่อพร็อกซี API พบข้อผิดพลาด ข้อผิดพลาดจะเกิดขึ้นใน <ProxyEndpoint> (คำขอจากหรือตอบกลับแอปไคลเอ็นต์) หรือใน <TargetEndpoint> (คำขอหรือการตอบกลับจากบริการเป้าหมาย) ไม่ว่าจะอยู่ที่ใด จะปรากฏขึ้นเมื่อ Edge มองหา FaultRules

ตัวอย่างเช่น หากเซิร์ฟเวอร์เป้าหมายไม่พร้อมใช้งาน (รหัสสถานะ HTTP 503) พร็อกซี API จะทำงาน เป็นสถานะข้อผิดพลาดในการตอบกลับ <TargetEndpoint> และพร็อกซี API ปกติ จะไม่ดำเนินการต่อไปยัง <ProxyEndpoint> หากคุณกำหนด FaultRules ไว้ เฉพาะใน <ProxyEndpoint> จะไม่จัดการกับข้อผิดพลาดนั้น

มาดูอีกตัวอย่างหนึ่งกัน หากนโยบาย RaiseFault ใน <ProxyEndpoint> การตอบสนองทำให้เกิดข้อผิดพลาด แต่ FaultRule ใน <TargetEndpoint> จะไม่แสดง ดำเนินการแล้ว

FaultRules เทียบกับนโยบาย RaiseFault

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

เคล็ดลับโดยสรุปมีดังนี้

• กฎความผิดพลาดจะได้รับการประเมินเสมอเมื่อพร็อกซี API ป้อนข้อผิดพลาด

• นโยบาย RaiseFault เป็นวิธีทำให้พร็อกซี API อยู่ในสถานะข้อผิดพลาด เมื่อข้อผิดพลาดไม่เกิดขึ้น

  ตัวอย่างเช่น หากคุณต้องการให้แสดงข้อผิดพลาดหากรหัสสถานะ HTTP ในการตอบกลับจาก บริการเป้าหมายมีปริมาณมากกว่า 200 คุณเพิ่มนโยบาย RaiseFault ในการตอบกลับ URL จะมีหน้าตาดังนี้:

  <TargetEndpoint name="default">
      <PreFlow name="PreFlow">
  ...
          <Response>
              <Step>
                  <Name>Raise-Fault-1</Name>
  <!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                  <Condition>(response.status.code GreaterThan "200")</Condition>
              </Step>
          </Response> 
  

  นโยบาย RaiseFault ยังส่งข้อความแสดงข้อผิดพลาดไปยังแอปไคลเอ็นต์ด้วย

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

• เนื่องจาก FaultRule หรือ DefaultFaultRule มีการใช้งานหลังจากนโยบาย RaiseFault ข้อมูลการตอบสนองของ FaultRule จะชนะ
• ข้อมูลการตอบกลับนโยบาย RaiseFault (รหัสสถานะ วลีเหตุผล หรือเพย์โหลดข้อความ) คือ ใช้ในกรณีที่ข้อมูลดังกล่าวไม่ได้ตั้งค่าโดย FaultRule หรือ DefaultFaultRule
• หากทั้งนโยบาย RaiseFault และ FaultRule เพิ่มส่วนหัว HTTP ที่กําหนดเอง ทั้ง 2 อย่างจะรวมอยู่ใน คำตอบ ชื่อส่วนหัวที่ซ้ำกันจะสร้างส่วนหัวที่มีหลายค่า

นี่คือตัวอย่างของสิ่งที่นโยบาย RaiseFault และ FaultRule ตั้งค่าไว้ รวมถึงสิ่งที่ กลับไปที่แอปไคลเอ็นต์ ตัวอย่างได้รับการออกแบบมาเพื่อความกระชับ ไม่ใช่แนวทางปฏิบัติแนะนำ

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: woops,gremlins

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: gremlins

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

สภาพอาคาร

เงื่อนไขเป็นกุญแจสู่การดำเนินการ FaultRule คุณสร้างเงื่อนไข FaultRule ในลักษณะเดียวกัน ที่คุณทำให้กับเงื่อนไขอื่นๆ ใน Edge เช่น สำหรับโฟลว์แบบมีเงื่อนไขหรือเงื่อนไข RaiseFault

เพื่อให้ส่วนที่เหลือของส่วนนี้เป็นบริบท ต่อไปนี้เป็นตัวอย่างกฎ Fault ที่มีด้านนอก เงื่อนไข FaultRule และเงื่อนไขขั้นตอนภายใน

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

ตัวแปรเฉพาะสําหรับนโยบาย ข้อผิดพลาด

ตัวแปร fault.name และ {policy_namespace}.{policy_name}.failed พร้อมใช้งานเมื่อนโยบายแสดงข้อผิดพลาด

fault.name

เมื่อนโยบายล้มเหลว ให้ตรวจจับข้อผิดพลาดในเงื่อนไขโดยใช้ fault.name ตัวแปร เช่น

<Condition>(fault.name = "policy_error_name")</Condition>

ชื่อข้อผิดพลาดจะปรากฏในข้อความแสดงข้อผิดพลาดเริ่มต้น ตัวอย่างเช่น ในกรณีต่อไปนี้ ชื่อคือ FailedToResolveAPIKey ในกรณีนี้ ตัวแปรโฟลว์ที่เรียกว่า ตั้งค่า fault.name เป็นค่า FailedToResolveAPIKey

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

ดังนั้นเงื่อนไขจะมีลักษณะดังนี้

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

ดูข้อผิดพลาดของนโยบาย ข้อมูลอ้างอิงสำหรับรายการข้อผิดพลาดด้านนโยบาย

{policy_namespace}.{policy_name} ไม่สำเร็จ

ตัวแปร *.failed จะพร้อมใช้งานเมื่อนโยบายล้มเหลว ต่อไปนี้เป็น ตัวอย่างตัวแปร *.failed สำหรับนโยบายต่างๆ สำหรับเนมสเปซของนโยบาย โปรดดูตัวแปรโฟลว์ในหัวข้อการอ้างอิงนโยบายแต่ละรายการ

• นโยบาย RaiseFault: raisefault.failed (เหมือนกันสำหรับนโยบาย RaiseFault ทั้งหมด)
• VerifyAPIKey policy: oauthV2.{policy_name}.failed สำหรับ ตัวอย่างเช่น oauthV2.Verify-API-Key-1.failed
• นโยบายโควต้าและนโยบาย SpikeArrest มีดังนี้ เช่น ratelimit.{policy_name}.failed ratelimit.Quota-1.failed

ตัวแปรอื่นๆ ที่ใช้ได้

เมื่อพร็อกซี API อยู่ในสถานะข้อผิดพลาด ตัวแปรที่ใช้ได้จะใช้ได้ในเงื่อนไขเท่านั้น ได้แก่

• ตัวแปรของนโยบายที่ล้มเหลว
• ตัวแปรข้อความ HTTP ที่มีอยู่ ณ จุดที่ล้มเหลว ตัวอย่างเช่น หากข้อผิดพลาดคือ ในการตอบสนอง FaultRule ใน <TargetEndpoint> สามารถใช้ HTTP ข้อมูล response.status.code, message.content error.content และอื่นๆ หรือหากนโยบายโควต้าล้มเหลว คุณสามารถใช้ ตัวแปร ratelimit.{quota_policy_name}.exceed.count ใช้เครื่องมือการติดตามและนโยบาย หัวข้ออ้างอิงเพื่อช่วยคุณหาตัวแปรและข้อมูล HTTP ที่สามารถใช้ได้

ข้อมูลเพิ่มเติม

• เงื่อนไข: การอ้างอิงเงื่อนไข และตัวแปรโฟลว์และ ของ Google

• ข้อผิดพลาด: ข้อมูลอ้างอิงข้อผิดพลาดของนโยบาย
• ตัวแปร: ข้อมูลอ้างอิงตัวแปร และดูคอลัมน์ หน้าอ้างอิงนโยบายสำหรับตัวแปรที่มีอยู่ในแต่ละนโยบาย

แนวทางปฏิบัติแนะนำสำหรับการจัดการข้อผิดพลาด

การจัดการข้อผิดพลาดเป็นงานออกแบบเชิงสถาปัตยกรรมที่สำคัญสำหรับการพัฒนาพร็อกซี API เป็นสิ่งสำคัญ เพื่อคิดหาวิธีและเวลาที่จะจัดการข้อผิดพลาด รวมถึงระบุข้อผิดพลาด และออกแบบรูปแบบข้อความแสดงข้อผิดพลาด หลังจากที่ (หรือ) คุณคิดหาวิธีเหล่านั้น จากนั้นใช้แนวทางปฏิบัติแนะนำ เพื่อช่วยในการจัดการข้อผิดพลาด

แนวทางปฏิบัติแนะนำในการออกแบบและสร้างการจัดการข้อผิดพลาดมีดังนี้

• สำหรับ FaultRule แต่ละรายการ ให้ระบุ "ด้านนอก" <Condition> (ข้างเคียงกับ <Step>) กฎข้อผิดพลาดที่ไม่มีเงื่อนไขภายนอกจะทำการประเมินโดยอัตโนมัติ เป็นจริง "ภายใน" ไม่ใช้เงื่อนไขขั้นตอนเพื่อระบุว่า FaultRule เป็นจริงหรือไม่ หรือ false ระบบจะประเมินเงื่อนไขขั้นตอนหลังจากที่ Edge เรียกใช้ FaultRule ที่มีเงื่อนไขดังกล่าวเท่านั้น ใน FaultRule โดยทั่วไปแล้วจะมีขั้นตอนหลายขั้นตอนพร้อมนโยบายมอบหมายข้อความ (หรืออื่นๆ) แต่ละรายการจะมีเงื่อนไขขั้นตอน

• เพื่อจัดการข้อผิดพลาดในนโยบายประเภทเดียวกันหลายรายการ (เช่น โควต้าหลายรายการ ) ให้สร้าง FaultRule ต่อข้อผิดพลาดนโยบายที่คุณมีแนวโน้มที่จะได้รับ ตัวอย่างเช่น สร้าง FaultRule สำหรับข้อผิดพลาดที่เป็นไปได้แต่ละรายการในนโยบายโควต้า เช่น QuotaViolation InvalidMessageWeight StartTimeNotSupported (โปรดดูข้อมูลอ้างอิงเกี่ยวกับข้อผิดพลาดเกี่ยวกับนโยบายสำหรับ ข้อผิดพลาดเกี่ยวกับนโยบาย เมื่อคุณพบข้อผิดพลาดเพิ่มเติมที่ต้องจัดการ คุณสามารถย้อนกลับ ในภายหลังและเพิ่มลงใน FaultRules ของคุณ การทำซ้ำก็ไม่เป็นไร แม้ว่าจะต้อง การทำให้พร็อกซีใช้งานได้ใหม่) วิธีนี้จะทำให้คุณตรวจพบข้อผิดพลาดประเภทเดียวกันได้ไม่ว่าข้อผิดพลาดใดก็ตาม นโยบายนี้จะทำให้ FaultRules ของคุณมีประสิทธิภาพ

  จากนั้นใช้เงื่อนไขขั้นตอนภายในหากต้องการการควบคุมข้อผิดพลาดอย่างละเอียดมากขึ้น ตัวอย่างเช่น หากคุณกำลังบังคับใช้ทั้งโควต้านักพัฒนาซอฟต์แวร์รายบุคคลและโควต้าทั่วโลกด้วย 2 นโยบายใน ขั้นตอนการส่งคำขอ ตั้งค่า "ด้านนอก" เงื่อนไข FaultRule ที่จะทริกเกอร์ใน ข้อผิดพลาด QuotaViolation รายการ (ซึ่งเกิดขึ้นเมื่อโควต้าเกินโควต้าไม่ว่าในกรณีใด) จากนั้น กำหนดเงื่อนไขขั้นตอนเพื่อประเมินตัวแปร exceed.count ในโควต้าทั้ง 2 รายการ ระบบจะส่งเฉพาะข้อผิดพลาดที่เกี่ยวข้องไปยังไคลเอ็นต์ (เกินโควต้านักพัฒนาแอปหรือทั่วโลก เกินโควต้า) ตัวอย่างการกำหนดค่ามีดังนี้

  <FaultRule name="over_quota">
  <!-- This condition catches a QuotaViolation in *any* Quota policy -->
    <Condition>(fault.name = "QuotaViolation")</Condition>
    <Step>
      <Name>developer-over-quota-fault</Name>
      <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
    <Step>
      <Name>global-over-quota-fault</Name>
      <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
  </FaultRule>
  

  หรือดูตัวอย่างได้ที่ชุดข้อความของชุมชน Apigee นี้

• หากต้องการจัดการข้อผิดพลาดเมื่อใช้นโยบายเดียวประเภทหนึ่ง ให้พิจารณาข้อผิดพลาดเดียว กฎที่จะมีการดำเนินการเมื่อนโยบายหนึ่งล้มเหลว และมีหลายขั้นตอนที่จะจับคู่กับ ข้อผิดพลาดที่อาจเกิดขึ้นได้แต่ละข้อ ซึ่งจะทำให้ XML ของคุณมีประสิทธิภาพด้วยการใช้ FaultRule เดียวแทน FaultRule หลายรายการ (1 กฎสําหรับข้อผิดพลาดแต่ละประเภท) เช่น

  <FaultRule name="raise-fault-3">
  <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
    <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
    <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
    <Step>
      <Name>Generic-Key-Fault</Name>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-1</Name>
      <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-2</Name>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </Step>
  </FaultRule>
  

• เพิ่ม FaultRules ในตำแหน่งที่จะเกิดข้อผิดพลาด (ฝั่งไคลเอ็นต์ <ProxyEndpoint> หรือเป้าหมายด้าน <TargetEndpoint>) รวม FaultRules สำหรับแต่ละนโยบายที่ จะปรากฏในแต่ละตำแหน่ง
• ใน FaultRules คุณสามารถใช้นโยบายประเภทใดก็ได้ที่ส่งข้อความกลับไปยังไคลเอ็นต์ได้ แอป นโยบาย AssignMessage เหมาะสำหรับกรณีนี้ และพิจารณาการบันทึกข้อความด้วย นโยบาย MessageLcking หากคุณต้องการติดตามข้อผิดพลาด
• เมื่อใช้นโยบาย RaiseFault ร่วมกับ FaultRules ให้ประสานการตอบกลับ ข้อมูลที่ส่งกลับเมื่อทั้งนโยบาย RaiseFault และ FaultRule แสดงผลข้อมูล สำหรับ เช่น หากนโยบาย RaiseFault รีเซ็ตรหัสสถานะ HTTP ก็ไม่ต้องรีเซ็ต FaultRule รหัสสถานะ ปัญหาใหญ่ที่สุดที่อาจเกิดขึ้นคือ รหัสสถานะเริ่มต้นจะถูกส่งคืนไปยัง แอปไคลเอ็นต์
• การดำเนินการ <DefaultFaultRule> รายการ:
  • หากคุณต้องการให้ <DefaultFaultRule> ทำงานเสมอเมื่อไม่มีตัวแปรอื่น FaultRule ทํางานอยู่ ไม่ต้องใส่ <Condition>
  • หากคุณต้องการให้ <DefaultFaultRule> ทำงานเสมอแม้ว่าจะมีอีกรายการก็ตาม ดำเนินการ FaultRule แล้ว โปรดเพิ่ม องค์ประกอบย่อย <AlwaysEnforce>true</AlwaysEnforce>

รูปแบบสำหรับ การจัดการข้อผิดพลาดจากส่วนกลางและนำมาใช้ใหม่ได้

โพสต์ชุมชน Apigee ต่อไปนี้อธิบายรูปแบบการจัดการข้อผิดพลาดแบบรวมศูนย์โดยไม่มี การทำซ้ำโค้ด:

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

การสร้าง FaultRule

ในการเพิ่ม FaultRule คุณจะต้องแก้ไขการกำหนดค่า XML ของ ProxyEndpoint หรือ TargetEndpoint คุณสามารถใช้ Edge UI เพื่อทำการแก้ไขในแผงโค้ดของ มุมมองพัฒนาสำหรับพร็อกซี API หรือแก้ไขไฟล์ XML ที่กำหนด ProxyEndpoint หรือ TargetEndpoint

หากคุณสร้าง FaultRules ใน UI การจัดการ ให้สร้างนโยบายที่ต้องการดำเนินการก่อน จากนั้นให้เพิ่มลงในการกำหนดค่า FaultRule (คุณจะได้รับข้อผิดพลาดใน UI ถ้าพยายามบันทึก FaultRule ที่อ้างอิงนโยบายที่ยังไม่ได้สร้าง)

การเพิ่มนโยบายไปยัง FaultRule

แม้ว่าคุณจะสามารถใส่นโยบายใดๆ ใน FaultRule แต่โดยทั่วไปแล้วมักจะใช้ AssignMessage policy เพื่อสร้างข้อความตอบกลับที่กำหนดเองสำหรับเงื่อนไขข้อผิดพลาด AssignMessage ช่วยให้คุณสามารถกำหนดค่าการตอบกลับ HTTP ด้วยเพย์โหลด รหัสสถานะ HTTP ส่วนหัว และองค์ประกอบข้อความเหตุผล

ตัวอย่างด้านล่างแสดงการกำหนดค่านโยบาย AssignMessage ตามปกติ

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

คุณใช้นโยบายนี้ใน FaultRule ได้แล้ว ดูวิธีที่คุณใช้อ้างอิง AssignMessage นโยบายตามชื่อใน FaultRule:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

เมื่อคุณทำให้การกำหนดค่าข้างต้นใช้งานได้ พร็อกซี API จะบังคับใช้นโยบาย AssignMessage เรียกใช้ fault_invalidkey ทุกครั้งที่แอปแสดงคีย์ API ที่ไม่ถูกต้อง

คุณสามารถใช้หลายนโยบายใน FaultRule ตามตัวอย่างต่อไปนี้

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

นโยบายจะทำงานตามลำดับที่กำหนด ตัวอย่างเช่น คุณสามารถใช้ นโยบายการบันทึกข้อความ นโยบาย ExtractVariable และ นโยบาย AssignMessage หรือนโยบายอื่นๆ ใน FaultRule โปรดทราบว่าการประมวลผล FaultRule จะหยุดทันทีในกรณีต่อไปนี้ เกิดขึ้น:

• นโยบายใน FaultRule ทำให้เกิดข้อผิดพลาด
• นโยบายใน FaultRule เป็นประเภท RaiseFault

คำจำกัดความของ ส่งกลับข้อความแสดงข้อผิดพลาดที่กำหนดเองจาก FaultRule

ตามแนวทางปฏิบัติที่ดีที่สุด คุณควรกำหนดการตอบกลับข้อผิดพลาดที่ชัดเจนจาก API ด้วยวิธีนี้ คุณจะให้ข้อมูลที่เป็นประโยชน์และสอดคล้องกันแก่ลูกค้า

ตัวอย่างนโยบาย AssignMessage ต่อไปนี้ใช้ <Payload> <StatusCode> และ <ReasonPhase> เพื่อกำหนดแท็กที่กำหนดเอง การตอบกลับข้อผิดพลาดที่ส่งกลับไปยังไคลเอ็นต์เมื่อพบข้อผิดพลาด invalidApiKey (ดู FaultRules ก่อนหน้า) ตัวอย่าง)

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. 
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

คำตอบนี้รวมถึง

• เพย์โหลดที่มีข้อความแสดงข้อผิดพลาดและอีเมลสำหรับติดต่อทีมสนับสนุน
• รหัสสถานะ HTTP ที่แสดงผลในการตอบกลับ
• วลีเหตุผล ซึ่งเป็นคำอธิบายสั้นๆ เกี่ยวกับข้อผิดพลาด

การสร้าง DefaultFaultRule

DefaultFaultRule จะทํางานตัวแฮนเดิลข้อยกเว้นสําหรับข้อผิดพลาดที่ไม่มีการจัดการอย่างชัดแจ้งจาก FaultRule อีกรายการ หากเงื่อนไขสำหรับ FaultRules ทั้งหมดไม่ตรงกับข้อผิดพลาด DefaultFaultRule จะจัดการข้อผิดพลาด เปิดใช้งานการจัดการข้อผิดพลาดเริ่มต้นด้วยการเพิ่ม <DefaultFaultRule> เป็นองค์ประกอบย่อยของ ProxyEndpoint หรือ TargetEndpoint

ตัวอย่างเช่น การกำหนดค่า TargetEndpoint ด้านล่างจะกำหนด DefaultFaultRule ที่เรียก นโยบายชื่อ ReturngenericError:

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

โดยปกติแล้วจะใช้ DefaultFaultRule เพื่อแสดงผลข้อความแสดงข้อผิดพลาดทั่วไปสำหรับกรณีที่ไม่คาดคิด เช่น ข้อความที่มีข้อมูลติดต่อฝ่ายสนับสนุนด้านเทคนิค ค่าเริ่มต้นนี้ ของ Google มีวัตถุประสงค์ 2 ประการในการให้ข้อมูลที่เป็นมิตรกับนักพัฒนาซอฟต์แวร์และ การสร้างความสับสนให้กับ URL แบ็กเอนด์หรือข้อมูลอื่นๆ ที่อาจถูกใช้เพื่อบุกรุกระบบ

ตัวอย่างเช่น คุณกำหนดนโยบาย AssignMessage ต่อไปนี้เพื่อแสดงข้อผิดพลาดทั่วไป

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

รวมองค์ประกอบ <AlwaysEnforce> ไว้ในส่วน <DefaultFaultRule> เพื่อเรียกใช้ DefaultFaultRule สําหรับข้อผิดพลาดทุกรายการ แม้ หากมีการดำเนินการ FaultRule อื่นแล้ว DefaultFaultRule จะเป็น FaultRule สุดท้ายเสมอ ที่จะเรียกใช้:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

การใช้ DefaultFaultRule อย่างหนึ่งคือการพิจารณาประเภทข้อผิดพลาดที่เกิดขึ้นเมื่อคุณ ไม่เช่นนั้น ก็ไม่สามารถระบุได้ ตัวอย่างเช่น พร็อกซี API ของคุณล้มเหลวเนื่องจากข้อผิดพลาดที่คุณ ไม่สามารถระบุได้ ใช้ DefaultFaultRule เพื่อเรียกใช้นโยบาย AssignMessage ต่อไปนี้ ช่วงเวลานี้ นโยบายจะเขียนค่า fault.name ลงในส่วนหัวชื่อ DefaultFaultHeader ในการตอบกลับ:

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

จากนั้นคุณจะดูส่วนหัวในเครื่องมือการติดตาม Edge หรือในการตอบสนองเพื่อดูสาเหตุที่ทำให้เกิด

กำลังเพิ่มการบันทึกข้อความลงใน PostClientFlow

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

การจัดการข้อผิดพลาดด้านนโยบายภายในขั้นตอนปัจจุบัน

ตัวอย่างที่แสดงจนถึงตอนนี้ใช้ FaultRule ใน ProxyEndpoint หรือ TargetEndpoint เพื่อจัดการ ข้อผิดพลาดใดๆ เกี่ยวกับนโยบายเป็นส่วนหนึ่งของสถานะข้อผิดพลาด เนื่องจากค่าเริ่มต้นของ องค์ประกอบ continueOnError ของนโยบายคือ false ซึ่งหมายความว่าเมื่อ เกิดข้อผิดพลาดในนโยบาย ตัวควบคุมจะไปยังสถานะข้อผิดพลาด เมื่ออยู่ในสถานะข้อผิดพลาด คุณจะ ไม่สามารถเปลี่ยนการควบคุมกลับไปเป็นไปป์ไลน์ปกติได้ และโดยปกติแล้วคุณจะแสดงข้อผิดพลาดบางอย่าง ไปยังแอปการโทร

อย่างไรก็ตาม หากคุณตั้งค่าองค์ประกอบ continueOnError เป็น true สำหรับ โดยนโยบาย การควบคุมจะยังอยู่ในขั้นตอนปัจจุบัน และนโยบายถัดไปในไปป์ไลน์จะทำงานหลังจาก นโยบายที่ทำให้เกิดข้อผิดพลาด ข้อดีในการจัดการกับข้อผิดพลาดในขั้นตอนปัจจุบันคือคุณสามารถ อาจมีวิธีกู้คืนจากข้อผิดพลาดเพื่อดำเนินการตามคำขอให้เสร็จสมบูรณ์

ที่แสดงด้านล่างคือ นโยบาย VerifyAPIKey ที่มีชื่อว่า verify-api-key พร้อมด้วย ตั้งค่าองค์ประกอบ continueOnError เป็น true:

<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

หากคีย์ API ขาดหายไปหรือไม่ถูกต้อง นโยบาย VerifyAPIKey จะตั้งค่าฟิลด์ ตัวแปร oauthV2.verify-api-key.failed เป็น true แต่กำลังประมวลผล จะดำเนินการต่อไปในขั้นตอนปัจจุบัน

จากนั้นเพิ่มนโยบาย VerifyAPIKey เป็นขั้นตอนใน PreFlow ของ ProxyEndpoint ดังนี้

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>      
</ProxyEndpoint>  

สังเกตว่าขั้นตอนถัดไปใน PreFlow ใช้เงื่อนไขเพื่อทดสอบการมีอยู่ของ หากเกิดข้อผิดพลาดในนโยบาย VerifAPIKey นโยบายที่ชื่อว่า ดำเนินการตามนโยบาย FaultInFlow มิฉะนั้น นโยบาย FaultInFlow ข้าม นโยบาย FaultInFlow ทำอะไรได้หลายอย่าง เช่น การบันทึกข้อผิดพลาด พยายามแก้ไขข้อผิดพลาด หรือดำเนินการอย่างอื่น

การทริกเกอร์ข้อผิดพลาดโดยใช้ RaiseFault นโยบาย

คุณใช้นโยบาย RaiseFault ได้ทุกเมื่อในโฟลว์เพื่อให้เกิดข้อผิดพลาด เมื่อ นโยบาย RaiseFault จะดําเนินการ และจะสิ้นสุดโฟลว์ปัจจุบันและโอนการควบคุมไปยังข้อผิดพลาด

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

เมื่อนโยบาย RaiseFault ทริกเกอร์ข้อผิดพลาด คุณสามารถใช้ FaultRule และเงื่อนไขต่อไปนี้ได้ เพื่อประมวลผล

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

โปรดทราบว่าเงื่อนไขจะทดสอบข้อผิดพลาดที่ชื่อ RaiseFault RaiseFault นโยบายจะกำหนดค่า fault.name เป็น RaiseFault เสมอ

การจัดการรหัสข้อผิดพลาด HTTP ที่กำหนดเอง จากเซิร์ฟเวอร์เป้าหมาย

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

โดยค่าเริ่มต้น Edge จะถือว่าโค้ดตอบกลับ HTTP ในช่วง 1xx-3xx เป็น "สำเร็จ" และ HTTP โค้ดตอบกลับในช่วง 4xx-5xx เป็น "ล้มเหลว" ซึ่งหมายความว่าการตอบสนองใดๆ จากแบ็กเอนด์ บริการที่มีรหัสตอบกลับ HTTP 4xx-5xx จะเรียกสถานะข้อผิดพลาดโดยอัตโนมัติ จากนั้น แสดงข้อความแสดงข้อผิดพลาดไปยังไคลเอ็นต์ที่ส่งคำขอโดยตรง

คุณสร้างตัวแฮนเดิลที่กำหนดเองสำหรับโค้ดตอบกลับ HTTP ใดก็ได้ ตัวอย่างเช่น คุณอาจไม่ต้องการ จัดการโค้ดตอบกลับ HTTP ทั้งหมดในช่วง 4xx-5xx เป็น "ล้มเหลว" แต่เพียง 5xx หรือคุณอาจต้องการ เพื่อแสดงผลข้อความแสดงข้อผิดพลาดที่กำหนดเองสำหรับรหัสตอบกลับ HTTP 400 และ 500

ในตัวอย่างถัดไป คุณใช้พร็อพเพอร์ตี้ success.codes เพื่อกำหนดค่าพารามิเตอร์ TargetEndpoint จะถือว่าโค้ดตอบกลับ HTTP 400 และ 500 เป็นโค้ดสําเร็จรูป รวมถึง HTTP เริ่มต้น เมื่อถือว่าโค้ดเหล่านั้นประสบผลสำเร็จ TargetEndpoint จึงจะเริ่มประมวลผลฟิลด์ ข้อความตอบกลับ แทนการเรียกใช้สถานะข้อผิดพลาด:

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

ดังที่คุณเห็นในตัวอย่างนี้ คุณสามารถใช้ไวลด์การ์ดในการตั้งค่าพร็อพเพอร์ตี้ success.codes เป็นช่วงของ มูลค่า

การตั้งค่าพร็อพเพอร์ตี้ success.codes จะเขียนทับ ค่าเริ่มต้น ดังนั้นหากคุณต้องการเพิ่มรหัส HTTP 400 ลงในรายการความสำเร็จเริ่มต้น รหัส ให้ตั้งค่าคุณสมบัตินี้เป็น

<Property name="success.codes">1xx,2xx,3xx,400</Property>

แต่หากคุณต้องการให้ถือว่ารหัส HTTP 400 เป็นรหัสความสำเร็จเท่านั้น ให้กำหนดพร็อพเพอร์ตี้ดังนี้

<Property name="success.codes">400</Property>

ตอนนี้คุณสามารถกำหนดตัวแฮนเดิลที่กำหนดเองสำหรับรหัสตอบกลับ HTTP 400 และ 500 เพื่อแสดงผลรหัสที่กำหนดเอง ข้อความตอบกลับไปยังแอปที่ขอ TargetEndpoint ต่อไปนี้ใช้นโยบายที่ชื่อ ReturnError เพื่อจัดการโค้ดตอบกลับ HTTP 400 และ 500:

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

การกำหนดค่า TargetEndpoint จะทำให้นโยบายที่ชื่อ ReturnError จัดการ การตอบสนองเมื่อใดก็ตามที่ TargetEndpoint พบรหัสการตอบกลับ HTTP 400 หรือ 500

การจัดหมวดหมู่ข้อผิดพลาด

บริการ API จะจัดระเบียบข้อผิดพลาดออกเป็นหมวดหมู่และหมวดหมู่ย่อยต่อไปนี้

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

• เหตุผล
• แอตทริบิวต์ที่กำหนดเองที่ผู้ใช้กำหนด