如何在 Azure API 管理原則中使用具名值

適用於：所有 APIM 層

API 管理原則是系統的強大功能，可讓發行者透過設定來變更 API 的行為。 原則是陳述式的集合，會因 API 的要求或回應循序執行。 原則陳述式可以使用常值文字值、原則運算式和具名值來建構。

「具名值」是每個 API 管理執行個體中名稱/值組的全域集合。 集合中的項目數不受限制。 具名值可用來管理所有 API 設定和原則的常數字串值和祕密。

值類型

類型	描述
純文字	常值字串或原則運算式
祕密	由 API 管理加密的常值字串或原則運算式
Key vault	儲存在 Azure Key Vault 中的祕密識別碼。

純值或祕密可以包含原則運算式。 例如，運算式 @(DateTime.Now.ToString()) 會傳回包含目前日期與時間的字串。

如需具名值屬性的詳細資料，請參閱 API 管理 REST API 參考。

金鑰保存庫祕密

祕密值可以儲存為 API 管理(自訂祕密) 中的加密字串，或參考 Azure Key Vault 中的祕密。

建議使用金鑰保存庫祕密，因為這有助於改善 API 管理安全性：

• 儲存在金鑰保存庫中的祕密可以跨服務重複使用
• 精細的存取原則可以套用至祕密
• 金鑰保存庫中更新的祕密會自動在 API 管理輪替。 在金鑰保存庫中更新之後，API 管理中的具名值會在 4 小時內更新。 您也可以使用 Azure 入口網站或透過管理 REST API 手動重新整理祕密。

注意

儲存在 Azure 金鑰保存庫 中的秘密必須介於 1 到 4096 個字元之間，因為 API 管理 無法擷取超過此限制的值。

必要條件

• 如果您尚未建立 API 管理服務執行個體，請參閱 建立 API 管理服務執行個體。

金鑰保存庫整合的必要條件

注意

目前，此功能無法在工作區中使用。

• 如果您還沒有金鑰保存庫，請建立一個。 如需建立金鑰保存庫的步驟，請參閱快速入門：使用 Azure 入口網站建立金鑰保存庫。

  若想建立金鑰保存庫或匯入祕密，請參閱快速入門：使用 Azure 入口網站從 Azure Key Vault 設定及擷取祕密。

• 在 API 管理執行個體中啟用系統指派或使用者指派的受控識別。

設定金鑰保存庫存取權

1. 在入口網站中，瀏覽至您的金鑰保存庫。

2. 從左側功能表中選取 [存取設定]，並記下已設定的 [權限模型]。

3. 根據權限模型，為 APIM 受控識別設定金鑰保存庫存取原則或 Azure RBAC 存取權。

   若要新增金鑰保存庫存取原則：
   

   1. 在左側功能表中，選取 [存取原則]。
   2. 在 [存取原則] 頁面上，選取 [+ 建立]。
   3. 在 [權限] 索引標籤的 [祕密權限] 下，選取 [取得] 與 [列出]，然後選取 [下一步]。
   4. 在 [主體] 索引標籤的 [選取主體] 中，搜尋受控識別的資源名稱，然後選取 [下一步]。 如果您使用系統指派的身分識別，則主體是您 API 管理執行個體的名稱。
   5. 再次選取 [下一步]。 在 [檢閱 + 建立] 索引標籤中，選取 [建立]。

   若要設定 Azure RBAC 存取權：
   

   1. 在左側功能表中，選取 [存取控制 (IAM)]。
   2. 在 [存取控制 (IAM)] 頁面上，選取 [新增角色指派]。
   3. 在 [角色] 索引標籤上，選取 [Key Vault 憑證使用者]。
   4. 在 [成員] 索引標籤上，選取 [受控識別]>[+ 選取成員]。
   5. 在 [選取受控識別] 頁面上，選取系統指派的受控識別或與 APIM 執行個體相關聯的使用者指派受控識別，然後選取 [選取]。
   6. 選取檢閱+指派。

金鑰保存庫防火牆的需求

如果您的金鑰保存庫已啟用金鑰保存庫防火牆，則下列為其他需求：

• 您必須使用 API 管理執行個體的系統指派受控識別來存取金鑰保存庫。

• 在金鑰保存庫防火牆中，啟用 [允許信任的 Microsoft 服務略過此防火牆] 選項。

• 當您選取要新增至 Azure API 管理的憑證或祕密時，請確定您的本機用戶端 IP 位址可以暫時存取金鑰保存庫。 如需詳細資訊，請參閱設定 Azure Key Vault 網路設定。

  完成設定之後，您可以在金鑰保存庫防火牆中封鎖用戶端位址。

虛擬網路需求

如果 API 管理執行個體已部署在虛擬網路中，也請設定下列網路設定：

• 在 API 管理子網路上啟用 Azure Key Vault 的服務端點。
• 設定網路安全性群組 (NSG) 規則，以允許對 AzureKeyVault 和 AzureActiveDirectory 服務標籤的輸出流量。

如需詳細資料，請參閱在 VNet 中設定 Azure API 管理時的網路設定。

新增或編輯具名值

將金鑰保存庫祕密新增至 APIM

請參閱金鑰保存庫整合的必要條件。

重要

將金鑰保存庫密碼新增至 API 管理執行個體時，您必須具有從金鑰保存庫列出秘密的權限。

警告

在 API 管理中使用金鑰保存庫密碼時，請小心不要刪除用來存取金鑰保存庫的祕密、金鑰保存庫或受控識別。

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。

2. 在 [API] 下，選取 [具名值]>[+新增]。

3. 輸入名稱識別碼，然後輸入用來參考原則屬性的顯示名稱。

4. 在 [實值型別] 中，選取 [金鑰保存庫]。

5. 輸入金鑰保存庫祕密的識別碼 (沒有版本)，或選擇 [選取] 從金鑰保存庫選取祕密。

   重要

   如果您自行輸入金鑰保存庫祕密識別碼，請確定這沒有版本資訊。 否則，祕密不會在金鑰保存庫更新之後自動在 API 管理中輪替。

6. 在 [用戶端身分識別] 中，選取系統指派或現有的使用者指派受控識別。 了解如何在 API 管理服務中新增或修改受控識別。

   注意

   身分識別需要從金鑰保存庫取得和列出祕密的權限。 如果您尚未設定金鑰保存庫的存取權，API 管理會提示您，以便可以使用必要的權限自動設定身分識別。

7. 新增一或多個選用的標籤以協助整理您的具名值，然後儲存。

8. 選取 建立。

   

將純文字或祕密值新增至 APIM

入口網站

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
2. 在 [API] 下，選取 [具名值]>[+新增]。
3. 輸入名稱識別碼，然後輸入用來參考原則屬性的顯示名稱。
4. 在 [實值型別] 中，選取 [純文字] 或 [祕密]。
5. 在 [值] 中，輸入字串或原則運算式。
6. 新增一或多個選用的標籤以協助整理您的具名值，然後儲存。
7. 選取 建立。

建立具名值之後，選取名稱後即可編輯。 如果您變更顯示名稱，則任何參考該具名值的原則將會自動更新為使用新的顯示名稱。

Azure CLI

開始使用 Azure CLI：

• 在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。

  

• 若要在本地執行 CLI 參考命令，請安裝 Azure CLI。 若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。

  • 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，完成驗證程序。 如需其他登入選項，請參閱使用 Azure CLI 登入。

  • 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。

  • 執行 az version 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。

若要新增具名值，請使用 az apim nv create 命令：

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

建立具名值之後，您可以使用 az apim nv update 命令加以更新。 若要查看全部具名值，請執行 az apim nv list 命令：

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

若要查看您為此範例建立的具名值詳細資料，請執行 az apim nv show 命令：

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

此範例是祕密值。 上述命令不會傳回值。 若要查看此值，請執行 az apim nv show-secret 命令：

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

若要刪除具名值，請使用 az apim nv delete 命令：

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

使用具名值

本節中的範例會使用下表所示的具名值。

名稱	值	祕密
ContosoHeader	TrackingId	False
ContosoHeaderValue	••••••••••••••••••••••	True
ExpressionProperty	@(DateTime.Now.ToString())	False
ContosoHeaderValue2	This is a header value.	False

若要在原則中使用具名值，請以兩對大括弧括住顯示名稱 (例如 {{ContosoHeader}})，如下列範例所示：

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

在此範例中，ContosoHeader 是做為 set-header 原則中標頭的名稱，且 ContosoHeaderValue 是用來做為該標頭的值。 在 API 管理閘道的要求或回應期間評估此原則時，{{ContosoHeader}} 和 {{ContosoHeaderValue}} 會換成各自的值。

如前述範例所示，具名值可以作為完整的屬性或元素值使用，但它們也可以插入部分的常值文字運算式或與之結合，如以下範例所示：

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

具名值也可以包含原則運算式。 下例範例使用 ExpressionProperty 運算式。

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

評估此原則時，{{ExpressionProperty}} 會取代為其值 @(DateTime.Now.ToString())。 因為該值是原則運算式，所以會評估運算式，且原則會繼續執行。

您可以在 Azure 入口網站或開發人員入口網站測試此項目，方法是呼叫原則中包含範圍內具名值的作業。 在下列範例中，會使用前兩個含具名值的範例 set-header 原則來呼叫作業。 請注意，回應中包含兩個使用含具名值的原則設定的自訂標頭。

如果您在輸出 API 追蹤中查看呼叫，而此呼叫包含前述兩個原則範例 (有具名值)，則您會看到兩個已插入具名值的 set-header 原則，以及具名值 (包含原則運算式) 的原則運算式評估。

字串內插補點也可以與具名值搭配使用。

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

CustomHeader 的值將會是 The URL encoded value is This+is+a+header+value.。

警告

如果原則參考 Azure Key Vault 中的祕密，則金鑰保存庫的值會顯示給可存取已對於 API 要求追蹤啟用訂閱的使用者。

雖然具名值可以包含原則運算式，但不可包含其他具名值。 如果使用包含具名值參考的文字作為值，例如 Text: {{MyProperty}}，則不會解析和取代該參考。

刪除具名值

若要刪除具名值，請選取名稱，然後從捷徑功能表 (...) 中選取 [刪除]。

重要

如有任何 API 管理原則參考該具名值，則除非從全部使用該具名值的原則中移除，否則無法成功刪除該具名值。

下一步

• 深入了解原則的使用方式
  • API 管理中的原則
  • 原則參考文件
  • 原則運算式