Xử lý lỗi

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến Tài liệu về Apigee X. thông tin

Nhiều tình trạng lỗi có thể phát sinh trong khi proxy API đang phân phát yêu cầu từ ứng dụng. Cho ví dụ: các proxy API có thể gặp sự cố mạng khi giao tiếp với các dịch vụ phụ trợ, có thể đưa ra thông tin đăng nhập đã hết hạn, tin nhắn yêu cầu có thể có định dạng không chính xác, v.v. .

Khi xảy ra lỗi sau khi ứng dụng khách gọi proxy API, thông báo lỗi sẽ được trả về khách hàng. Theo mặc định, máy khách thường nhận được thông báo lỗi khó hiểu mà không có thông tin chi tiết hoặc hướng dẫn. Nhưng nếu bạn muốn thay thế thông báo lỗi mặc định bằng các thông báo tuỳ chỉnh hữu ích hơn và thậm chí làm phong phú chúng bằng những thứ như tiêu đề HTTP bổ sung, bạn cần thiết lập lỗi tuỳ chỉnh xử lý trong Edge.

Tính năng xử lý lỗi tuỳ chỉnh cũng cho phép bạn thêm chức năng như ghi nhật ký thông báo bất cứ khi nào một lỗi xảy ra.

Trước khi chúng tôi nói về cách triển khai xử lý lỗi tuỳ chỉnh trong proxy API, hữu ích để tìm hiểu cách lỗi xảy ra và cách các proxy API phản ứng với lỗi.

Video

Hãy xem các video sau đây để tìm hiểu thêm về cách xử lý lỗi.

Video Mô tả
Giới thiệu về xử lý lỗi và luồng lỗi Tìm hiểu về cách xử lý lỗi và điều gì xảy ra khi lỗi xảy ra trong proxy API.
Xử lý lỗi sử dụng quy tắc lỗi Tìm hiểu cách xử lý lỗi bằng quy tắc lỗi.
Tăng số liệu tuỳ chỉnh lỗi bằng chính sách RaiseFault Nêu lỗi tuỳ chỉnh trong thời gian chạy API bằng chính sách RaiseFault.
Xác định lỗi quy tắc trong proxy API và điểm cuối mục tiêu Xác định các quy tắc lỗi trong proxy API và điểm cuối mục tiêu, đồng thời tìm hiểu sự khác biệt.
Tìm hiểu thứ tự thực thi của các quy tắc lỗi Nắm được thứ tự thực thi của các quy tắc lỗi trong proxy và đích API điểm cuối.
Xác định ứng dụng mặc định quy tắc lỗi Xác định quy tắc lỗi mặc định để xử lý các lỗi chung trong API.

Cách lỗi xảy ra

Trước tiên, chúng ta sẽ chỉ đề cập đến cách xảy ra lỗi. Việc biết được lỗi xảy ra như thế nào sẽ giúp bạn lập kế hoạch cho các tình huống khác nhau mà bạn muốn triển khai cách xử lý lỗi tuỳ chỉnh.

Lỗi tự động

Proxy API tự động gửi lỗi trong các trường hợp sau:

  • Một chính sách gửi ra thông báo lỗi. Ví dụ: nếu lệnh gọi API gửi một khoá đã hết hạn, thì Chính sách VerifyAPIKey tự động gửi lỗi; hoặc liệu số lệnh gọi API vượt quá một giới hạn nhất định, thì chính sách Hạn mức hoặc chính sách của Scooter sẽ báo lỗi. (Xem Tài liệu tham khảo về lỗi chính sách để biết các loại lỗi mà chính sách có thể gửi).
  • Đã xảy ra sự cố trong luồng thông báo proxy API, chẳng hạn như lỗi định tuyến.
  • Đã xảy ra lỗi phụ trợ, chẳng hạn như lỗi HTTP do lỗi cấp giao thức, TLS/SSL lỗi hoặc dịch vụ đích không khả dụng.
  • Đã xảy ra lỗi ở cấp hệ thống, chẳng hạn như ngoại lệ hết bộ nhớ.

Để biết thêm thông tin về những lỗi này, hãy xem phần Phân loại lỗi trong chủ đề này.

Lỗi tuỳ chỉnh

Trong trường hợp không có lỗi tự động, bạn có thể gửi một lỗi tuỳ chỉnh; với ví dụ: nếu phản hồi chứa từ "không có" hoặc nếu mã trạng thái HTTP lớn hơn so với 201. Để thực hiện việc này, hãy thêm chính sáchRaiseFault vào vị trí thích hợp trong luồng proxy API.

Bạn có thể thêm chính sách RaiseFault vào luồng proxy API giống như cách bạn thực hiện với bất kỳ chính sách nào khác. Trong ví dụ về cấu hình proxy sau đây, chính sách Raise-Fault-1 sẽ đi kèm với phản hồi TargetEndpoint. Nếu từ "không có" xuất hiện trong phản hồi từ mục tiêu thì chính sách RaiseFault sẽ được thực thi và báo lỗi.

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

Việc này nhằm cho bạn biết rằng bạn có thể gửi các lỗi tuỳ chỉnh. Chúng ta sẽ đi sâu hơn về Chính sách RaiseFault trong FaultRules so với chính sách RaiseFault .

Để biết thêm ví dụ, hãy xem các bài đăng sau trên Diễn đàn cộng đồng Apigee:

Proxy API làm gì khi xảy ra lỗi

Dưới đây là điều sẽ xảy ra khi proxy gửi lỗi.

Thoát khỏi quy trình proxy

Khi một proxy API gặp lỗi, bất kể lỗi xảy ra như thế nào, proxy đó sẽ thoát khỏi quy trình luồng thông thường, nhập trạng thái lỗi và trả về một thông báo lỗi cho ứng dụng khách. Sau khi proxy API nhập trạng thái lỗi, nó không thể đưa quá trình xử lý trở lại quy trình luồng bình thường.

Ví dụ: Giả sử một proxy API có các chính sách theo thứ tự sau trong ProxyEndpoint yêu cầu:

  1. Xác minh khoá API
  2. Hạn mức
  3. JSON sang XML

Nếu xảy ra lỗi trong quá trình xác minh khoá API, proxy API sẽ chuyển sang trạng thái lỗi. Chiến lược phát hành đĩa đơn Các chính sách Hạn mức và JSON sang XML không được thực thi, proxy sẽ không chuyển đến TargetEndpoint và một thông báo lỗi sẽ được trả về cho ứng dụng khách.

Kiểm tra lỗi FaultRules

Ở trạng thái lỗi, proxy API cũng kiểm tra sự hiện diện của các hàm sau (theo thứ tự) trong Cấu hình proxy API trước khi trả về một thông báo lỗi mặc định cho ứng dụng:

  1. Phần <FaultRules> chứa logic để kích hoạt thông báo lỗi tuỳ chỉnh (và các chính sách khác) dựa trên điều kiện cụ thể mà bạn định nghĩa.
  2. Phần <DefaultFaultRule>, kích hoạt chế độ mặc định trong các trường hợp sau:
    • Không có <FaultRules> nào được xác định.
    • Không có <FaultRules> hiện có nào được thực thi.
    • Phần tử <AlwaysEnforce> được đặt thành true.

Về bản chất, proxy API cho bạn cơ hội trả về một thông báo lỗi tuỳ chỉnh và kích hoạt logic khác. Nếu proxy không tìm thấy mục nào trong số đó hoặc các mục này tồn tại nhưng không có mục tuỳ chỉnh đã kích hoạt lỗi, proxy sẽ gửi tin nhắn mặc định do Edge tạo riêng.

Ví dụ về cách xử lý lỗi đơn giản

Hãy bắt đầu bằng một ví dụ đơn giản, trong đó lệnh gọi đến proxy API không chứa API bắt buộc . Theo mặc định, sau đây là phản hồi được trả về ứng dụng:

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"}}}

Người dùng API của bạn có thể tìm ra thông báo lỗi, nhưng họ có thể không tìm ra. Và nhiều lựa chọn mặc định tinh vi hơn và khó giải mã hơn.

Là nhà phát triển API, bạn có quyền thay đổi thông báo này để đáp ứng nhu cầu của bất kỳ ai cuối cùng sẽ nhận được thông báo lỗi, cho dù đó là nhà phát triển ứng dụng iOS hay kiểm thử nội bộ có các yêu cầu định dạng thông báo lỗi riêng.

Dưới đây là ví dụ cơ bản về cách bạn sẽ tạo thông báo lỗi tuỳ chỉnh để xử lý lỗi này. Chiến dịch này cần 1) một chính sách xác định thông báo tuỳ chỉnh và 2) lỗi FaultRule thực thi chính sách khi proxy chuyển sang trạng thái lỗi.

1. Tạo một chính sách giúp xác định thông điệp tuỳ chỉnh.

Trước tiên, hãy tạo một chính sách định nghĩa thông báo lỗi tuỳ chỉnh. Bạn có thể sử dụng bất kỳ loại chính sách nào, chẳng hạn như SpecifyMessage policy (chính sách gán), có thể đặt một tải trọng và các tiêu đề HTTP tuỳ chọn như mã trạng thái và lý do. Gán tin nhắn là lựa chọn lý tưởng cho trường hợp này. Hộp cát về quyền riêng tư cho phép bạn kiểm soát tải trọng tin nhắn, thiết lập mã trạng thái HTTP khác, đặt cụm từ lý do HTTP khác và thêm tiêu đề HTTP.

Không đính kèm chính sách này vào bất kỳ quy trình nào trong proxy API. Chỉ cần tồn tại trong gói proxy. Để thực hiện việc này trong trình chỉnh sửa proxy giao diện người dùng quản lý, hãy chuyển đến thẻ Phát triển và trong Ngăn điều hướng rồi nhấp vào biểu tượng dấu + trên thanh Chính sách.

Việc này cho phép bạn tạo một chính sách mà không cần đính kèm chính sách đó vào một luồng trong proxy API. Một chính sách không được đính kèm vào bất kỳ luồng nào sẽ bị gắn cờ "phân tách" biểu tượng trong Danh sách chính sách, như bên cạnh chính sách về thông báo về khoá API như trong hình trước.

Sau đây là một ví dụ về AssignmentMessage chính sách:

  • Trả về thông báo JSON.
  • Đặt mã trạng thái HTTP (911, đây là một mã trạng thái rõ ràng không tồn tại chỉ để minh hoạ sự linh hoạt). Mã trạng thái sẽ xuất hiện trong tiêu đề HTTP.
  • Đặt cụm từ lý do HTTP (để thay thế cụm từ lý do "Không được phép" mặc định cho trường hợp này lỗi thiếu khoá API). Cụm từ lý do xuất hiện bên cạnh mã trạng thái trong HTTP .
  • Tạo và điền sẵn tiêu đề HTTP mới có tên là 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>

Khi chính sách này được thực thi, phản hồi cho ứng dụng sẽ có dạng như sau. So sánh phản hồi đó với phản hồi mặc định xuất hiện trước đó.

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."}

Đúng, điều này hơi ngớ ngẩn một chút nhưng sẽ cho bạn thấy điều có thể. Ít nhất thì bây giờ, nhà phát triển nhận được thông báo rằng họ đã quên bao gồm khoá API làm tham số truy vấn.

Nhưng chính sách này được thực thi như thế nào? Phần tiếp theo sẽ cho bạn thấy.

2. Tạo &lt;FaultRule&gt; để kích hoạt chính sách

Trong phần <ProxyEndpoint> hoặc <TargetEndpoint> của cấu hình proxy, bạn sẽ thêm một khối XML <FaultRules> có chứa một hoặc nhiều mục <FaultRule> riêng lẻ. Mỗi FaultRule biểu thị một mà bạn muốn xử lý. Trong ví dụ đơn giản này, chúng tôi sẽ chỉ sử dụng một FaultRule để hiển thị cho bạn bao gồm nó.

Bạn cũng nên thêm <DefaultFaultRule> để cung cấp lỗi chung tuỳ chỉnh nếu không có FaultRules nào được thực thi.

Ví dụ:

<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>

Điểm chính:

  • FaultRules được xác định trong ProxyEndpoint. Điều này rất quan trọng. Thông tin khác về việc đưa mẫu FaultRules trong ProxyEndpoint so với TargetEndpoint sau này.
  • <Name> – Tên chính sách cần thực thi. Tên xuất phát từ thuộc tính name của chính sách trên phần tử mẹ, như minh hoạ trong ví dụ về chính sách ở trên.

  • <Condition> – Edge đánh giá điều kiện và chỉ thực thi chính sách nếu điều kiện đó đúng. Nếu có nhiều FaultRules đánh giá thành true, Edge sẽ thực thi phương thức đầu tiên là giá trị true. (Lưu ý quan trọng: thứ tự mà FaultRules được đánh giá, từ trên xuống dưới hoặc từ dưới lên trên, khác nhau giữa TargetEndpoint và ProxyEndpoint như được mô tả trong Nhiều phần FaultRules và logic thực thi.) Nếu bạn không thêm điều kiện, lỗi FaultRule sẽ tự động được áp dụng. Tuy nhiên, đó không phải là phương pháp hay nhất. Mỗi FaultRule phải có .

  • <DefaultFaultRule> – Nếu không có FaultRule tuỳ chỉnh nào thì <DefaultFaultRule> được thực thi, gửi một lệnh gọi chung hơn tin nhắn tuỳ chỉnh thay vì tin nhắn khó hiểu do Edge tạo theo mặc định. Đáp <DefaultFaultRule> cũng có thể có <Condition>, nhưng trong hầu hết các trường hợp, bạn sẽ không bao gồm một mô-đun, bởi vì bạn muốn nó thực thi bất kể lần cuối cùng có nghỉ dưỡng.

    DefaultFaultRule thường được dùng để trả về thông báo lỗi chung cho bất kỳ lỗi không mong muốn. Ví dụ: một thư chứa thông tin liên hệ của hỗ trợ kỹ thuật. Phản hồi mặc định này phục vụ mục đích kép là cung cấp thông tin phù hợp với nhà phát triển, đồng thời làm rối mã nguồn của các URL phụ trợ hoặc các thông tin khác có thể bị dùng để xâm phạm hệ thống.

Nhiều lỗi và logic thực thi

Trong phần Ví dụ về xử lý lỗi đơn giản, chúng tôi đã sử dụng một ví dụ đơn giản về một FaultRule và điều kiện. Trong một dự án API thực tế, với tất cả các lỗi có thể xảy ra có thể xảy ra, có thể bạn sẽ có nhiều FaultRules và một DefaultFaultRule trong cả <ProxyEndpoint> và <TargetEndpoint>. Mặc dù vậy, cuối cùng, chỉ một FaultRule được thực thi khi proxy API chuyển sang trạng thái lỗi.

Phần này mô tả logic mà Edge sử dụng trong quá trình xử lý FaultRules, từ cách nó đến khi một FaultRule để thực thi theo mức độ "bên trong" Điều kiện bước được xử lý khi FaultRule của chúng được đã kích hoạt. Phần này cũng cung cấp hướng dẫn về thời điểm xác định FaultRules trong <ProxyEndpoint> so với <TargetEndpoint>, đồng thời mô tả mối quan hệ giữa FaultRules và chính sáchRaiseFault.

Thực thi FaultRules

Tóm lại, đây là logic mà Edge sử dụng khi proxy API chuyển sang trạng thái lỗi. Lưu ý rằng có sự khác biệt nhỏ giữa đánh giá FaultRules trong ProxyEndpoint so với Điểm cuối đích.

  1. Edge đánh giá FaultRules trong ProxyEndpoint hoặc TargetEndpoint, tuỳ thuộc vào nơi xảy ra lỗi:
    • ProxyEndpoint – Edge bắt đầu từ dưới cùng <FaultRule> trong XML cấu hình và đang hoạt động, đánh giá <Condition> của mỗi <FaultRule> ("bên ngoài" , chứ không phải "bên trong" <Step> điều kiện).
    • TargetEndpoint – Cạnh bắt đầu bằng đầu <FaultRule> trong XML cấu hình và đang hoạt động, đánh giá <Condition> của mỗi <FaultRule> ("bên ngoài" , chứ không phải "bên trong" <Step> điều kiện).
  2. Thực thi FaultRule đầu tiên có điều kiện là đúng. Nếu FaultRule có không có điều kiện nào, giá trị này là đúng theo mặc định.
    • Khi FaultRule được thực thi, tất cả các Bước bên trong FaultRule được đánh giá theo thứ tự, từ trên xuống dưới trong cấu hình XML. Các bước không có điều kiện sẽ tự động được thực thi (các chính sách được thực thi) và các Bước có <Condition> cho kết quả là "true" được thực thi (các điều kiện đánh giá là "false" không được thực thi).

    • Nếu FaultRule được thực thi, nhưng không có Bước nào trong FaultRule được thực thi (vì điều kiện đánh giá là "false"), thông báo lỗi mặc định do Edge tạo sẽ được trả về ứng dụng khách. <DefaultFaultRule> không được thực thi, vì Edge đã thực thi một lỗi FaultRule.

  3. Nếu không thực thi FaultRule nào, Edge sẽ thực thi <DefaultFaultRule>, nếu hiện tại.

Sau đây là ví dụ về nhận xét cùng dòng.

Thực thi ProxyEndpoint

Phần đánh giá về ProxyEndpoint FaultRules nằm từ dưới lên trên cùng nên hãy bắt đầu đọc ở phần cuối FaultRule trong mẫu sau và tìm cách tăng. Xem DefaultFaultRule sau cùng.

<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>

Thực thi TargetEndpoint

Phần đánh giá TargetEndpoint FaultRules nằm từ trên xuống dưới nên hãy bắt đầu đọc từ đầu FaultRule trong mẫu sau và cố gắng xử lý. Xem DefaultFaultRule sau cùng.

<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>

Thứ tự quy tắc lỗi

Như bạn có thể thấy trong ví dụ trước, thứ tự mà bạn đặt FaultRules là tuỳ thuộc vào việc lỗi xảy ra ở ProxyEndpoint hay Điểm cuối đích.

Ví dụ:

Thứ tự ProxyEndpoint Thứ tự TargetEndpoint

Trong ví dụ sau, vì việc đánh giá nằm từ dưới lên trên nên FaultRule 3 được thực thi, có nghĩa là FaultRules 2 và 1 không được đánh giá.

5. Lỗi quy tắc 1: FALSE

4. Lỗi quy tắc 2: TRUE

3. Lỗi quy tắc 3: TRUE

2. Lỗi quy tắc 4: FALSE

1. FaultRule: 5 FALSE

Trong ví dụ sau, vì việc đánh giá được sắp xếp từ trên xuống dưới nên FaultRule 2 được thực thi, có nghĩa là FaultRules 3, 4 và 5 không được đánh giá.

1. Lỗi quy tắc 1: FALSE

2. Lỗi quy tắc 2: TRUE

3. Lỗi quy tắc 3: TRUE

4. Lỗi quy tắc 4: FALSE

5. FaultRule: 5 FALSE

Chính sách cần bao gồm

Bạn có thể thực thi bất kỳ chính sách nào từ FaultRule bằng cách đặt chính sách đó vào Bước. Ví dụ: bạn có thể thực thi chính sách assignMessage để định dạng một phản hồi cho ứng dụng khách, sau đó ghi lại một thông báo bằng chính sách MessageLogging. Các chính sách được thực thi theo thứ tự bạn đặt ra (từ trên xuống dưới trong XML).

Các quy tắc lỗi CHỈ được kích hoạt khi ở trạng thái lỗi (về ContinueOnError)

Tiêu đề này có vẻ như đang lặp lại chính mình, nhưng có một điểm đặc biệt cần được lưu ý về lỗi proxy khiến proxy API chuyển sang trạng thái lỗi — hoặc thay vào đó, không nhập trạng thái lỗi: thuộc tính continueOnError trên .

Tóm lại: Proxy API đánh giá <FaultRules> và <DefaultFaultRule> chỉ khi proxy đã chuyển sang trạng thái lỗi. Đó có nghĩa là ngay cả khi điều kiện FaultRule được đánh giá là true, thì điều kiện đó sẽ không được kích hoạt nếu proxy hiện không ở trạng thái lỗi.

Tuy nhiên, dưới đây là ví dụ về một lỗi xảy ra và proxy không chuyển sang trạng thái lỗi. Bật bất kỳ chính sách nào, bạn đều có thể đặt một thuộc tính trên phần tử mẹ có tên là continueOnError. Thuộc tính đó rất quan trọng đối với quá trình xử lý lỗi, vì thuộc tính này xác định liệu hoặc nếu chính sách không thành công thì proxy sẽ không chuyển sang trạng thái lỗi. Trong hầu hết các trường hợp, bạn nên giữ lại mặc định continueOnError="false". Thao tác này sẽ đặt proxy ở trạng thái lỗi nếu không thành công và quá trình xử lý lỗi tuỳ chỉnh của bạn sẽ được kích hoạt. Tuy nhiên, nếu continueOnError="true" (ví dụ: nếu bạn không muốn một Dịch vụ gặp lỗi Chú thích để dừng thực thi proxy), proxy sẽ không chuyển sang trạng thái lỗi nếu đó không thành công và proxy sẽ không xem FaultRules của bạn.

Để biết thông tin về cách ghi nhật ký lỗi khi continueOnError="true", hãy xem phần Xử lý lỗi chính sách trong quy trình hiện tại.

Địa điểm để xác định FaultRules: ProxyEndpoint hoặc TargetEndpoint

Khi proxy API gặp lỗi, lỗi đó sẽ xảy ra trong phần <ProxyEndpoint> (yêu cầu từ hoặc phản hồi cho ứng dụng khách) hoặc trong <TargetEndpoint> (yêu cầu hoặc phản hồi từ dịch vụ đích). Bất cứ nơi đâu lỗi xảy ra là khi Edge tìm kiếm FaultRules.

Ví dụ: nếu máy chủ mục tiêu không hoạt động (mã trạng thái HTTP 503), proxy API sẽ hoạt động sang trạng thái lỗi trong phản hồi <TargetEndpoint> và proxy API thông thường sẽ không tiếp tục sang <ProxyEndpoint>. Nếu bạn đã xác định FaultRules chỉ trong <ProxyEndpoint>, nên họ sẽ không xử lý lỗi đó.

Sau đây là một ví dụ khác. Nếu chính sáchRaiseFault trên <ProxyEndpoint> phản hồi kích hoạt lỗi, FaultRule trong <TargetEndpoint> sẽ không nhận được thực thi.

FaultRules so với chính sách RaiseFault

Có vẻ như các quy tắc lỗi và chính sáchRaiseFault được hiển thị trên bề mặt như là những cách khác để thực hiện xử lý lỗi; và đúng theo một cách nào đó. Nhưng chúng cũng hoạt động cùng nhau. Chiến dịch này giải thích mối quan hệ giữa hai loại. Hiểu được mối quan hệ này sẽ giúp ích bạn sẽ thiết kế cách xử lý lỗi, đặc biệt nếu bạn muốn sử dụng cả hai.

Tóm lại:

  • Các quy tắc lỗi luôn được đánh giá khi proxy API nhập lỗi trạng thái.

  • Chính sách RaiseFault là cách đặt proxy API ở trạng thái lỗi khi mà lỗi mà lẽ ra sẽ không xảy ra.

    Ví dụ: nếu bạn muốn báo cáo lỗi nếu mã trạng thái HTTP trong phản hồi từ dịch vụ mục tiêu lớn hơn 200, hãy thêm chính sáchRaiseFault vào phản hồi của mình luồng. URL sẽ có dạng như sau:

    <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>

    Chính sách RaiseFault cũng sẽ gửi một thông báo lỗi đến ứng dụng.

Điều gì xảy ra khi chính sách RaiseFault kích hoạt lỗi, khiến proxy bị lỗi trạng thái nào có thể thực thi FaultRule? Có lúc bạn sẽ gặp một chút khó khăn. Nếu chính sách RaiseFault trả về một thông báo lỗi và lỗi FaultRule được kích hoạt và trả về một thông báo lỗi, dữ liệu nào sẽ được trả về ứng dụng khách?

  • Vì FaultRule hoặc DefaultFaultRule được thực thi sau chính sách RaiseFault, Dữ liệu phản hồi FaultRule sẽ thắng.
  • Dữ liệu phản hồi của chính sách RaiseFault (mã trạng thái, cụm từ lý do hoặc tải trọng tin nhắn) là được sử dụng nếu dữ liệu đó không được đặt bởi FaultRule hoặc DefaultFaultRule.
  • Nếu cả chính sách RaiseFault và FaultRule đều thêm tiêu đề HTTP tuỳ chỉnh, thì cả hai tiêu đề này đều được đưa vào nội dung phản hồi. Tên tiêu đề trùng lặp tạo ra một tiêu đề có nhiều giá trị.

Dưới đây là ví dụ về những gì được thiết lập theo chính sách RaiseFault và FaultRule và những gì được quay lại ứng dụng khách. Các mẫu được thiết kế để trình bày ngắn gọn, không phải là các phương pháp hay nhất.

Ứng dụng khách nhận được:

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

<- Chính sách về quy tắc lỗi thiết lập điều này:

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

<- Chính sách RaiseFault đặt ra điều này:

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

Điều kiện xây dựng

Các điều kiện là chìa khoá để thực thi FaultRule. Bạn tạo các điều kiện FaultRule theo cách tương tự bạn thực hiện cho các điều kiện khác trong Edge, chẳng hạn như đối với luồng có điều kiện hoặc điều kiện RaiseFault.

Để đưa phần còn lại của phần này vào ngữ cảnh, sau đây là một quy tắc lỗi mẫu có phần tử Điều kiện FaultRule và điều kiện Bước bên trong.

<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>

Các biến dành riêng cho chính sách các lỗi

Các biến fault.name và {policy_namespace}.{policy_name}.failed sẽ được cung cấp khi chính sách gửi lỗi.

fault.name

Khi một chính sách không thành công, hãy phát hiện lỗi trong một điều kiện bằng cách sử dụng fault.name biến. Ví dụ:

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

Tên lỗi sẽ xuất hiện trong thông báo lỗi mặc định. Ví dụ: trong các trường hợp sau, lỗi tên là FailedToResolveAPIKey. Trong trường hợp này, biến luồng được gọi là fault.name được đặt thành giá trị FailedToResolveAPIKey.

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

Do đó, điều kiện sẽ có dạng như sau:

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

Xem phần Lỗi chính sách tài liệu tham khảo để biết danh sách các lỗi chính sách.

{policy_workspace}.{policy_name}.failed

Biến *.failed sẽ dùng được khi chính sách không thành công. Đang theo dõi ví dụ về biến *.failed cho các chính sách. Đối với không gian tên chính sách, hãy xem các biến quy trình trong mỗi chủ đề tài liệu tham khảo về chính sách.

Các biến có sẵn khác

Khi proxy API chuyển sang trạng thái lỗi, các biến duy nhất có sẵn để sử dụng trong các điều kiện là:

  • Các biến của chính sách không thành công.
  • Các biến thông báo HTTP tồn tại tại thời điểm không thành công. Ví dụ: nếu lỗi là được gửi trong phản hồi, thì FaultRule trong <TargetEndpoint> có thể sử dụng HTTP dữ liệu response.status.code, message.content, error.content, v.v. Hoặc nếu Chính sách về hạn mức không thành công, bạn có thể sử dụng biến ratelimit.{quota_policy_name}.exceed.count. Sử dụng công cụ Theo dõi và chính sách các chủ đề tham khảo để giúp bạn xác định biến và dữ liệu HTTP nào có sẵn.

Thông tin khác

Các phương pháp hay nhất để xử lý lỗi

Xử lý lỗi là một nhiệm vụ thiết kế kiến trúc chính để phát triển proxy API. Quan trọng là dành thời gian tìm hiểu cách thức và thời điểm bạn xử lý lỗi, hãy xác định xem và thiết kế định dạng thông báo lỗi. Sau khi (hoặc khi) bạn tìm ra những điều đó, thì hãy áp dụng các phương pháp hay nhất này để triển khai xử lý lỗi.

Sau đây là một số phương pháp hay nhất khi thiết kế và xây dựng cách xử lý lỗi:

  • Đối với mỗi FaultRule, hãy cung cấp một "bên ngoài" <Condition> (đồng cấp với phần tử <Step>). Các quy tắc lỗi không có điều kiện bên ngoài nào tự động đánh giá thành true. "Bên trong" Các điều kiện bước không được sử dụng để xác định xem FaultRule có đúng hay không hoặc sai. Các điều kiện bước chỉ được đánh giá sau khi Edge thực thi FaultRule có chứa các điều kiện đó. Trong FaultRule, thông thường sẽ có nhiều Bước với chính sách Chỉ định thông báo (hoặc các chính sách khác), mỗi chiến dịch có một Điều kiện bước.

  • Để xử lý lỗi trong nhiều chính sách cùng loại (ví dụ: nhiều Hạn mức ), hãy tạo một FaultRule cho mỗi lỗi chính sách mà bạn có thể nhận được. Ví dụ: tạo FaultRule cho từng lỗi có thể xảy ra trong chính sách Hạn mức, chẳng hạn như QuotaViolation, InvalidMessageWeight StartTimeNotSupported. (Xem Tài liệu tham khảo về lỗi chính sách để biết lỗi chính sách. Khi phát hiện các lỗi khác cần xử lý, bạn có thể quay lại sau đó và thêm chúng vào FaultRules. Bạn có thể lặp lại, dù việc này đòi hỏi triển khai lại proxy.) Phương pháp này cho phép bạn phát hiện cùng một loại lỗi bất kể chính sách sẽ gửi ra, giúp XML FaultRules của bạn trở nên hiệu quả.

    Sau đó, hãy sử dụng các điều kiện Bước bên trong nếu bạn cần kiểm soát lỗi chi tiết hơn. Ví dụ: nếu bạn đang áp dụng cả hạn mức cho nhà phát triển cá nhân và hạn mức trên toàn cầu thông qua hai chính sách trong luồng yêu cầu của bạn, đặt "bên ngoài" của bạn Điều kiện FaultRule được kích hoạt trên QuotaViolation lỗi (được gửi khi hạn mức vượt quá trong cả hai trường hợp). Sau đó đặt Điều kiện bước để đánh giá biến exceed.count ở cả hai hạn mức Google Cloud. Chỉ gửi lỗi liên quan đến khách hàng (lỗi vượt quá hạn mức dành cho nhà phát triển hoặc lỗi toàn hệ thống vượt quá hạn mức). Dưới đây là ví dụ về cấu hình này:

    <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>

    Để tìm hiểu ví dụ khác, hãy xem chuỗi bài đăng trong Cộng đồng Apigee.

  • Để xử lý lỗi khi bạn đang sử dụng một chính sách duy nhất thuộc một loại, hãy xem xét một lỗi duy nhất quy tắc được thực thi khi một chính sách đó không thành công và bao gồm nhiều bước ánh xạ đến từng lỗi có thể xảy ra. Thao tác này giúp XML của bạn hiệu quả bằng cách sử dụng một FaultRule (Quy tắc lỗi) duy nhất thay vì nhiều FaultRules (một quy tắc cho mỗi loại lỗi). Ví dụ:

    <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>
  • Thêm FaultRules sẽ xảy ra lỗi (phía máy khách <ProxyEndpoint> hoặc bên mục tiêu <TargetEndpoint>). Bao gồm FaultRules cho từng chính sách sẽ xuất hiện ở từng vị trí.
  • Trong FaultRules, bạn có thể thực thi bất kỳ loại chính sách nào có thể trả về thông báo cho ứng dụng khách . Bạn có thể dùng chính sách assignMessage là giải pháp lý tưởng cho việc này. Ngoài ra, hãy cân nhắc ghi nhật ký thông báo bằng chính sách MessageLogging nếu bạn muốn theo dõi lỗi.
  • Khi sử dụng chính sách RaiseFault cùng với FaultRules, hãy điều phối phản hồi dữ liệu được gửi lại khi cả chính sách RaiseFault và dữ liệu trả về FaultRule được gửi trả về. Cho ví dụ: nếu chính sách RaiseFault đặt lại mã trạng thái HTTP thì bạn đừng đặt lại FaultRule mã trạng thái. Điều tồi tệ nhất có thể xảy ra là mã trạng thái mặc định bị trả về ứng dụng khách.
  • Lần thực thi <DefaultFaultRule>:
    • Nếu bạn muốn <DefaultFaultRule> luôn thực thi khi không có FaultRule thực thi, không bao gồm <Condition>.
    • Nếu bạn muốn <DefaultFaultRule> luôn thực thi ngay cả khi một FaultRule đã thực thi, hãy thêm phương thức Phần tử con <AlwaysEnforce>true</AlwaysEnforce>.

Hình mở khoá cho xử lý lỗi tập trung và có thể tái sử dụng

Bài đăng sau đây trên thẻ Cộng đồng Apigee mô tả một quy trình để xử lý lỗi tập trung mà không cần trùng lặp mã:

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

Tạo FaultRules

Để thêm FaultRule, bạn cần chỉnh sửa cấu hình XML của ProxyEndpoint hoặc Điểm cuối đích. Bạn có thể sử dụng giao diện người dùng Edge để thực hiện chỉnh sửa này trong ngăn Code (Mã) của Phát triển khung hiển thị cho proxy API, hoặc chỉnh sửa tệp XML xác định ProxyEndpoint hoặc Điểm cuối đích.

Nếu bạn tạo FaultRules trong giao diện người dùng quản lý, trước tiên hãy tạo các chính sách mà bạn muốn thực thi, sau đó thêm chúng vào cấu hình FaultRule. (Bạn sẽ gặp lỗi trong giao diện người dùng nếu bạn cố lưu một FaultRule tham chiếu đến một chính sách chưa được tạo.)

Thêm chính sách vào FaultRule

Mặc dù bạn có thể đặt bất kỳ chính sách nào trong FaultRule, bạn thường sử dụng Chính sách GánTin để tạo thông báo phản hồi tuỳ chỉnh cho một điều kiện lỗi. PagingMessage cho phép bạn định cấu hình phản hồi HTTP với tải trọng, mã trạng thái HTTP, tiêu đề, và gợi ý cụm từ.

Ví dụ bên dưới cho thấy một cấu hình AssignmentMessage điển hình:

<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>

Giờ đây, bạn có thể sử dụng chính sách này trong FaultRule. Lưu ý cách bạn tham chiếu đến OnlyMessage chính sách theo tên trong FaultRule:

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

Khi bạn triển khai cấu hình ở trên, proxy API sẽ thực thi chính sách AllowedMessage được gọi là fault_invalidkey bất cứ khi nào ứng dụng hiển thị khoá API không hợp lệ.

Bạn có thể thực thi nhiều chính sách trong một FaultRule, như ví dụ sau đây:

<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>

Các chính sách thực thi theo thứ tự đã xác định. Ví dụ: bạn có thể sử dụng Chính sách MessageLogging, chính sách ExtractVariables, Chính sách gán tin nhắn hoặc bất kỳ chính sách nào khác trong FaultRule (Quy tắc lỗi). Lưu ý rằng việc xử lý FaultRule sẽ ngừng ngay lập tức nếu một trong những trường hợp này xảy ra:

  • Mọi chính sách trong FaultRule gây ra lỗi
  • Mọi chính sách trong FaultRule đều thuộc loại RaiseFault

Xác định thông báo lỗi tuỳ chỉnh được trả về từ FaultRule

Tốt nhất là bạn nên xác định phản hồi lỗi rõ ràng từ API. Bằng cách đó, bạn cung cấp thông tin nhất quán và hữu ích cho khách hàng của mình.

Ví dụ sau đây về AssignmentMessage sử dụng <Payload>, <StatusCode> và <ReasonPhase> để xác định thuộc tính tuỳ chỉnh phản hồi lỗi được gửi lại cho máy khách khi gặp lỗi InvalidApiKey (xem FaultRules trước đó ví dụ).

<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>

Câu trả lời này bao gồm:

  • Tải trọng chứa thông báo lỗi và địa chỉ email để liên hệ với bộ phận hỗ trợ.
  • Mã trạng thái HTTP được trả về trong phản hồi.
  • Cụm từ nguyên nhân, là đoạn mô tả ngắn về lỗi.

Tạo DefaultFaultRule

DefaultFaultRule đóng vai trò là trình xử lý ngoại lệ cho mọi lỗi không được xử lý rõ ràng bằng một lỗi khác. Nếu điều kiện cho tất cả FaultRules không khớp với lỗi này, thì hàm DefaultFaultRule xử lý lỗi. Bật tính năng xử lý lỗi mặc định bằng cách thêm thuộc tính Thẻ <DefaultFaultRule> làm phần tử con của ProxyEndpoint hoặc Điểm cuối đích.

Ví dụ: cấu hình TargetEndpoint bên dưới xác định DefaultFaultRule sẽ gọi chính sách có tên là 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 thường được dùng để trả về thông báo lỗi chung cho mọi trường hợp , chẳng hạn như thông báo chứa thông tin liên hệ để được hỗ trợ kỹ thuật. Chế độ mặc định này Phản hồi này phục vụ mục đích kép là cung cấp thông tin thân thiện với nhà phát triển, đồng thời làm rối mã nguồn của các URL phụ trợ hoặc các thông tin khác có thể được dùng để xâm phạm hệ thống.

Ví dụ: bạn xác định chính sách AttributionMessage sau đây để trả về một lỗi chung:

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

Đưa phần tử <AlwaysEnforce> vào trong Thẻ <DefaultFaultRule> để thực thi DefaultFaultRule cho mọi lỗi, ngay cả nếu một FaultRule khác đã được thực thi. DefaultFaultRule luôn là FaultRule cuối cùng để thực thi:

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

Một cách sử dụng DefaultFaultRule là xác định loại lỗi xảy ra khi bạn nếu không thì không xác định được mã đó. Ví dụ: proxy API của bạn không hoạt động được do một lỗi mà bạn không thể xác định. Sử dụng DefaultFaultRule để gọi chính sách AttributionMessage sau đây. Chiến dịch này chính sách này ghi giá trị fault.name vào tiêu đề có tên DefaultFaultHeader trong câu trả lời:

<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>

Sau đó, bạn có thể xem tiêu đề trong công cụ theo dõi Edge hoặc trên phản hồi để biết nguyên nhân .

Đang thêm nhật ký thư vào PostClientFlow

PostClientFlow là luồng duy nhất thực thi sau khi proxy mắc lỗi trạng thái. Bạn chỉ có thể đính kèm MessageLogging (chính sách MessageLogging) vào quy trình thực thi này sau khi phản hồi được gửi quay lại với khách hàng. Mặc dù việc đính kèm chính sách MessageLogging vào quy trình này về mặt kỹ thuật không xử lý lỗi, bạn có thể sử dụng nó để ghi thông tin trong trường hợp xảy ra lỗi. Vì thực thi bất kể proxy thành công hay không, bạn có thể đặt tính năng Ghi nhật ký tin nhắn trong PostClientFlow và đảm bảo rằng các chính sách này luôn thực thi.

Xử lý các lỗi về chính sách trong luồng hiện tại

Các ví dụ tôi thấy cho đến thời điểm hiện tại đều sử dụng FaultRule trên ProxyEndpoint hoặc TargetEndpoint để xử lý bất kỳ lỗi chính sách nào trong trạng thái lỗi. Đó là vì giá trị mặc định của Phần tử continueOnError của một chính sách là false, tức là khi một lỗi xảy ra trong chính sách, thì chế độ kiểm soát sẽ chuyển hướng đến trạng thái lỗi. Khi ở trạng thái lỗi, bạn không thể trả về điều khiển về quy trình bình thường và bạn thường trả về một dạng lỗi nào đó nhắn tin cho ứng dụng gọi.

Tuy nhiên, nếu bạn đặt phần tử continueOnError thành true cho phần tử chính sách này, quyền kiểm soát vẫn nằm trong quy trình hiện tại và chính sách tiếp theo trong quy trình sẽ được thực thi sau khi chính sách gây ra lỗi. Lợi thế của việc xử lý lỗi trong luồng hiện tại là bạn có thể tìm cách khắc phục lỗi để hoàn tất xử lý yêu cầu.

Dưới đây là một chính sáchVerifyAPIKey có tên là verify-api-key kèm theo Đã đặt phần tử continueOnError thành true:

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

Nếu khoá API bị thiếu hoặc không hợp lệ, chính sáchVerifyAPIKey sẽ đặt biến oauthV2.verify-api-key.failed thành true, nhưng đang xử lý sẽ tiếp tục trong luồng hiện tại.

Sau đó, bạn thêm chính sách VerifyAPIKey làm một bước trong PreFlow của 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>

Hãy lưu ý cách bước tiếp theo trong PreFlow sử dụng một điều kiện để kiểm tra sự tồn tại của một . Nếu xảy ra lỗi trong chính sách VerifAPIKey thì chính sách có tên là Chính sách FaultInFlow sẽ thực thi. Nếu không, chính sách FaultInFlow sẽ là đã bỏ qua. Chính sách FaultInFlow có thể thực hiện nhiều việc, chẳng hạn như ghi nhật ký lỗi, cố gắng sửa lỗi hoặc thực hiện một số hành động khác.

Kích hoạt lỗi bằng cách sử dụng RaiseFault chính sách

Bạn có thể sử dụng chính sáchRaiseFault bất cứ lúc nào trong một luồng để kích hoạt lỗi. Khi một Khi thực thi chính sách RaiseFault, chính sách này sẽ chấm dứt quy trình hiện tại và chuyển quyền kiểm soát thành lỗi trạng thái.

Một cách sử dụng chính sách RaiseFault là thử nghiệm một điều kiện cụ thể mà một chính sách khác có thể không phát hiện được. Trong ví dụ trên, bạn đã thêm thẻ <Condition> vào Thẻ PreFlow <Step> đã khiến chính sách FaultInFlow thực thi nếu điều kiện được thoả mãn. Nếu FaultInFlow là chính sách RaiseFault, thì hãy kiểm soát chuyển sang trạng thái lỗi. Hoặc bạn có thể chèn chính sách RaiseFault vào một quy trình để gỡ lỗi và kiểm tra FaultRules của bạn.

Khi chính sách RaiseFault kích hoạt lỗi, bạn có thể sử dụng FaultRule và điều kiện sau để xử lý thông tin đó:

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

Lưu ý rằng điều kiện sẽ kiểm tra lỗi có tên RaiseFault. RaiseFault luôn đặt giá trị của fault.name thành RaiseFault.

Xử lý tuỳ chỉnh đối với mã lỗi HTTP từ máy chủ đích

Ví dụ được trình bày trong các phần trước áp dụng cho các lỗi do chính sách tạo ra. Tuy nhiên, bạn cũng có thể tạo một phản hồi tuỳ chỉnh cho các lỗi cấp độ truyền tải, tức là các lỗi HTTP được trả về từ máy chủ mục tiêu. Để kiểm soát phản hồi từ lỗi HTTP, hãy định cấu hình TargetEndpoint thành xử lý mã phản hồi HTTP.

Theo mặc định, Edge coi mã phản hồi HTTP trong phạm vi 1xx-3xx là "thành công" và HTTP các mã phản hồi trong phạm vi 4xx-5xx là "không thành công". Tức là mọi phản hồi từ phần phụ trợ dịch vụ có mã phản hồi HTTP 4xx-5xx sẽ tự động gọi trạng thái lỗi, sau đó sẽ trả về thông báo lỗi trực tiếp cho ứng dụng yêu cầu.

Bạn có thể tạo trình xử lý tuỳ chỉnh cho mọi mã phản hồi HTTP. Ví dụ: bạn có thể không muốn coi tất cả các mã phản hồi HTTP trong phạm vi 4xx-5xx là 'không thành công' nhưng chỉ 5xx hoặc bạn có thể muốn để trả về thông báo lỗi tuỳ chỉnh cho mã phản hồi HTTP 400 và 500.

Trong ví dụ tiếp theo, bạn sử dụng thuộc tính success.codes để định cấu hình TargetEndpoint để xử lý mã phản hồi HTTP 400 và 500 là thành công, cùng với HTTP mặc định mã. Bằng cách coi các mã đó là thành công, TargetEndpoint sẽ tiếp quản việc xử lý thông báo phản hồi thay vì gọi trạng thái lỗi:

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

Như bạn có thể thấy trong ví dụ này, bạn có thể sử dụng ký tự đại diện để đặt thuộc tính success.codes thành một loạt giá trị..

Việc đặt thuộc tính success.codes sẽ ghi đè các giá trị mặc định. Do đó, nếu bạn muốn thêm mã HTTP 400 vào danh sách thành công mặc định mã, hãy đặt thuộc tính này thành:

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

Tuy nhiên, nếu bạn chỉ muốn coi mã HTTP 400 là mã thành công, hãy đặt thuộc tính như sau:

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

Giờ đây, bạn có thể xác định trình xử lý tuỳ chỉnh cho mã phản hồi HTTP 400 và 500 để trả về mã phản hồi tuỳ chỉnh cho ứng dụng yêu cầu. TargetEndpoint sau đây sử dụng chính sách có tên ReturnError để xử lý mã phản hồi HTTP 400 và 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>

Cấu hình TargetEndpoint này khiến chính sách có tên ReturnError xử lý phản hồi bất cứ khi nào TargetEndpoint gặp mã phản hồi HTTP 400 hoặc 500.

Hệ thống phân loại lỗi

Dịch vụ API sắp xếp các lỗi theo các danh mục và danh mục phụ sau.

Danh mục Danh mục con Tên lỗi Mô tả
Nhắn tin Lỗi xảy ra trong luồng thông báo (không bao gồm lỗi chính sách)
Lỗi tuỳ chỉnh {fault_name} Mọi lỗi được proxy API xử lý rõ ràng bằng chính sách RaiseFault
Mã phản hồi Lỗi máy chủ nội bộ, không tìm thấy Mã lỗi HTTP 5xx, 4xx
Lỗi định tuyến NoRoutesMatched Không chọn được TargetEndpoint đã đặt tên cho một yêu cầu
Không phân loại được NotFound Lỗi do URI yêu cầu không khớp với bất kỳ BasePath nào cho bất kỳ ProxyEndpoint nào cấu hình (nghĩa là không có proxy API nào khớp với URL trong yêu cầu của ứng dụng khách)
Giao thông vận tải Lỗi cấp độ truyền tải HTTP
Kết nối Đã từ chối kết nối, Đặt lại kết nối, Hết thời gian chờ kết nối Xảy ra lỗi khi thiết lập kết nối cấp mạng hoặc cấp truyền tải
Yêu cầu xác thực ContentLengthMissing, HostHeaderMissing Lỗi xảy ra trong quá trình kiểm tra ngữ nghĩa đối với mọi yêu cầu
Xác thực phản hồi Lỗi xảy ra trong quá trình kiểm tra ngữ nghĩa trên mọi phản hồi
Lỗi IO Lỗi SSLhandshakeError, Đọc hết thời gian chờ, Lỗi đọc, Thời gian chờ ghi, Lỗi ghi lỗi, Lỗi Chunk Lỗi đọc/ghi tại điểm cuối máy khách hoặc điểm cuối đích, thời gian chờ, lỗi TLS/SSL và phân đoạn các lỗi
Hệ thống Lỗi thời gian chạy không xác định
Bộ nhớ OutOfMemory, GCOverLimit Lỗi liên quan đến bộ nhớ
Chuỗi hội thoại RogueTaskTerminated Các lỗi như chấm dứt các nhiệm vụ đang chạy
Policy Lỗi của từng loại Chính sách được xác định trong Tài liệu tham khảo về chính sách.

Mỗi lỗi luôn đi kèm với nội dung mô tả bằng văn bản về lý do gây ra lỗi. Khi hệ thống phát sinh lỗi, một nhóm thuộc tính được điền sẵn để hỗ trợ khắc phục sự cố. Lỗi bao gồm các thông tin sau:

  • Lý do
  • Thuộc tính tuỳ chỉnh do người dùng xác định