驗證、要求和回應

Azure Key Vault 提供兩種類型的容器來儲存和管理雲端應用程式的秘密：

以下是用來存取每種物件類型的URL後綴

Azure Key Vault 支援 JSON 格式化的要求和回應。 搭配使用 HTTPS 與一些 URL 參數以及 JSON 編碼要求和回應本文，以將對 Azure Key Vault 的要求導向至有效的 Azure Key Vault URL。

本文涵蓋 Azure Key Vault 服務的特定內容。 如需使用 Azure REST 介面的一般資訊，包括驗證/授權以及如何取得存取令牌，請參閱 Azure REST API 參考。

要求 URL 結構

密鑰管理作業使用 HTTP 動詞命令，包括 DELETE、GET、PATCH 和 PUT。 現有金鑰物件的密碼編譯作業會使用 HTTP POST。

對於不支援特定 HTTP 動詞命令的用戶端，Azure Key Vault 允許搭配 X-HTTP-REQUEST 標頭使用 HTTP POST 來指定預期的動詞。 使用 POST 做為替代項目 (例如，取代 DELETE) 時，針對通常不需要 POST 的要求，包含空白本文。

若要在 Azure Key Vault 中使用物件，以下是範例 URL：

• 若要在 Key Vault 中 CREATE (建立) 稱為 TESTKEY 的金鑰，請使用 - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• 若要將名為 IMPORTEDKEY 的金鑰匯入 Key Vault 使用 - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

• 若要在 Key Vault 中取得名為 MYSECRET 的秘密，請使用 - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

• 若在 Key Vault 中使用名為 TESTKEY 的金鑰簽署摘要， 請使用 - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

• 對 Key Vault 提出要求的授權單位一律如下，

  • 保存庫：https://{keyvault-name}.vault.azure.net/
  • 針對受控 HSM： https://{HSM-name}.managedhsm.azure.net/ 金鑰一律儲存在 /keys 路徑下，而秘密一律儲存在 /secrets 路徑下。

支援的 API 版本

Azure Key Vault 服務支援通訊協定版本控制，以提供與下層用戶端的相容性，但並非所有功能都可供這些用戶端使用。 客戶端必須使用 api-version 查詢字串參數來指定其支援的通訊協定版本，因為沒有預設值。

Azure Key Vault 通訊協定版本遵循使用 {YYYY}.{MM}.{DD} 格式的日期編號方式。

要求本文需求

根據 HTTP 規格，GET 作業不得有要求內容，而 POST 和 PUT 作業則必須具有要求內容。 DELETE 作業中的主體在 HTTP 中是選擇性的。

除非在作業描述中另有說明，否則要求本文內容類型必須是 application/json，且必須包含符合內容類型的串行化 JSON 物件。

除非在作業描述中另有說明，否則 Accept 要求標頭必須包含 application/json 媒體類型。

回應本文格式

除非在作業描述中另有說明，否則成功和失敗作業的回應本文內容類型都是 application/json，並包含詳細的錯誤資訊。

使用 HTTP POST 做為替代方案

某些用戶端可能無法使用特定 HTTP 動詞，例如 PATCH 或 DELETE。 若用戶端也包含 "X-HTTP-METHOD" 標頭來指定原始 HTTP 指令動詞，則 Azure Key Vault 支援 HTTP POST 做為這些用戶端的替代方法。 本檔所定義之每個 API 都支援 HTTP POST。

處理錯誤回應

錯誤處理會使用 HTTP 狀態代碼。 一般結果如下：

• 2xx – 成功：用於一般作業。 回應本文包含預期的結果

• 3xx – 重新導向：可能會傳回 304「未修改」，以滿足條件式 GET。 未來可能會使用其他 3xx 代碼來指出 DNS 和路徑變更。

• 4xx – 用戶端錯誤：用於不正確的要求、遺漏密鑰、語法錯誤、無效的參數、驗證錯誤等。回應本文包含詳細的錯誤說明。

• 5xx – 伺服器錯誤：用於內部伺服器錯誤。 回應本文會包含摘要錯誤資訊。

  系統的設計目的是在 Proxy 或防火牆後方運作。 因此，用戶端可能會收到其他錯誤碼。

  發生問題時，Azure Key Vault 也會傳回回應本文中的錯誤資訊。 回應本文已格式化為 JSON，並採用下列格式：

{  
  "error":  
  {  
    "code": "BadArgument",  
    "message":  

      "’Foo’ is not a valid argument for ‘type’."  
    }  
  }  
}  

驗證需求

對 Azure Key Vault 的所有要求都必須經過驗證。 Azure Key Vault 支援使用 OAuth2 [RFC6749] 取得的 Microsoft Entra 存取令牌。

如需註冊應用程式並使用 Azure Key Vault 進行驗證的詳細資訊，請參閱 使用 Microsoft Entra ID 註冊用戶端應用程式。

存取權杖必須使用 HTTP 授權標頭傳送至服務：

PUT /keys/MYKEY?api-version=<api_version>  HTTP/1.1  
Authorization: Bearer <access_token>  

未提供存取令牌，或當服務不接受令牌時，HTTP 401 錯誤會傳回給用戶端，並包含 WWW-Authenticate 標頭，例如：

401 Not Authorized  
WWW-Authenticate: Bearer authorization="…", resource="…"  

WWW-Authenticate 標頭上的參數如下：

• authorization：OAuth2 授權服務的位址，可用來取得要求的存取令牌。

• resource：要用於授權要求的資源名稱（https://vault.azure.net）。