Pustaka klien Azure Key Vault Secret untuk JavaScript - versi 4.11.2

Azure Key Vault adalah layanan yang memungkinkan Anda mengenkripsi kunci autentikasi, kunci akun penyimpanan, kunci enkripsi data, file .pfx, dan kata sandi dengan menggunakan kunci aman. Jika Anda ingin tahu lebih banyak tentang Azure Key Vault, Anda mungkin ingin mengulas: Apa itu Azure Key Vault?

Manajemen Azure Key Vault Secrets memungkinkan Anda menyimpan dan mengontrol akses ke token, kata sandi, sertifikat, kunci API, dan rahasia lainnya dengan aman dan mengontrol secara ketat.

Gunakan pustaka klien untuk Azure Key Vault Rahasia di aplikasi Node.js Anda untuk:

Dapatkan, atur, dan hapus rahasia.
Perbarui rahasia dan atributnya.
Cadangkan dan pulihkan rahasia.
Dapatkan, hapus menyeluruh, atau pulihkan rahasia yang dihapus.
Dapatkan semua versi rahasia.
Dapatkan semua rahasia.
Dapatkan semua rahasia yang dihapus.

Catatan: Paket ini tidak dapat digunakan di browser karena batasan layanan Azure Key Vault, silakan merujuk ke dokumen ini untuk panduan.

Tautan kunci:

Kode sumber
Paket (npm)
Dokumentasi Referensi API
dokumentasi produk
Sampel

Memulai Langkah Pertama

Lingkungan yang didukung saat ini

Versi LTS dari Node.js

Prasyarat

Langganan Azure
Sumber daya Key Vault
Azure Key Vault yang ada. Jika Anda perlu membuat brankas kunci, Anda dapat melakukannya di portal Azure dengan mengikuti langkah-langkah di dokumen ini. Atau, Anda dapat menggunakan Azure CLI dengan mengikuti langkah-langkah di dokumen ini.

Pasang paketnya

Instal pustaka klien Azure Key Vault Secret menggunakan npm:

npm install @azure/keyvault-secrets

Menginstal pustaka identitas

Klien Key Vault mengautentikasi menggunakan Pustaka Identitas Azure. Instal juga menggunakan npm

npm install @azure/identity

Mengonfigurasi TypeScript

Pengguna TypeScript harus menginstal definisi jenis Node:

npm install @types/node

Anda juga perlu mengaktifkan compilerOptions.allowSyntheticDefaultImports di tsconfig.jsonAnda. Perhatikan bahwa jika Anda telah mengaktifkan compilerOptions.esModuleInterop, allowSyntheticDefaultImports diaktifkan secara default. Lihat opsi kompilator TypeScript untuk informasi selengkapnya.

Konsep utama

Secret client adalah antarmuka utama untuk berinteraksi dengan metode API yang terkait dengan rahasia di API Azure Key Vault dari aplikasi JavaScript. Setelah diinisialisasi, ini menyediakan serangkaian metode dasar yang dapat digunakan untuk membuat, membaca, memperbarui, dan menghapus rahasia.
Versi Rahasia adalah versi rahasia dalam Key Vault. Setiap kali pengguna menetapkan nilai ke nama rahasia unik, versi baru rahasia tersebut dibuat. Mengambil rahasia dengan nama akan selalu mengembalikan nilai terbaru yang ditetapkan, kecuali versi tertentu disediakan untuk kueri.
Penghapusan sementara memungkinkan Key Vault mendukung penghapusan dan penghapusan menyeluruh sebagai dua langkah terpisah, sehingga rahasia yang dihapus tidak segera hilang. Ini hanya terjadi jika Key Vault mengaktifkan soft-delete.
cadangan Rahasia dapat dihasilkan dari rahasia yang dibuat. Cadangan ini berasal sebagai data biner, dan hanya dapat digunakan untuk meregenerasi rahasia yang dihapus sebelumnya.

Mengautentikasi dengan Azure Active Directory

Layanan Key Vault bergantung pada Azure Active Directory untuk mengautentikasi permintaan ke API-nya. Paket @azure/identity menyediakan berbagai jenis kredensial yang dapat digunakan aplikasi Anda untuk melakukan ini. README untuk @azure/identity memberikan detail dan sampel lebih lanjut untuk membantu Anda memulai.

Untuk berinteraksi dengan layanan Azure Key Vault, Anda harus membuat instans kelas SecretClient, url vault dan objek kredensial. Contoh yang ditunjukkan dalam dokumen ini menggunakan objek kredensial bernama DefaultAzureCredential, yang sesuai untuk sebagian besar skenario, termasuk lingkungan pengembangan dan produksi lokal. Selain itu, sebaiknya gunakan identitas terkelola untuk autentikasi di lingkungan produksi.

Anda dapat menemukan informasi selengkapnya tentang berbagai cara autentikasi dan jenis kredensial yang sesuai di dokumentasi Azure Identitas.

Berikut adalah contoh singkatnya. Pertama, impor DefaultAzureCredential dan SecretClient. Setelah ini diimpor, selanjutnya kita dapat terhubung ke layanan 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 secrets client and connect to the service
const client = new SecretClient(url, credential);

Untuk lingkungan browser, gunakan InteractiveBrowserCredential dari paket @azure/identity untuk mengautentikasi.

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

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

Menentukan versi API layanan Azure Key Vault

Secara default, paket ini menggunakan versi layanan Azure Key Vault terbaru yaitu 7.1. Satu-satunya versi lain yang didukung adalah 7.0. Anda dapat mengubah versi layanan yang digunakan dengan mengatur opsi serviceVersion di konstruktor klien seperti yang ditunjukkan di bawah ini:

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
});

Contoh

Bagian berikut menyediakan cuplikan kode yang mencakup beberapa tugas umum menggunakan Rahasia Azure Key Vault. Skenario yang dibahas di sini terdiri dari:

Membuat dan mengaturrahasia .
Mendapatkanrahasia .
Membuat dan memperbarui rahasia dengan atribut.
Menghapusrahasia .
Iterasi daftar rahasia.

Membuat dan mengatur rahasia

setSecret menetapkan nilai yang disediakan ke nama rahasia yang ditentukan. Jika rahasia dengan nama yang sama sudah ada, maka versi baru rahasia dibuat.

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);

Mendapatkan rahasia

Cara paling sederhana untuk membaca rahasia kembali dari brankas adalah dengan mendapatkan rahasia berdasarkan nama. Ini akan mengambil versi terbaru rahasia. Anda dapat secara opsional mendapatkan versi kunci yang berbeda jika Anda menentukannya sebagai bagian dari parameter opsional.

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,
);

Membuat dan memperbarui rahasia dengan atribut

Rahasia dapat memiliki lebih banyak informasi daripada namanya dan nilainya. Mereka juga dapat menyertakan atribut berikut:

tags: Sekumpulan kunci-nilai yang dapat digunakan untuk mencari dan memfilter rahasia.
contentType: String apa pun yang dapat digunakan untuk membantu penerima rahasia memahami cara menggunakan nilai rahasia.
enabled: Nilai boolean yang menentukan apakah nilai rahasia dapat dibaca atau tidak.
notBefore: Tanggal tertentu setelah nilai rahasia dapat diambil.
expiresOn: Tanggal tertentu setelah nilai rahasia tidak dapat diambil.

Objek dengan atribut ini dapat dikirim sebagai parameter ketiga setSecret, tepat setelah nama dan nilai rahasia, sebagai berikut:

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,
});

Ini akan membuat versi baru dari rahasia yang sama, yang akan memiliki atribut terbaru yang disediakan.

Atribut juga dapat diperbarui ke versi rahasia yang ada dengan updateSecretProperties, sebagai berikut:

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 });

Menghapus rahasia

Metode beginDeleteSecret memulai penghapusan Rahasia. Proses ini akan terjadi di latar belakang segera setelah sumber daya yang diperlukan tersedia.

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);

Jika soft-delete diaktifkan untuk Key Vault, operasi ini hanya akan memberi label rahasia sebagai rahasia deleted. Rahasia yang dihapus tidak dapat diperbarui. Mereka hanya dapat dibaca, dipulihkan, atau dibersihkan.

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);

Karena Rahasia membutuhkan waktu untuk dihapus sepenuhnya, beginDeleteSecret mengembalikan objek Poller yang melacak Operasi Jangka Panjang yang mendasar sesuai dengan pedoman kami: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Poller yang diterima akan memungkinkan Anda untuk mendapatkan rahasia yang dihapus dengan memanggil ke poller.getResult(). Anda juga dapat menunggu hingga penghapusan selesai, baik dengan menjalankan panggilan layanan individual hingga rahasia dihapus, atau dengan menunggu hingga proses selesai:

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);

Cara lain untuk menunggu sampai rahasia sepenuhnya dihapus adalah dengan melakukan panggilan individual, sebagai berikut:

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`);

Iterasi daftar rahasia

Dengan menggunakan SecretClient, Anda dapat mengambil dan mengulangi semua rahasia di Key Vault, serta melalui semua rahasia yang dihapus dan versi rahasia tertentu. Metode API berikut tersedia:

listPropertiesOfSecrets akan mencantumkan semua rahasia Anda yang tidak dihapus berdasarkan namanya, hanya pada versi terbarunya.
listDeletedSecrets akan mencantumkan semua rahasia Anda yang dihapus berdasarkan namanya, hanya pada versi terbarunya.
listPropertiesOfSecretVersions akan mencantumkan semua versi rahasia berdasarkan nama rahasia.

Yang dapat digunakan sebagai berikut:

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);
}

Semua metode ini akan mengembalikan semua hasil yang tersedia sekaligus. Untuk mengambilnya berdasarkan halaman, tambahkan .byPage() tepat setelah memanggil metode API yang ingin Anda gunakan, sebagai berikut:

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);
  }
}

Penyelesaian Masalah

Lihat panduan pemecahan masalah kami untuk detail tentang cara mendiagnosis berbagai skenario kegagalan.

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Langkah selanjutnya

Anda dapat menemukan lebih banyak sampel kode melalui tautan berikut:

Berpartisipasi

Jika Anda ingin berkontribusi ke library ini, silakan baca panduan contributor untuk mempelajari lebih lanjut cara membuat dan menguji kode.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-05-05