使用訂用帳戶金鑰來呼叫 API

已完成

發佈 API 時，您通常想要對可透過閘道存取 API 的人員進行某種程度的控管。 訂用帳戶金鑰是用來限制 API 存取的其中一個方法。

您會在這裡了解如何使用訂用帳戶金鑰來保護 API。

訂用帳戶和金鑰

若要保護 API，您可以使用訂用帳戶金鑰。

注意

在生產 API 管理環境中，您通常會結合訂用帳戶金鑰與其他機制，以保護 API 免於未經授權的使用，例如憑證驗證或 OAuth 2.0 授權。 這些不在此課程模組範圍之内。

訂用帳戶金鑰是自動產生且獨一無二的字串，透過用戶端要求的標頭進行傳遞，也能以 URL 中查詢字串的形式傳遞。 此金鑰會與可將範圍設定為不同區域的訂用帳戶直接相關，這樣可以對權限和原則進行精細的控制。 主要訂用帳戶的範圍如下:

• 所有 API
• 單一 API
• 產品

呼叫受保護 API 的應用程式必須在要求中包含金鑰。

您可以隨時重新產生這些訂用帳戶金鑰。 例如，若您懷疑訂用帳戶金鑰被分享給未經授權的使用者，您可以重新產生金鑰。

每個訂用帳戶都有兩個金鑰：主要和次要。 擁有兩個金鑰會讓您更易於重新產生金鑰。 例如，若您想要變更主要金鑰並避免停機，請在應用程式中使用次要金鑰。

針對已啟用訂用帳戶的產品，您必須在對該產品中的 API 進行呼叫時提供金鑰。 身為開發人員，您可以藉由提交訂用帳戶要求來取得金鑰。 此流程是 API 管理 (APIM) 工作流程的核心部分。

注意

建立新的使用者並為其提供訂用帳戶金鑰以讓使用者能夠存取 API 是 APIM 工作流程的核心部分，但不在本課程模組的範圍內。

使用訂用帳戶金鑰來呼叫 API

應用程式必須在呼叫訂用帳戶所保護的 API 端點時，於所有 HTTP 要求中包含有效的金鑰。 金鑰可以在要求標頭中傳遞，或以 URL 中的查詢字串來傳遞。

預設的標頭名稱是 Ocp-Apim-Subscription-Key，而預設的查詢字串為 subscription-key。

若要測試 API 呼叫，您可以使用開發人員入口網站 (若在您的服務層級可供使用)、curl 之類的命令列工具，或其他 REST 用戶端工具。

以下是使用 curl 命令在要求標頭中傳遞金鑰的 GET 要求範例:

curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path

以下為範例 curl 命令，可在 URL 中將金鑰當成查詢字串來傳遞：

curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>

如果金鑰不是在標頭中傳遞，或在 URL 中以查詢字串形式傳遞，您將會收到來自 API 閘道的 「401 存取遭拒」回應。