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

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

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

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

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

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

วิดีโอ

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

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

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

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

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

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

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

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

สำหรับสถานการณ์ที่ไม่มีข้อผิดพลาดโดยอัตโนมัติ คุณอาจต้องแสดงข้อผิดพลาดที่กำหนดเอง เช่น หากการตอบกลับมีคำว่า "ไม่พร้อมใช้งาน" หรือรหัสสถานะ 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 ในส่วนนโยบาย RaiseFault เทียบกับนโยบาย RaiseFault

ดูตัวอย่างเพิ่มเติมได้ที่โพสต์เหล่านี้ในฟอรัมชุมชน Apigee

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

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

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

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

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

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

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

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

ตรวจสอบ FaultRule

ในสถานะข้อผิดพลาด พร็อกซี 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 ที่สามารถตั้งค่าเพย์โหลดและส่วนหัว 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> แต่ละส่วนอย่างน้อย 1 ส่วน 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>

ข้อมูลสำคัญ

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

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

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

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

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

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

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

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

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

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

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

3. หากไม่มีการดำเนินการ FaultRule จะเรียกใช้ <DefaultFaultRule> หากมี

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

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

การประเมิน ProxyEndpoint FaultRule จะอยู่จากล่างขึ้นบน ดังนั้นให้เริ่มอ่านที่ 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 FaultRule จะอยู่จากบนลงล่าง ดังนั้นให้เริ่มอ่านที่ 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 เพื่อจัดรูปแบบการตอบกลับแอปไคลเอ็นต์ จากนั้นจึงบันทึกข้อความด้วยนโยบาย MessageLในเร็วๆ นี้ นโยบายจะทำงานตามลำดับที่คุณป้อน (จากบนลงล่างใน XML)

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

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

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

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

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

ตำแหน่งที่กำหนด FaultRule: ProxyEndpoint หรือ TargetEndpoint

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

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

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

FaultRule กับนโยบาย 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

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

• นโยบาย RaiseFault: raisefault.failed (เหมือนกับนโยบาย RaiseFault ทั้งหมด)
• นโยบาย ConfirmAPIKey: 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 ใดที่พร้อมใช้งาน

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

• เงื่อนไข: การอ้างอิงเงื่อนไข รวมถึงตัวแปรและเงื่อนไขสำหรับโฟลว์

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

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

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

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

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

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

  จากนั้นใช้เงื่อนไขขั้นตอนภายในหากต้องการการควบคุมข้อผิดพลาดที่ละเอียดกว่านี้ ตัวอย่างเช่น หากคุณบังคับใช้ทั้งโควต้านักพัฒนาแอปแต่ละรายและโควต้าทั่วโลกด้วยนโยบาย 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>
  

• เพิ่ม FaultRULE ที่ข้อผิดพลาดจะเกิดขึ้น (ฝั่งไคลเอ็นต์ <ProxyEndpoint> หรือด้านเป้าหมาย <TargetEndpoint>) ใส่ FaultRule สำหรับแต่ละนโยบายที่ปรากฏในแต่ละตำแหน่ง
• ใน FaultRule คุณสามารถบังคับใช้นโยบายประเภทใดก็ได้ที่แสดงข้อความไปยังแอปไคลเอ็นต์ ซึ่งนโยบาย AssignMessage เหมาะสำหรับกรณีนี้ นอกจากนี้ ให้พิจารณาบันทึกข้อความด้วยนโยบาย MessageLogging หากต้องการติดตามข้อผิดพลาด
• เมื่อใช้นโยบาย RaiseFault ร่วมกับ FaultRule ให้ประสานข้อมูลการตอบกลับที่ส่งกลับเมื่อทั้งนโยบาย RaiseFault และข้อมูล FaultRule ส่งกลับข้อมูล ตัวอย่างเช่น หากนโยบาย RaiseFault รีเซ็ตรหัสสถานะ HTTP คุณก็ไม่ต้องรีเซ็ตรหัสสถานะ HTTP ปัญหาร้ายแรงที่สุดที่อาจเกิดขึ้นได้คือระบบส่งรหัสสถานะเริ่มต้นกลับไปยังแอปไคลเอ็นต์
• การเรียกใช้ <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 ได้

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

การเพิ่มนโยบายลงใน FaultRule

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

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

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

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

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

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

<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> เป็นองค์ประกอบย่อยของ 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>

โดยทั่วไปค่าเริ่มต้นFaultRule จะใช้เพื่อแสดงข้อความแสดงข้อผิดพลาดทั่วไปสำหรับข้อผิดพลาดที่ไม่คาดคิด เช่น ข้อความที่มีข้อมูลติดต่อสำหรับฝ่ายสนับสนุนด้านเทคนิค การตอบกลับเริ่มต้นนี้มีจุดประสงค์คู่ในการมอบข้อมูลที่เป็นมิตรกับนักพัฒนาแอป ในขณะเดียวกันก็สร้างความสับสนให้กับ 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 อื่นไปแล้วก็ตาม โดยค่าเริ่มต้น FaultRule จะเป็น 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 เป็นขั้นตอนเดียวที่จะดำเนินการหลังจากพร็อกซีเข้าสู่สถานะข้อผิดพลาด มีเพียงนโยบาย MessageLoking จะแนบกับขั้นตอนนี้ได้ ซึ่งระบบจะดำเนินการหลังจากส่งการตอบกลับ กลับไปยังไคลเอ็นต์ แม้ว่าในทางเทคนิคแล้ว การแนบนโยบาย MessageLในเร็วๆ นี้จะไม่ใช่การจัดการข้อผิดพลาด แต่คุณก็ใช้นโยบายนี้เพื่อบันทึกข้อมูลในกรณีที่เกิดข้อผิดพลาดได้ เนื่องจากระบบจะดำเนินการไม่ว่าพร็อกซีจะสำเร็จหรือล้มเหลวก็ตาม คุณสามารถใส่นโยบายการบันทึกข้อความใน PostClientFlow ได้ และรับประกันได้ว่าจะมีการใช้นโยบายดังกล่าวเสมอ

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

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

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

ด้านล่างนี้เป็นนโยบาย ConfirmAPIKey ที่มีชื่อว่า 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 หรือคีย์ไม่ถูกต้อง นโยบาย ConfirmAPIKey จะตั้งค่าตัวแปร oauthV2.verify-api-key.failed เป็น true แต่การประมวลผลจะดำเนินการต่อในขั้นตอนปัจจุบัน

จากนั้นเพิ่มนโยบาย ConfirmAPIKey เป็นขั้นตอนใน 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 ในขั้นตอนเพื่อแก้ไขข้อบกพร่องและทดสอบ Fault Rules

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

คุณสร้างตัวแฮนเดิลที่กำหนดเองสำหรับโค้ดตอบกลับ HTTP ใดก็ได้ เช่น คุณอาจไม่ต้องการให้รหัสตอบกลับ HTTP ทั้งหมดในช่วง 4xx-5xx เป็น "failure" (ไม่สำเร็จ) แต่มีเพียง 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 จะจัดระเบียบข้อผิดพลาดเป็นหมวดหมู่และหมวดหมู่ย่อยต่อไปนี้

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

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