適用於 JavaScript 的 Azure Key Vault 機密用戶端庫 - 版本 4.10.0

Azure Key Vault 是一項服務，可讓您使用安全密鑰來加密驗證金鑰、記憶體帳戶密鑰、數據加密密鑰、.pfx 檔案和密碼。如果您想要深入瞭解 Azure Key Vault，建議您檢閱：什麼是 Azure Key Vault？

Azure Key Vault 秘密管理可讓您安全地儲存及嚴格控制令牌、密碼、憑證、API 密鑰和其他秘密的存取。

在 Node.js 應用程式中，使用 Azure Key Vault 秘密的用戶端連結庫來：

取得、設定和刪除秘密。
更新秘密及其屬性。
備份和還原秘密。
取得、清除或復原已刪除的秘密。
取得秘密的所有版本。
取得所有秘密。
取得所有已刪除的秘密。

注意：由於 Azure Key Vault 服務限制，無法在瀏覽器中使用此套件，請參閱本檔以取得指引。

主要連結：

入門指南

目前支援的環境

LTS 版本的 Node.js

先決條件

Azure 訂用帳戶
Key Vault 資源
現有的 azure Key Vault 。如果您需要建立金鑰儲存庫，您可以依照本檔案中的步驟，在 Azure 入口網站中執行此動作，。或者，您可以依照本文件中的步驟來使用 Azure CLI。

安裝套件

使用 npm 安裝 Azure Key Vault 秘密客戶端連結庫：

npm install @azure/keyvault-secrets

安裝身分識別連結庫

Key Vault 用戶端會使用 Azure 身分識別連結庫進行驗證。使用 npm 安裝

npm install @azure/identity

設定 TypeScript

TypeScript 用戶必須安裝 Node 類型定義：

npm install @types/node

您也需要在 tsconfig.json中啟用 compilerOptions.allowSyntheticDefaultImports。請注意，如果您已啟用 compilerOptions.esModuleInterop，預設會啟用 allowSyntheticDefaultImports。如需詳細資訊，請參閱 TypeScript 的編譯程式選項手冊。

重要概念

秘密用戶端 是主要介面，可從 JavaScript 應用程式與 Azure Key Vault API 中秘密相關的 API 方法互動。初始化之後，它會提供一組基本方法，可用來建立、讀取、更新和刪除秘密。
秘密版本 是 Key Vault 中的秘密版本。每次使用者將值指派給唯一的秘密名稱時，就會建立該秘密的新版本。除非特定版本提供給查詢，否則依名稱擷取秘密一律會傳回指派的最新值。
虛刪除 可讓 Key Vault 支援刪除和清除兩個不同的步驟，因此不會立即遺失已刪除的秘密。只有當 Key Vault 已啟用虛刪除時，才會發生這種情況。
您可以從任何建立的秘密產生 秘密備份。這些備份是二進位數據，而且只能用來重新產生先前刪除的秘密。

使用 Azure Active Directory 進行驗證

Key Vault 服務依賴 Azure Active Directory 來驗證其 API 的要求。 @azure/identity 套件提供應用程式可用來執行這項作業的各種認證類型。的自述檔提供更多詳細數據和範例，讓您開始使用。

若要與 Azure Key Vault 服務互動，您必須建立 SecretClient 類別的實例、保存庫 url 和認證物件。本檔中所示的範例會使用名為 DefaultAzureCredential的認證物件，適用於大部分案例，包括本機開發和生產環境。此外，建議您在生產環境中使用受控識別進行驗證。

您可以在 Azure 身分識別檔中找到驗證方式及其對應認證類型的詳細資訊。

以下是快速範例。首先，匯入 DefaultAzureCredential 和 SecretClient。匯入這些項目之後，我們可以接著連線到 Key Vault 服務：

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our keys client and connect to the service
const client = new SecretClient(url, credential);

指定 Azure Key Vault 服務 API 版本

根據預設，此套件會使用最新的 Azure Key Vault 服務版本，7.1。唯一支援的其他版本是 7.0。您可以藉由在用戶端建構函式中設定選項 serviceVersion 來變更所使用的服務版本，如下所示：

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new SecretClient(url, credential, {
  serviceVersion: "7.0", // Or 7.1
});

範例

下列各節提供代碼段，這些代碼段涵蓋使用 Azure Key Vault 秘密的一些常見工作。這裡涵蓋的案例包括：

建立和設定秘密。
取得秘密。
使用屬性建立和更新秘密。
刪除秘密。
反覆運算秘密清單。

建立和設定秘密

setSecret 將提供的值指派給指定的秘密名稱。如果已有相同名稱的秘密存在，則會建立新版的秘密。

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

取得秘密

從保存庫讀取秘密的最簡單方式是依名稱取得秘密。這會擷取最新版本的秘密。如果您將其指定為選擇性參數的一部分，可以選擇性地取得不同的密鑰版本。

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const latestSecret = await client.getSecret(secretName);
console.log(`Latest version of the secret ${secretName}: `, latestSecret);

const specificSecret = await client.getSecret(secretName, {
  version: latestSecret.properties.version!,
});
console.log(
  `The secret ${secretName} at the version ${latestSecret.properties.version!}: `,
  specificSecret,
);

使用屬性建立和更新秘密

秘密可以擁有比其名稱和其值更多的資訊。它們也可以包含下列屬性：

tags：可用於搜尋和篩選秘密的任何索引鍵/值集。
contentType：可用來協助秘密接收者瞭解如何使用秘密值的任何字串。
enabled：布爾值，決定是否可以讀取秘密值。
notBefore：可以擷取秘密值的指定日期。
expiresOn：指定日期，之後無法擷取秘密值。

具有這些屬性的物件可以傳送為 setSecret的第三個參數，緊接在秘密的名稱和值後面，如下所示：

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.setSecret(secretName, "MySecretValue", {
  enabled: false,
});

這會建立新版的相同秘密，這會擁有最新的提供屬性。

屬性也可以更新為具有 updateSecretProperties的現有秘密版本，如下所示：

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.getSecret(secretName);
await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });

刪除秘密

beginDeleteSecret 方法會開始刪除秘密。只要有必要的資源可供使用，此程式就會在背景進行。

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

await client.beginDeleteSecret(secretName);

如果金鑰保存庫已啟用虛刪除，此作業只會將秘密標示為已刪除的秘密。無法更新已刪除的秘密。它們只能讀取、復原或清除。

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const poller = await client.beginDeleteSecret(secretName);

// You can use the deleted secret immediately:
const deletedSecret = poller.getResult();

// The secret is being deleted. Only wait for it if you want to restore it or purge it.
await poller.pollUntilDone();

// You can also get the deleted secret this way:
await client.getDeletedSecret(secretName);

// Deleted secrets can also be recovered or purged.

// recoverDeletedSecret returns a poller, just like beginDeleteSecret.
const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
await recoverPoller.pollUntilDone();

// And then, to purge the deleted secret:
await client.purgeDeletedSecret(secretName);

由於秘密需要一些時間才能完全刪除，beginDeleteSecret 會傳回 Poller 物件，以根據我們的指導方針追蹤基礎長時間執行作業：https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

接收的輪詢器可讓您呼叫 poller.getResult()來取得已刪除的秘密。您也可以等到刪除完成，方法是執行個別服務呼叫，直到刪除秘密，或等到程式完成為止：

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const poller = await client.beginDeleteSecret(secretName);

// You can use the deleted secret immediately:
let deletedSecret = poller.getResult();

// Or you can wait until the secret finishes being deleted:
deletedSecret = await poller.pollUntilDone();
console.log(deletedSecret);

等待秘密完全刪除的另一種方式是執行個別呼叫，如下所示：

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

console.log(`The secret ${secretName} is fully deleted`);

反覆運算秘密清單

使用 SecretClient，您可以擷取並逐一查看 Key Vault 中的所有秘密，以及透過所有已刪除的秘密和特定秘密的版本。下列 API 方法可供使用：

listPropertiesOfSecrets 只會在其最新版本中列出所有未刪除的秘密。
listDeletedSecrets 只會在其最新版本中列出所有已刪除的秘密。
listPropertiesOfSecretVersions 會根據秘密名稱列出秘密的所有版本。

這可以如下所示使用：

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

所有這些方法都會同時傳回所有可用結果。若要依頁面擷取它們，請在叫用您想要使用的 API 方法之後，立即新增 .byPage()，如下所示：

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

for await (const page of client.listPropertiesOfSecrets().byPage()) {
  for (const secretProperties of page) {
    console.log("Secret properties: ", secretProperties);
  }
}
for await (const page of client.listDeletedSecrets().byPage()) {
  for (const deletedSecret of page) {
    console.log("Deleted secret: ", deletedSecret);
  }
}
for await (const page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
  for (const versionProperties of page) {
    console.log("Version properties: ", versionProperties);
  }
}

故障排除

如需如何診斷各種失敗案例的詳細資訊，請參閱我們的疑難解答指南。

啟用記錄可能有助於找出有關失敗的實用資訊。若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在運行時間啟用記錄，方法是在 setLogLevel中呼叫 @azure/logger：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

後續步驟

您可以透過下列連結找到更多程式碼範例：

貢獻

如果您想要參與此連結庫，請閱讀參與指南，以深入瞭解如何建置和測試程序代碼。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-06-12