SecretClient class

  • 參考
套件:
@azure/keyvault-secrets

SecretClient 提供在 Azure 金鑰保存庫中管理KeyVaultSecret的方法。 用戶端支援建立、擷取、更新、刪除、清除、備份、還原及列出 KeyVaultSecrets。 用戶端也支援針對已啟用虛刪除的 Azure 金鑰保存庫列出DeletedSecret。

建構函式

SecretClient(string, TokenCredential, SecretClientOptions)

建立 SecretClient 的實例。

使用方式範例：

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

let vaultUrl = `https://<MY KEYVAULT HERE>.vault.azure.net`;
let credentials = new DefaultAzureCredential();

let client = new SecretClient(vaultUrl, credentials);

屬性

vaultUrl

保存庫的基底 URL

方法

backupSecret(string, BackupSecretOptions)

要求將指定秘密的備份下載至用戶端。 將會下載所有版本的秘密。 此作業需要秘密/備份許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
let backupResult = await client.backupSecret("MySecretName");

備份指定的秘密。
beginDeleteSecret(string, BeginDeleteSecretOptions)

刪除儲存在 Azure 金鑰保存庫中的秘密。 此函式會傳回長時間執行的作業輪詢器，可讓您無限期等候，直到刪除秘密為止。

此作業需要秘密/刪除許可權。

使用方式範例：

const client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

const deletePoller = await client.beginDeleteSecret("MySecretName");

// Serializing the poller
const serialized = deletePoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginDeleteSecret("MySecretName", { resumeFrom: serialized });

// Waiting until it's done
const deletedSecret = await deletePoller.pollUntilDone();
console.log(deletedSecret);

從指定的金鑰保存庫刪除秘密。
beginRecoverDeletedSecret(string, BeginRecoverDeletedSecretOptions)

復原指定保存庫中已刪除的秘密。 此函式會傳回長時間執行的作業輪詢器，可讓您無限期等候秘密復原。

此作業需要秘密/復原許可權。

使用方式範例：

const client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

const deletePoller = await client.beginDeleteSecret("MySecretName");
await deletePoller.pollUntilDone();

const recoverPoller = await client.beginRecoverDeletedSecret("MySecretName");

// Serializing the poller
const serialized = recoverPoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginRecoverDeletedSecret("MySecretName", { resumeFrom: serialized });

// Waiting until it's done
const deletedSecret = await recoverPoller.pollUntilDone();
console.log(deletedSecret);

將已刪除的秘密復原至最新版本。
getDeletedSecret(string, GetDeletedSecretOptions)

getDeletedSecret 方法會傳回指定的已刪除秘密及其屬性。 此作業需要秘密/取得許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
await client.getDeletedSecret("MyDeletedSecret");

取得指定的已刪除秘密。
getSecret(string, GetSecretOptions)

getSecret 方法適用于儲存在 Azure 金鑰保存庫中的任何秘密。 此作業需要秘密/取得許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
let secret = await client.getSecret("MySecretName");

從指定的金鑰保存庫取得指定的秘密。
listDeletedSecrets(ListDeletedSecretsOptions)

逐一查看保存庫中已刪除的秘密。 回應中提供完整密碼識別碼和屬性。 秘密不會傳回任何值。 此作業需要秘密/清單許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("deleted secret: ", deletedSecret);
}

列出保存庫中的所有秘密。
listPropertiesOfSecrets(ListPropertiesOfSecretsOptions)

逐一查看保存庫中所有秘密的最新版本。 回應中提供完整密碼識別碼和屬性。 秘密不會傳回任何值。 此作業需要秘密/清單許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
for await (const secretProperties of client.listPropertiesOfSecrets()) {
  const secret = await client.getSecret(secretProperties.name);
  console.log("secret: ", secret);
}

列出保存庫中的所有秘密。
listPropertiesOfSecretVersions(string, ListPropertiesOfSecretVersionsOptions)

逐一查看保存庫中指定秘密的所有版本。 回應中提供完整密碼識別碼和屬性。 秘密不會傳回任何值。 此作業需要秘密/清單許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
for await (const secretProperties of client.listPropertiesOfSecretVersions("MySecretName")) {
  const secret = await client.getSecret(secretProperties.name);
  console.log("secret version: ", secret);
}
purgeDeletedSecret(string, PurgeDeletedSecretOptions)

清除刪除的秘密作業會永久移除秘密，而不會有復原的可能性。 此作業只能在已啟用虛刪除的保存庫上啟用。 此作業需要秘密/清除許可權。

使用方式範例：

const client = new SecretClient(url, credentials);
const deletePoller = await client.beginDeleteSecret("MySecretName");
await deletePoller.pollUntilDone();
await client.purgeDeletedSecret("MySecretName");

永久刪除指定的秘密。
restoreSecretBackup(Uint8Array, RestoreSecretBackupOptions)

將備份的秘密及其所有版本還原至保存庫。 此作業需要秘密/還原許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
let mySecretBundle = await client.backupSecret("MySecretName");
// ...
await client.restoreSecretBackup(mySecretBundle);

將備份的秘密還原至保存庫。
setSecret(string, string, SetSecretOptions)

setSecret 方法會將秘密或秘密版本新增至 Azure 金鑰保存庫。 如果指定的密碼已存在，Azure 金鑰保存庫會建立該密碼的新版本。 此作業需要秘密/設定許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

在指定的金鑰保存庫中新增秘密。
updateSecretProperties(string, string, UpdateSecretPropertiesOptions)

updateSecret 方法會變更現有預存秘密的指定屬性。 要求中未指定的屬性會保持不變。 無法變更密碼本身的值。 此作業需要秘密/設定許可權。

使用方式範例：

let secretName = "MySecretName";
let client = new SecretClient(url, credentials);
let secret = await client.getSecret(secretName);
await client.updateSecretProperties(secretName, secret.properties.version, { enabled: false });

更新指定金鑰保存庫中與指定秘密相關聯的屬性。

建構函式詳細資料

SecretClient(string, TokenCredential, SecretClientOptions)

建立 SecretClient 的實例。

使用方式範例：

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

let vaultUrl = `https://<MY KEYVAULT HERE>.vault.azure.net`;
let credentials = new DefaultAzureCredential();

let client = new SecretClient(vaultUrl, credentials);

new SecretClient(vaultUrl: string, credential: TokenCredential, pipelineOptions?: SecretClientOptions)

參數

vaultUrl

string

保存庫的基底 URL。 您應該驗證此 URL 參考有效的金鑰保存庫資源。 如需詳細資訊，請參閱＜https://aka.ms/azsdk/blog/vault-uri＞。

credential
TokenCredential

實作 介面的物件， TokenCredential 用來驗證對服務的要求。 @azure/identity使用套件來建立符合您需求的認證。

pipelineOptions
SecretClientOptions

用來設定 金鑰保存庫 API 要求的管線選項。 省略此參數以使用預設管線組態。

屬性詳細資料

vaultUrl

保存庫的基底 URL

vaultUrl: string

屬性值

string

方法詳細資料

backupSecret(string, BackupSecretOptions)

要求將指定秘密的備份下載至用戶端。 將會下載所有版本的秘密。 此作業需要秘密/備份許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
let backupResult = await client.backupSecret("MySecretName");

備份指定的秘密。

function backupSecret(secretName: string, options?: BackupSecretOptions): Promise<undefined | Uint8Array>

參數

secretName

string

秘密的名稱。

options
BackupSecretOptions

選擇性參數。

傳回

Promise<undefined | Uint8Array>

beginDeleteSecret(string, BeginDeleteSecretOptions)

刪除儲存在 Azure 金鑰保存庫中的秘密。 此函式會傳回長時間執行的作業輪詢器，可讓您無限期等候，直到刪除秘密為止。

此作業需要秘密/刪除許可權。

使用方式範例：

const client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

const deletePoller = await client.beginDeleteSecret("MySecretName");

// Serializing the poller
const serialized = deletePoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginDeleteSecret("MySecretName", { resumeFrom: serialized });

// Waiting until it's done
const deletedSecret = await deletePoller.pollUntilDone();
console.log(deletedSecret);

從指定的金鑰保存庫刪除秘密。

function beginDeleteSecret(name: string, options?: BeginDeleteSecretOptions): Promise<PollerLike<PollOperationState<DeletedSecret>, DeletedSecret>>

參數

name

string

options
BeginDeleteSecretOptions

選擇性參數。

傳回

Promise<PollerLike<PollOperationState<DeletedSecret>, DeletedSecret>>

beginRecoverDeletedSecret(string, BeginRecoverDeletedSecretOptions)

復原指定保存庫中已刪除的秘密。 此函式會傳回長時間執行的作業輪詢器，可讓您無限期等候秘密復原。

此作業需要秘密/復原許可權。

使用方式範例：

const client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

const deletePoller = await client.beginDeleteSecret("MySecretName");
await deletePoller.pollUntilDone();

const recoverPoller = await client.beginRecoverDeletedSecret("MySecretName");

// Serializing the poller
const serialized = recoverPoller.toString();

// A new poller can be created with:
// const newPoller = await client.beginRecoverDeletedSecret("MySecretName", { resumeFrom: serialized });

// Waiting until it's done
const deletedSecret = await recoverPoller.pollUntilDone();
console.log(deletedSecret);

將已刪除的秘密復原至最新版本。

function beginRecoverDeletedSecret(name: string, options?: BeginRecoverDeletedSecretOptions): Promise<PollerLike<PollOperationState<SecretProperties>, SecretProperties>>

參數

name

string

options
BeginRecoverDeletedSecretOptions

選擇性參數。

傳回

Promise<PollerLike<PollOperationState<SecretProperties>, SecretProperties>>

getDeletedSecret(string, GetDeletedSecretOptions)

getDeletedSecret 方法會傳回指定的已刪除秘密及其屬性。 此作業需要秘密/取得許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
await client.getDeletedSecret("MyDeletedSecret");

取得指定的已刪除秘密。

function getDeletedSecret(secretName: string, options?: GetDeletedSecretOptions): Promise<DeletedSecret>

參數

secretName

string

秘密的名稱。

options
GetDeletedSecretOptions

選擇性參數。

傳回

Promise<DeletedSecret>

getSecret(string, GetSecretOptions)

getSecret 方法適用于儲存在 Azure 金鑰保存庫中的任何秘密。 此作業需要秘密/取得許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
let secret = await client.getSecret("MySecretName");

從指定的金鑰保存庫取得指定的秘密。

function getSecret(secretName: string, options?: GetSecretOptions): Promise<KeyVaultSecret>

參數

secretName

string

秘密的名稱。

options
GetSecretOptions

選擇性參數。

傳回

Promise<KeyVaultSecret>

listDeletedSecrets(ListDeletedSecretsOptions)

逐一查看保存庫中已刪除的秘密。 回應中提供完整密碼識別碼和屬性。 秘密不會傳回任何值。 此作業需要秘密/清單許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("deleted secret: ", deletedSecret);
}

列出保存庫中的所有秘密。

function listDeletedSecrets(options?: ListDeletedSecretsOptions): PagedAsyncIterableIterator<DeletedSecret, DeletedSecret[], PageSettings>

參數

options
ListDeletedSecretsOptions

選擇性參數。

傳回

PagedAsyncIterableIterator<DeletedSecret, DeletedSecret[], PageSettings>

listPropertiesOfSecrets(ListPropertiesOfSecretsOptions)

逐一查看保存庫中所有秘密的最新版本。 回應中提供完整密碼識別碼和屬性。 秘密不會傳回任何值。 此作業需要秘密/清單許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
for await (const secretProperties of client.listPropertiesOfSecrets()) {
  const secret = await client.getSecret(secretProperties.name);
  console.log("secret: ", secret);
}

列出保存庫中的所有秘密。

function listPropertiesOfSecrets(options?: ListPropertiesOfSecretsOptions): PagedAsyncIterableIterator<SecretProperties, SecretProperties[], PageSettings>

參數

options
ListPropertiesOfSecretsOptions

選擇性參數。

傳回

PagedAsyncIterableIterator<SecretProperties, SecretProperties[], PageSettings>

listPropertiesOfSecretVersions(string, ListPropertiesOfSecretVersionsOptions)

逐一查看保存庫中指定秘密的所有版本。 回應中提供完整密碼識別碼和屬性。 秘密不會傳回任何值。 此作業需要秘密/清單許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
for await (const secretProperties of client.listPropertiesOfSecretVersions("MySecretName")) {
  const secret = await client.getSecret(secretProperties.name);
  console.log("secret version: ", secret);
}

function listPropertiesOfSecretVersions(secretName: string, options?: ListPropertiesOfSecretVersionsOptions): PagedAsyncIterableIterator<SecretProperties, SecretProperties[], PageSettings>

參數

secretName

string

要擷取版本的秘密名稱。

options
ListPropertiesOfSecretVersionsOptions

選擇性參數。

傳回

PagedAsyncIterableIterator<SecretProperties, SecretProperties[], PageSettings>

purgeDeletedSecret(string, PurgeDeletedSecretOptions)

清除刪除的秘密作業會永久移除秘密，而不會有復原的可能性。 此作業只能在已啟用虛刪除的保存庫上啟用。 此作業需要秘密/清除許可權。

使用方式範例：

const client = new SecretClient(url, credentials);
const deletePoller = await client.beginDeleteSecret("MySecretName");
await deletePoller.pollUntilDone();
await client.purgeDeletedSecret("MySecretName");

永久刪除指定的秘密。

function purgeDeletedSecret(secretName: string, options?: PurgeDeletedSecretOptions): Promise<void>

參數

secretName

string

秘密的名稱。

options
PurgeDeletedSecretOptions

選擇性參數。

傳回

Promise<void>

restoreSecretBackup(Uint8Array, RestoreSecretBackupOptions)

將備份的秘密及其所有版本還原至保存庫。 此作業需要秘密/還原許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
let mySecretBundle = await client.backupSecret("MySecretName");
// ...
await client.restoreSecretBackup(mySecretBundle);

將備份的秘密還原至保存庫。

function restoreSecretBackup(secretBundleBackup: Uint8Array, options?: RestoreSecretBackupOptions): Promise<SecretProperties>

參數

secretBundleBackup

Uint8Array

與秘密配套相關聯的備份 Blob。

options
RestoreSecretBackupOptions

選擇性參數。

傳回

Promise<SecretProperties>

setSecret(string, string, SetSecretOptions)

setSecret 方法會將秘密或秘密版本新增至 Azure 金鑰保存庫。 如果指定的密碼已存在，Azure 金鑰保存庫會建立該密碼的新版本。 此作業需要秘密/設定許可權。

使用方式範例：

let client = new SecretClient(url, credentials);
await client.setSecret("MySecretName", "ABC123");

在指定的金鑰保存庫中新增秘密。

function setSecret(secretName: string, value: string, options?: SetSecretOptions): Promise<KeyVaultSecret>

參數

secretName

string

秘密的名稱。

value

string

密碼的值。

options
SetSecretOptions

選擇性參數。

傳回

Promise<KeyVaultSecret>

updateSecretProperties(string, string, UpdateSecretPropertiesOptions)

updateSecret 方法會變更現有預存秘密的指定屬性。 要求中未指定的屬性會保持不變。 無法變更密碼本身的值。 此作業需要秘密/設定許可權。

使用方式範例：

let secretName = "MySecretName";
let client = new SecretClient(url, credentials);
let secret = await client.getSecret(secretName);
await client.updateSecretProperties(secretName, secret.properties.version, { enabled: false });

更新指定金鑰保存庫中與指定秘密相關聯的屬性。

function updateSecretProperties(secretName: string, secretVersion: string, options?: UpdateSecretPropertiesOptions): Promise<SecretProperties>

參數

secretName

string

秘密的名稱。

secretVersion

string

秘密的版本。

options
UpdateSecretPropertiesOptions

選擇性參數。

傳回

Promise<SecretProperties>