共用方式為

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

  • 發行項

適用於：所有 API 管理層

在 Azure API 管理中，API 發行者可以使用原則透過設定來變更 API 行為。 原則是陳述式的集合，會因 API 的要求或回應循序執行。 APIM 提供超過現成的 50 個原則，讓您可設定來解決常見的 API 案例，例如，驗證、速率限制、快取，以及要求或回應的轉換。 如需完整清單，請參閱 API 管理原則參考。

熱門原則包括：

  • 從 XML 轉換為 JSON 的格式
  • 呼叫速率限制來限制開發人員連入呼叫的數目
  • 篩選來自特定 IP 位址的要求

原則是在位於 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 is an error condition go here -->
  </on-error>
</policies>

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

錯誤處理

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

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

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

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

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

原則運算式

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

  • 以 @(expression) 括住的單一 C# 陳述式，或
  • 括住在 @{expression} 中，並會傳回值的多陳述式 C# 程式碼區塊

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

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

範圍

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

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

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

原則範圍

須知事項

  • 若要對不同的 API 取用者進行更精細的控制，您可以在多個範圍設定原則定義

  • 並非所有原則在每個範圍和原則區段都受支援

  • 在多個範圍中設定原則定義時，您可以透過放置 base 元素來控制每個原則區段中的原則繼承和原則評估順序

  • 套用至 API 要求的原則也會受到要求內容所影響，包括要求中使用的訂用帳戶金鑰是否存在、訂用帳戶金鑰的 API 或產品範圍，以及 API 或產品是否需要訂用帳戶。

    注意

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

如需詳細資訊，請參閱

GraphQL 解析器原則

在 APIM 中，GraphQL 解析器是使用範圍限定為 GraphQL 結構描述中特定作業類型和欄位的原則。

  • 目前，APIM 支援 GraphQL 解析器，可指定 HTTP API、Cosmos DB 或 Azure SQL 資料來源。 例如，使用元素來設定單一 http-data-source 原則，以指定對 HTTP 資料來源的要求 (並選擇性地回應)。
  • 您無法在其他範圍 (例如 API、產品或所有 API) 的原則定義中包含解析器原則。 它也不會繼承在其他範圍設定的原則。
  • 閘道會在原則執行管線中任何設定的 inbound 和 backend 原則「之後」，評估解析器範圍的原則。

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

取得使用 Microsoft Copilot for Azure (預覽版) 建立原則的協助

Microsoft Copilot for Azure (預覽版) 提供適用於 Azure API 管理的原則撰寫功能。 在 Azure API 管理原則編輯器的內容中使用 Copilot for Azure 來建立符合您特定需求的原則，而不需了解語法，或已經設定已為您說明過的原則。

您可以提示 Copilot for Azure 來產生原則定義，然後將結果複製到原則編輯器中，並進行任何必要的調整。 詢問問題以深入解析不同的選項、修改提供的原則，或釐清您已經擁有的原則。 深入了解

範例

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

若您在全域層級中有一個原則，還有一個為 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 原則，將使用者資料新增至傳入要求。 新增的標頭包含與要求中訂用帳戶金鑰相關聯的使用者識別碼，以及處理要求之網路閘道託管的區域。

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

相關內容

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