Azure API 管理中的原則Policies in Azure API Management

在 Azure API 管理 (APIM) 中,原則是系統的一項強大功能,可讓發行者透過組態來變更 API 的行為。In Azure API Management (APIM), policies are a powerful capability of the system that allow the publisher to change the behavior of the API through configuration. 原則是「陳述式」的集合,會在 API 的要求或回應上循序執行。Policies are a collection of Statements that are executed sequentially on the request or response of an API. 常見的「陳述式」包括從 XML 至 JSON 的格式轉換,以及利用呼叫速率限制來限制開發人員傳入的呼叫數量。Popular Statements include format conversion from XML to JSON and call rate limiting to restrict the amount of incoming calls from a developer. 還有許多現成的原則可用。Many more policies are available out of the box.

原則是在位於 API 取用者與受控 API 之間的閘道內套用。Policies are applied inside the gateway which sits between the API consumer and the managed API. 閘道會接收所有要求,然後通常原封不動地轉送至基礎 API。The gateway receives all requests and usually forwards them unaltered to the underlying API. 不過,原則可以套用至輸入要求和輸出要求。However a policy can apply changes to both the inbound request and outbound response.

如果原則不另行指定,則可以在任何 API 管理原則中,使用原則運算式做為屬性值或文字值。Policy expressions can be used as attribute values or text values in any of the API Management policies, unless the policy specifies otherwise. 某些原則是以原則運算式為基礎,例如控制流程設定變數原則。Some policies such as the Control flow and Set variable policies are based on policy expressions. 如需詳細資訊,請參閱進階原則原則運算式For more information, see Advanced policies and Policy expressions.

了解原則組態 Understanding policy configuration

原則定義是一份簡單的 XML 文件,描述一連串輸入和輸出陳述式。The policy definition is a simple XML document that describes a sequence of inbound and outbound statements. 可直接在定義視窗中編輯 XML。The XML can be edited directly in the definition window. 右邊提供陳述式的清單,而且會啟用並醒目提示適用於目前範圍的陳述式。A list of statements is provided to the right and statements applicable to the current scope are enabled and highlighted.

按一下已啟用的陳述式會在定義檢視中的游標位置上加入適當的 XML。Clicking an enabled statement will add the appropriate XML at the location of the cursor in the definition view.

注意

如果未啟用您想要新增的原則,請確定您是在該原則的正確範圍內。If the policy that you want to add is not enabled, ensure that you are in the correct scope for that policy. 每個原則陳述式都是針對在特定範圍和原則區段中使用所設計。Each policy statement is designed for use in certain scopes and policy sections. 若要檢閱原則的原則區段和範圍,請檢查 原則參考 中該原則的 使用方式一節。To review the policy sections and scopes for a policy, check the Usage section for that policy in the Policy Reference.

設定分為 inboundbackendoutboundon-errorThe configuration is divided into inbound, backend, outbound, and on-error. 指定的一連串原則陳述式會針對要求和回應而依序執行。The series of specified policy statements is executes in order for a request and a response.

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

若在處理要求期間發生錯誤,便會略過 inboundbackendoutbound 區段中的所有剩餘步驟,且執行程序會跳至 on-error 區段中的陳述式。If there is an error during the processing of a request, any remaining steps in the inbound, backend, or outbound sections are skipped and execution jumps to the statements in the on-error section. 將原則陳述式置於 on-error 區段中,您即可使用 context.LastError 屬性檢閱錯誤、使用 set-body 原則檢查和自訂錯誤回應,以及設定錯誤發生時採取的動作。By placing policy statements in the on-error section you can review the error by using the context.LastError property, inspect and customize the error response using the set-body policy, and configure what happens if an error occurs. 會出現內建步驟的錯誤碼和處理原則陳述式期間可能會發生之錯誤的錯誤碼。There are error codes for built-in steps and for errors that may occur during the processing of policy statements. 如需詳細資訊,請參閱 API 管理原則中的錯誤處理方式For more information, see Error handling in API Management policies.

如何設定原則 How to configure policies

如需如何設定原則的資訊,請參閱設定或編輯原則For information on how to configure policies, see Set or edit policies.

原則參考文件Policy Reference

如需原則陳述式及其設定的完整清單,請參閱原則參考文件See the Policy reference for a full list of policy statements and their settings.

原則範例Policy samples

請參閱原則範例以取得更多程式碼範例。See Policy samples for more code examples.

範例Examples

套用在不同範圍指定的原則Apply policies specified at different scopes

若您在全域層級中有一個原則,還有一個為 API 設定的原則,則每次使用該特定 API 時,皆會套用這兩個原則。If you have a policy at the global level and a policy configured for an API, then whenever that particular API is used both policies will be applied. API 管理可透過 base 元素來指定組合式原則陳述式的固定順序。API Management allows for deterministic ordering of combined policy statements via the base element.

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

在上述的原則定義範例中,cross-domain 陳述式會在任何更高層級的原則執行之前執行,而這些原則後面又接著 find-and-replace 原則。In the example policy definition above, the cross-domain statement would execute before any higher policies which would in turn, be followed by the find-and-replace policy.

限制傳入要求Restrict incoming requests

若要新增陳述式以限制接收指定 IP 位址的傳入要求,請將游標移至 inbound XML 元素的內容當中,然後按一下 Restrict caller IPs 陳述式。To add a new statement to restrict incoming requests to specified IP addresses, place the cursor just inside the content of the inbound XML element and click the Restrict caller IPs statement.

Restriction policies

這會將 XML 程式碼片段新增至提供設定陳述式之指引的 inbound 元素。This will add an XML snippet to the inbound element that provides guidance on how to configure the statement.

<ip-filter action="allow | forbid">
    <address>address</address>
    <address-range from="address" to="address"/>
</ip-filter>

若要限制輸入要求,只接受來自 IP 位址 1.2.3.4 的要求,請如下修改 XML:To limit inbound requests and accept only those from an IP address of 1.2.3.4 modify the XML as follows:

<ip-filter action="allow">
    <address>1.2.3.4</address>
</ip-filter>

後續步驟Next steps

如需使用原則的詳細資訊,請參閱︰For more information working with policies, see: