教學課程：轉換及保護 API

2025-06-01

適用於：所有 API 管理層

在本教學課程中，您將瞭解如何設定原則以保護或轉換 API。原則是語句的集合，這些語句會依序在修改 API 行為之 API 的要求或回應上執行。

秘訣

API 小組可以在工作區中使用這項功能。工作區提供 API 及其自有 API 執行階段環境的隔離系統管理存取權。

例如，您可能想要設定自定義響應標頭。或者，藉由設定速率限制原則來保護後端 API，讓開發人員不會過度使用 API。這些範例是 API 管理原則的簡單簡介。如需更多原則選項，請參閱 API 管理原則。

附註

根據預設，API 管理會設定全域 forward-request 原則。閘道需要 forward-request 策略，以完成對後端服務的請求。

在本教學課程中，您會了解如何：

轉換 API 以設定自訂響應標頭
新增頻率限制策略以保護 API（即節流）
測試轉換

必要條件

了解 Azure API 管理術語。
了解 Azure API 管理的原則概念。
完成下列快速入門：建立 Azure API 管理執行個體。在本教學課程中，我們建議您使用其中一個傳統或 v2 層，例如開發人員層或基本 v2 層。消費層不支援本教學中使用的所有策略。
同時也請完成下列教學課程：匯入和發佈您的第一個 API。

移至您的 API 管理執行個體

在 Azure 入口網站中，搜尋並選取 [API 管理服務]：
在 [ API 管理服務 ] 頁面上，選取您的 API 管理實例：

測試原始回應

查看原始回應：

在您的 API 管理服務執行個體中，選取 [API]。
從您的 API 清單中選取 [Swagger Petstore ]。
選取畫面頂端的 [測試] 索引標籤。
選取 [GET 依狀態搜尋寵物] 作業，並選擇性地選取 status查詢參數 的不同值。請選取傳送。

原始 API 回應看起來應如下列回應所示：

轉換 API 以新增自訂響應標頭

API 管理包含數個轉換原則，可用來修改要求或響應承載、標頭或狀態代碼。在此範例中，您會在 API 回應中設定自訂回應標頭。

設定轉換原則

本節說明如何使用原則來設定自定義響應標頭 set-header 。在這裡，您會使用可簡化原則設定的窗體式原則編輯器。

選取 [Swagger Petstore]>[設計]>[所有作業]。
在 [輸出處理] 區段中，選取 [+ 新增原則]。
在 [新增輸出原則] 視窗中，選取 [設定標頭]。
若要進行標頭原則設定，請執行下列動作：
1. 在名稱底下，輸入自訂。
2. 在 [值] 之下，選取 [ + 新增值]。輸入 「我的自定義值」。
3. 選取儲存。
設定之後，set-header 政策元素會出現在 輸出處理 區段中。

新增速率限制原則 (節流) 來保護 API

本節示範如何設定速率限制，並新增後端 API 的保護，讓開發人員不過度使用 API。此範例示範如何使用程式代碼編輯器設定 rate-limit-by-key 原則。在此範例中，限制會設定為每15秒三個呼叫。 15 秒之後，開發人員可以重試呼叫 API。

附註

取用層中不支援此原則。

選取 [Swagger Petstore]>[設計]>[所有作業]。
在 [輸入處理] 區段中，選取程式碼編輯器 (</>) 圖示。
將游標移至空白行上的 <inbound> 元素內。接著，選取畫面右上角的 [顯示程式碼片段]。
在右側視窗的 [存取限制原則] 下方，選取 [+ 限制每個金鑰的呼叫速率]。

游標處添加 <rate-limit-by-key /> 元素。
將 <rate-limit-by-key /> 元素中的 <inbound> 程式碼修改為下列程式碼。然後選取儲存。
```
<rate-limit-by-key calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
```

測試轉換

此時若在程式碼編輯器中查看程式碼，您的原則將如下列程式碼所示：

<policies>
     <inbound>
         <rate-limit calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
         <base />
     </inbound>
     <outbound>
         <set-header name="Custom" exists-action="override">
             <value>"My custom value"</value>
           </set-header>
         <base />
     </outbound>
     <on-error>
         <base />
     </on-error>
 </policies>

本節的其餘部分將測試您在此文章中設定的原則轉換。

測試自定義回應標頭

選取 [Swagger Petstore]>[測試]。
選取 [GET 依狀態搜尋寵物] 作業，並選擇性地選取 status查詢參數 的不同值。請選取傳送。

如您所見，已新增自定義回應標頭：

測試速率限制 (節流)

選取 [Swagger Petstore]>[測試]。
選取 GET 依狀態尋找寵物 作業。選取在資料列中 [傳送] 數次。

在設定的期間傳送太多要求之後，您會收到 429 個太多要求 回應。
至少等候 15 秒，接著再次選取 [傳送]。此時，您應該得到 200 確定的回應。

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

共用方式為