Azure API 管理中的原則 \(部分機器翻譯\)

2025-06-01

適用於：所有 API 管理層

在 Azure API 管理中，API 發行者可以使用原則，透過設定來變更 API 行為。本文說明如何使用原則。

原則是陳述式的集合，會因 API 的要求或回應循序執行。 API 管理提供 75 個以上的現用原則，您可以設定這些原則來解決常見的 API 案例，例如驗證、速率限制、快取，以及要求或回應的轉換。如需完整清單，請參閱 API 管理原則參考。

熱門原則包括：

將 XML 轉換成 JSON 的格式。
通話速率限制，以限制來自開發人員的來電數目。
篩選來自特定IP位址的要求。

原則是在位於 API 取用者與受控 API 之間的閘道內套用。雖然閘道會接收要求，並將其轉送至基礎 API，但原則可以同時對輸入要求和輸出回應套用變更。

了解原則設定

原則定義是簡單的 XML 文件，描述要套用至要求和回應的陳述式序列。為了協助您設定原則定義，入口網站會提供下列選項：

引導式表單式編輯器，可簡化設定熱門原則而不撰寫 XML 程式碼
程式碼編輯器，您可以在其中插入 XML 程式碼片段或直接編輯 XML

如需如何設定原則的詳細資訊，請參閱設定或編輯原則。

原則 XML 組態分成 inbound、backend、outbound 和 on-error 區段。這一系列指定的政策聲明會依序執行，用於處理請求和回應。其看起來會像下面這樣：

<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's an error condition go here -->
  </on-error>
</policies>

如需原則 XML 範例，請參閱 APIM 原則程式碼片段存放庫 (英文)。

錯誤處理

如果在處理要求期間發生錯誤：

inbound、backend 或 outbound 區段中的其他任何步驟都會略過。
執行會跳至區段 on-error 中的陳述式。

藉由在 on-error 區段中放置原則陳述式，您可以：

使用 context.LastError 屬性檢閱錯誤。
使用 set-body 原則檢查並自定義錯誤回應。
設定發生錯誤時會發生什麼事。

如需詳細資訊，請參閱 API 管理原則中的錯誤處理方式。

原則運算式

如果原則不另行指定，則可以在任何 API 管理原則中，使用原則運算式做為屬性值或文字值。原則表達式是下列其中一項：

單一 C# 語句被包裹在 @(expression) 中
由多個語句組成並以 @{expression} 括住的 C# 代碼區塊，會傳回一個值。

每個運算式具有存取權以隱含方式提供 context 變數並允許子集的 .NET Framework 型別。

原則運算式提供複雜的方法來控制流量和修改 API 行為，您無須撰寫特製化程式碼或修改後端服務。某些原則是以原則運算式為基礎，例如控制流程和設定變數。

範圍

API 管理可讓您在下列範圍定義原則，從最廣泛到最窄的範圍呈現：

全域 (所有 API)
工作區 (與所選工作區相關聯的所有 API)
產品 (與所選產品相關聯的所有 API)
API (API 中的所有作業)
工作（API 中的單一工作）

開始設定原則時，您必須先選取要套用原則的範圍。

須知事項

若要針對不同的 API 取用者進行精細的控制，您可以在多個範圍設定原則定義。
不是每一個政策都支援每一個範圍和政策區段。
在多個範圍設定原則定義時，您可以藉由放置 base 元素來控制每個原則區段中的原則繼承和原則評估順序。
套用至 API 要求的原則也會受到要求內容所影響，包括要求中使用的訂用帳戶金鑰是否存在、訂用帳戶金鑰的 API 或產品範圍，以及 API 或產品是否需要訂用帳戶。

注意

如果您使用 API 範圍的訂用帳戶、所有 API 訂用帳戶或內建的所有存取訂用帳戶，則在產品範圍中設定的原則都不會套用至來自該訂用帳戶的要求。

如需詳細資訊，請參閱

GraphQL 解析器原則

在 API 管理中， GraphQL 解析程式會設定原則範圍設定為 GraphQL 架構中的特定作業類型和欄位。

目前，API 管理支援 GraphQL 解析程式，可指定 HTTP API、Azure Cosmos DB 或 Azure SQL 數據源。例如，您可以使用元素來設定單一http-data-source原則，以指定對 HTTP 資料來源的要求（以及選擇性地回應）。
您無法在其他範圍的原則定義中包含解析程序原則，例如 API、產品或所有 API。原則也不會繼承在其他範圍設定的原則。
網關會在原則執行管線中，先執行任何已設定的 inbound 和 backend 原則，然後評估解析程式範圍的原則。

如需詳細資訊，請參閱設定 GraphQL 解析器。

取得 Copilot 協助

您可以從 Copilot 取得 AI 協助，以建立和編輯 API 管理原則定義。您可以使用 Copilot 來建立和更新符合特定需求的原則，而不需要知道 XML 語法。您也可以取得現有原則的說明。 Copilot 可協助您轉譯您可能在其他 API 管理解決方案中設定的原則。

Microsoft Azure 中的 Copilot 會在 Azure 入口網站中提供自然語言提示的原則撰寫協助。您可以在 API 管理原則編輯器中撰寫原則，並要求 Copilot 說明原則區段。
Visual Studio Code 中適用於 Azure 的 GitHub Copilot 提供 Visual Studio Code 中的原則撰寫協助，而且您可以使用適用於 Visual Studio Code 的 Azure API 管理延伸模組來加速原則設定。您可以使用自然語言提示 Copilot Chat 或 Copilot Edits，在原位置建立並精簡原則定義。

範例提示：

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot 是由 AI 所提供，因此可能會有驚喜和錯誤。如需詳細資訊，請參閱 Copilot 一般使用常見問題。

範例

套用在不同範圍指定的原則

若您在全域層級中有一個原則，還有一個為 API 設定的原則，則每次使用該特定 API 時，皆可以套用這兩個原則。 API 管理可透過 base 元素來指定組合式原則陳述式的固定順序。

API 範圍的原則定義範例：

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

在上述範例原則定義中：

cross-domain 語句先執行。
find-and-replace政策會在任何範圍較廣的政策之後執行。

注意

如果您在 API 範圍移除 base 元素，則只會套用在 API 範圍設定的原則。配置在產品及更廣泛範圍的政策將不會被套用。

使用原則運算式修改要求

下列範例使用原則表達式和原則 set-header ，將用戶數據新增至傳入要求。新增的標頭包含與要求中訂閱金鑰相關聯的使用者 ID，以及主機處理要求的閘道所在的區域。

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

如需使用原則的詳細資訊，請參閱：

共用方式為