Azure API 管理中的原則

適用於：所有 APIM 層

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

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

附註

API 管理政策與 Azure 原則 定義 不同。 API 管理政策是在閘道器內部執行的執行時規則，用以轉換、驗證、保護及路由 API 請求與回應。 相較之下，Azure 原則 是一項治理服務，評估並強制執行 Azure 資源（如 API Management 實例）符合組織或法規要求的合規性。

熱門原則包括：

  • 將 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 元素來控制每個原則區段中的原則繼承和原則評估順序。

    這很重要

    最佳做法是在每個原則區段的開頭新增 base 元素，以便從父範圍繼承原則。 這可確保在較高層級定義的任何原則不會遭到意外覆寫或忽略。 可使用內建的 Azure 原則定義 (API Management policies should inherit parent scope policies using <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 管理解決方案中設定的原則。

範例提示：

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>

在上述範例原則定義中：

附註

如果您在 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>

相關內容

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

  • Last updated on