API 管理策略中的错误处理Error handling in API Management policies

• 11/18/2020
• • J

Azure API 管理通过提供 ProxyError 对象，允许发布服务器响应在处理请求的过程中可能发生的错误情况。By providing a ProxyError object, Azure API Management allows publishers to respond to error conditions, which may occur during processing of requests. ProxyError 对象可通过 context.LastError 属性访问，并可由 on-error 策略节中的策略使用。The ProxyError object is accessed through the context.LastError property and can be used by policies in the on-error policy section. 本文提供的参考针对 Azure API 管理中的错误处理功能。This article provides a reference for the error handling capabilities in Azure API Management.

API 管理中的错误处理Error handling in API Management

Azure API 管理中的策略分为 inbound、backend、outbound 和 on-error 部分，如以下示例所示。Policies in Azure API Management are divided into inbound, backend, outbound, and on-error sections as shown in the following example.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is
         forwarded to the backend service go here -->
    </backend>
    <outbound>
      <!-- statements to be applied to the response go here -->
    </outbound>
    <on-error>
        <!-- statements to be applied if there is an error
             condition go here -->
  </on-error>
</policies>

在处理请求期间，内置的步骤与请求范围内的策略一起执行。During the processing of a request, built-in steps are executed along with any policies, which are in scope for the request. 如果发生错误，处理会立即跳转到 on-error 策略节。If an error occurs, processing immediately jumps to the on-error policy section. on-error 策略节可以在任何范围内使用。The on-error policy section can be used at any scope. API 发布者可配置自定义行为，例如将错误记录到事件中心，或者创建新的需要返回到调用方的响应。API publishers can configure custom behavior such as logging the error to event hubs or creating a new response to return to the caller.

出错时允许的策略Policies allowed in on-error

以下策略可以用在 on-error 策略节中。The following policies can be used in the on-error policy section.

• choosechoose
• set-variableset-variable
• find-and-replacefind-and-replace
• return-responsereturn-response
• set-headerset-header
• set-methodset-method
• set-statusset-status
• send-requestsend-request
• send-one-way-requestsend-one-way-request
• log-to-eventhublog-to-eventhub
• json-to-xmljson-to-xml
• xml-to-jsonxml-to-json
• limit-concurrencylimit-concurrency
• mock-responsemock-response
• retryretry
• 跟踪trace

LastErrorLastError

当发生错误且控制跳转到 on-error 策略节时，错误会存储在 context.LastError 属性中，该属性可以通过 on-error 节中的策略进行访问。When an error occurs and control jumps to the on-error policy section, the error is stored in context.LastError property, which can be accessed by policies in the on-error section. LastError 具有以下属性。LastError has the following properties.

针对内置步骤的预定义错误Predefined errors for built-in steps

针对评估内置处理步骤期间可能发生的错误情况，预定义了以下错误。The following errors are predefined for error conditions that can occur during the evaluation of built-in processing steps.

针对策略的预定义错误Predefined errors for policies

针对策略评估期间可能发生的错误情况，预定义了以下错误。The following errors are predefined for error conditions that can occur during policy evaluation.

示例Example

将 API 策略设置为以下内容：Setting an API policy to:

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <set-header name="ErrorSource" exists-action="override">
            <value>@(context.LastError.Source)</value>
        </set-header>
        <set-header name="ErrorReason" exists-action="override">
            <value>@(context.LastError.Reason)</value>
        </set-header>
        <set-header name="ErrorMessage" exists-action="override">
            <value>@(context.LastError.Message)</value>
        </set-header>
        <set-header name="ErrorScope" exists-action="override">
            <value>@(context.LastError.Scope)</value>
        </set-header>
        <set-header name="ErrorSection" exists-action="override">
            <value>@(context.LastError.Section)</value>
        </set-header>
        <set-header name="ErrorPath" exists-action="override">
            <value>@(context.LastError.Path)</value>
        </set-header>
        <set-header name="ErrorPolicyId" exists-action="override">
            <value>@(context.LastError.PolicyId)</value>
        </set-header>
        <set-header name="ErrorStatusCode" exists-action="override">
            <value>@(context.Response.StatusCode.ToString())</value>
        </set-header>
        <base />
    </on-error>
</policies>

并发送未经授权的请求将导致以下响应：and sending an unauthorized request will result in the following response:

后续步骤Next steps

有关如何使用策略的详细信息，请参阅：For more information working with policies, see:

• API 管理中的策略Policies in API Management
• 转换 APITransform APIs
• 策略参考，获取策略语句及其设置的完整列表Policy Reference for a full list of policy statements and their settings
• 策略示例Policy samples