使用订阅保护 API

已完成

當您透過 APIM 發佈 API 時，使用訂用帳戶金鑰安全地存取這些 API 是簡單且常見的方式。 需要使用已發佈 API 的開發人員在呼叫這些 API 時，必須在 HTTP 要求中包含有效的訂用帳戶金鑰。 API 管理閘道會拒絕沒有訂用帳戶金鑰的呼叫，而且不會將呼叫轉送至後端服務。

若要取得用於存取 API 的訂用帳戶金鑰，則需要訂用帳戶。 訂用帳戶基本上是一組訂用帳戶金鑰的具名容器。 需要取用已發行 API 的開發人員可以取得訂用帳戶。 而且不需要 API 發行者的核准。 API 發行者還可以為 API 取用者直接建立訂用帳戶。

注意

API 管理也支援其他機制來保護對 API 的存與，包括 OAuth2.0、用戶端憑證和 IP 允許清單。

訂用帳戶與金鑰

訂用帳戶金鑰是唯一自動產生的金鑰，可以在用戶端要求的標頭中傳遞，也能以查詢字串參數形式傳遞。 金鑰與訂用帳戶直接相關，範圍可以限定在不同的區域。 訂用帳戶可讓您更精確地控制權限及原則。

這三個主要訂用帳戶的範圍如下：

範圍	詳細資料
所有 API	適用於可從閘道存取的每個 API
單一 API	此範圍適用於單一匯入的 API 與其所有端點
Products	產品是您在 API 管理中設定的一或多個 API 的集合。 您可以將 API 指派給一個以上的產品。 產品可以有不同的存取規則、使用量配額與使用規定。

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

您隨時都能重新產生這些訂用帳戶金鑰，例如，若您懷疑金鑰已與未經授權的使用者共用。

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

針對已啟用訂用帳戶的產品，用戶端必須在對該產品中的 API 進行呼叫時提供金鑰。 開發人員可以透過提交訂用帳戶要求來取得金鑰。 如果您核准該要求，則必須安全地向他們傳送訂用帳戶金鑰，例如以加密訊息傳送。 此步驟是 API 管理工作流程的核心部分。

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

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

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

若要充分測試 API 呼叫，您可以使用開發人員入口網站或命令列工具，例如 curl。 以下是使用開發人員入口網站的 GET 要求範例，其顯示訂用帳戶金鑰標頭：

以下是如何使用 curl，在要求標頭中傳遞金鑰的方式：

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 存取遭拒」回應。