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

發行項
04/05/2024

適用於：所有 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 來產生原則定義，然後將結果複製到原則編輯器中，並進行任何必要的調整。詢問問題以深入解析不同的選項、修改提供的原則，或釐清您已經擁有的原則。深入了解

重要

Microsoft Copilot for Azure (預覽版) 需要註冊，目前僅適用於核准的企業客戶和合作夥伴。如需詳細資訊，請參閱對 Microsoft 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>

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