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

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

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

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

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

ส่วนนี้จะอธิบายตรรกะที่ 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>

ลำดับกฎข้อบกพร่อง

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

ลองมาดูอีกตัวอย่างหนึ่งกัน หากนโยบาย 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> ระดับกฎไว้ใน <DefaultFaultRule> หากต้องการเรียกใช้นโยบายภายใน <DefaultFaultRule>แบบมีเงื่อนไข ให้วาง <Condition> ไว้ในองค์ประกอบย่อย <Step>
  • หากต้องการให้ <DefaultFaultRule> ทำงานเสมอแม้ว่า FaultRule อื่นจะทำงานแล้ว ให้เพิ่มองค์ประกอบย่อย <AlwaysEnforce>true</AlwaysEnforce>

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

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

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

การสร้าง FaultRules

หากต้องการเพิ่ม FaultRule คุณต้องแก้ไขการกำหนดค่า XML ของ ProxyEndpoint หรือ TargetEndpoint คุณสามารถใช้ UI ของ Edge เพื่อทำการแก้ไขนี้ในบานหน้าต่างโค้ดของมุมมองพัฒนาสำหรับพร็อกซี 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>

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

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

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