共用方式為

如何設定或編輯 Azure API Management 原則

適用於：所有 APIM 階層

本文說明如何在 Azure 入口網站中編輯原則定義，以設定 API 管理執行個體中的原則。 每個原則定義都是一份 XML 文件，該文件會描述在 API 要求和回應上循序執行的輸入和輸出陳述式序列。

在入口網站中，原則編輯器會提供 API 發行者所需的引導式表單，以新增和編輯原則定義中的原則。 您也可以直接在原則程式碼編輯器中編輯 XML。

關於原則的詳細資訊：

必要條件

如果您還沒有 API 管理執行個體和後端 API，請參閱：

移至您的 APIM 執行個體

  1. 在 Azure 入口 網站中，搜尋並選取 [API 管理服務]：

    顯示搜尋結果中 API 管理服務的螢幕快照。

  2. 在 [ API 管理服務 ] 頁面上，選取您的 API 管理實例：

    顯示 API 管理服務頁面上 API 管理實例的螢幕快照。

在入口網站中設定原則

下列範例示範如何使用入口網站原則編輯器中的下列兩個選項來設定原則：

  • 引導式表單型編輯器，可簡化許多原則的設定作業
  • 程式碼編輯器，可供您直接新增或編輯 XML

在此範例中，原則要篩選來自特定傳入 IP 位址的要求。 其範圍設定為選取的 API。

附註

您可以設定其他範圍的原則，例如針對所有 API、產品或單一 API 作業。 如需其他範例，請參閱本文稍後的設定範圍。

若要設定原則：

  1. 在 API 管理執行個體的左側導覽中，選取 [API]。

  2. 選取您先前匯入的 API。

  3. 選取 設計 索引標籤。

  4. 若要將原則套用至所有作業，請選取 [所有作業]。

  5. 在 [輸入處理] 區段中，選取 [+ 新增原則]。

    在 APIM 中新增原則

  6. 在 [新增輸入政策] 中，選取要新增的政策。 例如，選取 [篩選 IP 位址]。

    篩選 IP 位址原則

    秘訣

    • 顯示的原則範圍為您要設定的原則區段，在此案例中為輸入處理。
    • 如果您沒有看到想要的原則，請選取 [其他原則] 圖格。 隨即開啟 XML 程式碼編輯器，並顯示該區段和範圍的完整原則清單。

  7. 選取 [允許的 IP]>[+ 新增 IP 篩選器]，然後新增傳入位址範圍的第一個和最後一個 IP 位址，以允許提出 API 要求。 視需要新增其他 IP 位址範圍。

    設定允許的 IP 位址

  8. 選取 [儲存] 以立即將變更傳播至 API 管理閘道。

    ip-filter 原則現在會出現在 [輸入處理] 區段中。

設定不同範圍的原則

API 管理可讓您彈性地在每個原則區段中，設定多個範圍的原則定義。

重要

並非所有原則都可以套用在每個範圍或原則區段。 如果您想要新增的原則並未啟用，請確認您位於支援的原則區段，並在該原則的正確範圍內。 若要檢閱原則的原則區段和範圍，請查看原則參考主題中的使用方式一節。

附註

後端原則區段只能包含一個原則元素。 根據預設，API 管理會在全域範圍的forward-request區段中設定 原則，並在其他範圍設定 base 元素。

全域範圍

在您的 API 管理執行個體中，已為 所有 API 設定全域範圍。

  1. 在 API 管理執行個體的左側導覽中，選取 [API]>[所有 API]。

  2. 選取 設計 索引標籤。

    在產品範圍設定原則

  3. 在原則區段中，選取 [+ 新增原則] 以使用表單型原則編輯器，或選取 </> (程式碼編輯器) 圖示，直接新增和編輯 XML。

  4. 選取 [儲存] 以立即將變更傳播至 API 管理閘道。

產品範圍

您要為所選的產品設定產品範圍。

  1. 在左側功能表中，選取 [產品]，然後選取您要套用原則的產品。

  2. 在產品視窗中，選取 [原則]。

    在全域範圍設定原則

  3. 在原則區段中，選取 [+ 新增原則] 以使用表單型原則編輯器，或選取 </> (程式碼編輯器) 圖示，直接新增和編輯 XML。

  4. 選取 [儲存] 以立即將變更傳播至 API 管理閘道。

API 範圍

您要為所選 API 的 [所有作業] 設定 API 範圍。

  1. 在 API 管理執行個體的左側導覽中，選取 [API]，然後選取您要套用原則的 API。

  2. 選取 設計 索引標籤。

  3. 選取 [所有作業]。

    在 API 範圍設定原則

  4. 在原則區段中，選取 [+ 新增原則] 以使用表單型原則編輯器，或選取 </> (程式碼編輯器) 圖示，直接新增和編輯 XML。

  5. 選取 [儲存] 以立即將變更傳播至 API 管理閘道。

作業範圍

您要為所選的 API 作業設定作業範圍。

  1. 在 API 管理執行個體的左側導覽中，選取 [API]。

  2. 選取 設計 索引標籤。

  3. 選取您要套用原則的作業。

    在作業範圍設定原則

  4. 在原則區段中，選取 [+ 新增原則] 以使用表單型原則編輯器，或選取 </> (程式碼編輯器) 圖示，直接新增和編輯 XML。

  5. 選取 [儲存] 以立即將變更傳播至 API 管理閘道。

重複使用原則設定

您可以在 API 管理執行個體中建立可重複使用的原則片段。 原則片段是包含一或多個原則設定的 XML 元素。 原則片段可協助您一致地設定原則，並維護原則定義，而不需要重複或重新鍵入 XML 程式碼。

使用 include-fragment 原則，以在原則定義中插入原則片段。

使用 base 元素來設定原則評估順序

如果您在多個範圍設定原則定義，則多個原則可以套用至 API 要求或回應。 根據不同範圍的原則套用順序而定，要求或回應的轉換可能會有所不同。

在 API 管理中，請依據 base 元素在每個範圍原則定義區段中的放置位置，判斷原則評估順序。 base 元素會繼承下一個更廣泛 (父系) 範圍中該區段設定的原則。 每個原則區段預設會包含 base 元素。

附註

若要檢視目前範圍的有效原則，請在原則編輯器中選取 [計算有效原則]。

若要使用原則編輯器修改原則評估順序：

  1. 請先從您設定的最窄範圍定義開始，因為 API 管理也會先由此套用。

    例如，當您使用全域範圍和 API 範圍設定的原則定義時，請從 API 範圍的設定開始。

  2. 將 base 元素放在區段中，以判斷要從父系範圍對應區段哪個位置繼承所有原則。

    例如，您可以在 API 範圍設定的 inbound 區段中，放置 base 元素來控制要繼承全域範圍 inbound 區段哪個位置設定的原則。 在下列範例中，繼承自全域範圍的原則會優先於 ip-filter 原則套用。

    <policies>
  <inbound>
      <base />
        <ip-filter action="allow">
            <address>10.100.7.1</address>
        </ip-filter>
  </inbound>
  [...]
</policies>

    附註

    • 您可以在區段中的任何原則元素之前或之後放置 base 元素。
    • 如果您想要避免繼承來自父系範圍的原則，請移除 base 元素。 但在大部分情況下，不建議您這麼做。 不過，在某些情況下可能很有用，例如當您想要將不同原則套用至特定作業，而不是針對 API (所有作業) 範圍設定時。

  3. 接著在後續更廣泛範圍的原則定義中，繼續設定 base 元素。

    全域範圍原則沒有父系範圍，因此在這類原則中使用 base 元素無法發揮任何作用。

取得 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 一般使用常見問題。

相關內容

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