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

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

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

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

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

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

วิดีโอ

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

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

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

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

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

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

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

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

ตัวอย่าง

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ระบบจะทริกเกอร์กฎข้อผิดพลาดในสถานะข้อผิดพลาดเท่านั้น (เกี่ยวกับ continueOnError)

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

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

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

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

<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 ทั้งหมด)
• นโยบาย VerifyAPIKey: 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 โดยทั่วไปจะมีหลายขั้นตอนที่มีนโยบาย Assign Message (หรือนโยบายอื่นๆ) แต่ละขั้นตอนมีเงื่อนไขของขั้นตอน

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

  จากนั้นใช้เงื่อนไขขั้นตอนภายในหากต้องการควบคุมข้อผิดพลาดแบบละเอียดยิ่งขึ้น เช่น หากคุณบังคับใช้ทั้งโควต้าสำหรับนักพัฒนาแอปแต่ละรายและโควต้าส่วนกลางด้วยนโยบาย 2 รายการใน โฟลว์คำขอ ให้ตั้งค่าเงื่อนไข FaultRule "ด้านนอก" เพื่อให้ทริกเกอร์เมื่อเกิดQuotaViolationข้อผิดพลาด (ซึ่งจะเกิดขึ้นเมื่อโควต้าเกินในทั้ง 2 กรณี) จากนั้น ตั้งค่าเงื่อนไขของขั้นตอนเพื่อประเมิน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 เหมาะสำหรับกรณีนี้ นอกจากนี้ คุณยังอาจพิจารณาบันทึกข้อความด้วยนโยบายการบันทึกข้อความหากต้องการติดตามข้อผิดพลาด
• เมื่อใช้นโยบาย RaiseFault ร่วมกับ FaultRules ให้ประสานงานข้อมูลการตอบกลับ ที่ส่งกลับเมื่อทั้งนโยบาย RaiseFault และ FaultRule ส่งคืนข้อมูล ตัวอย่างเช่น หากนโยบาย RaiseFault รีเซ็ตรหัสสถานะ HTTP อย่าให้ FaultRule รีเซ็ต รหัสสถานะ ปัญหาใหญ่ที่สุดที่อาจเกิดขึ้นคือระบบจะแสดงรหัสสถานะเริ่มต้นไปยังแอปไคลเอ็นต์
• <DefaultFaultRule> การดำเนินการ:
  • หากต้องการให้ <DefaultFaultRule> ทำงานเสมอเมื่อไม่มี FaultRule อื่น ทำงาน ให้ไม่ต้องใส่ <Condition> ใน FaultRule นั้น
  • หากต้องการให้ <DefaultFaultRule> ทำงานเสมอแม้ว่า FaultRule อื่นจะทำงานอยู่ ให้เพิ่มองค์ประกอบย่อย <AlwaysEnforce>true</AlwaysEnforce>

รูปแบบสำหรับ การจัดการข้อผิดพลาดแบบรวมศูนย์ที่นำกลับมาใช้ใหม่ได้

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

รูปแบบการจัดการข้อผิดพลาดสำหรับพร็อกซี Apigee

การสร้าง FaultRules

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

หากสร้าง FaultRules ใน 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>

นโยบายจะทำงานตามลำดับที่กำหนด เช่น คุณสามารถใช้นโยบาย MessageLogging, นโยบาย ExtractVariables, นโยบาย 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 อื่น หากเงื่อนไขของ FaultRule ทั้งหมดไม่ตรงกับข้อผิดพลาด 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 จะใช้เพื่อแสดงข้อความแสดงข้อผิดพลาดทั่วไปสำหรับข้อผิดพลาดที่ไม่คาดคิด เช่น ข้อความที่มีข้อมูลติดต่อสำหรับการสนับสนุนด้านเทคนิค การตอบกลับเริ่มต้นนี้มีจุดประสงค์ 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 เป็นโฟลว์เดียวที่จะดำเนินการหลังจากที่พร็อกซีเข้าสู่สถานะข้อผิดพลาด เฉพาะนโยบายการบันทึกข้อความเท่านั้นที่แนบกับโฟลว์นี้ได้ ซึ่งจะดำเนินการ หลังจากส่งการตอบกลับ กลับไปยังไคลเอ็นต์ แม้ว่าการแนบนโยบายการบันทึกข้อความกับโฟลว์นี้จะไม่ใช่การจัดการข้อผิดพลาดในทางเทคนิค แต่คุณก็ใช้เพื่อบันทึกข้อมูลในกรณีที่เกิดข้อผิดพลาดได้ เนื่องจากระบบจะ เรียกใช้ไม่ว่าพร็อกซีจะสำเร็จหรือไม่ก็ตาม คุณจึงวางนโยบายการบันทึกข้อความ ไว้ใน 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 หรือคีย์ API ไม่ถูกต้อง VerifyAPIKey policy จะตั้งค่าตัวแปร 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 จัดระเบียบข้อผิดพลาดเป็นหมวดหมู่และหมวดหมู่ย่อยต่อไปนี้

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

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