JavaScript için Azure Key Vault Gizli dizi istemci kitaplığı - sürüm 4.10.0

Azure Key Vault, güvenli anahtarları kullanarak kimlik doğrulama anahtarlarını, depolama hesabı anahtarlarını, veri şifreleme anahtarlarını, .pfx dosyalarını ve parolaları şifrelemenizi sağlayan bir hizmettir. Azure Key Vault hakkında daha fazla bilgi edinmek isterseniz şunları gözden geçirmek isteyebilirsiniz: Azure Key Vault nedir?

Azure Key Vault Gizli Dizileri yönetimi belirteçlere, parolalara, sertifikalara, API anahtarlarına ve diğer gizli dizilere erişimi güvenli bir şekilde depolamanıza ve sıkı bir şekilde denetlemenize olanak tanır.

Node.js uygulamanızda Azure Key Vault Gizli Dizileri için istemci kitaplığını kullanarak:

Gizli dizileri alın, ayarlayın ve silin.
Gizli diziyi ve özniteliklerini güncelleştirin.
Bir gizli diziyi yedekleme ve geri yükleme.
Silinen gizli diziyi alma, temizleme veya kurtarma.
Bir gizli dizinin tüm sürümlerini alın.
Tüm gizli dizileri alın.
Silinen tüm gizli dizileri alın.

Not: Azure Key Vault hizmet sınırlamaları nedeniyle bu paket tarayıcıda kullanılamıyor, yönergeler için lütfen bu belge bakın.

Önemli bağlantılar:

Başlangıç Yapmak

Şu anda desteklenen ortamlar

Node.js LTS sürümleri

Önkoşullar

Azure aboneliği
Key Vault kaynağı
Mevcut Azure Key Vault. Anahtar kasası oluşturmanız gerekiyorsa, azure portalda bu belgeyi adımlarını izleyerek bunu yapabilirsiniz. Alternatif olarak, bu belgeyi adımları izleyerek Azure CLI'yı kullanabilirsiniz.

Paketi yükle

npm kullanarak Azure Key Vault Gizli anahtarı istemci kitaplığını yükleyin:

npm install @azure/keyvault-secrets

Kimlik kitaplığını yükleme

Key Vault istemcileri Azure Kimlik Kitaplığı'nı kullanarak kimlik doğrulaması yapar. Npm kullanarak da yükleyin

npm install @azure/identity

TypeScript'i yapılandırma

TypeScript kullanıcılarının Düğüm türü tanımlarının yüklü olması gerekir:

npm install @types/node

ayrıca tsconfig.jsoncompilerOptions.allowSyntheticDefaultImports etkinleştirmeniz gerekir. compilerOptions.esModuleInteropetkinleştirdiyseniz allowSyntheticDefaultImports varsayılan olarak etkin olduğunu unutmayın. Daha fazla bilgi için bkz. TypeScript'in derleyici seçenekleri el kitabı.

Temel kavramlar

Gizli Dizi istemcisi, Bir JavaScript uygulamasından Azure Key Vault API'sindeki gizli dizilerle ilgili API yöntemleriyle etkileşime geçmek için kullanılan birincil arabirimdir. Başlatıldıktan sonra, gizli dizileri oluşturmak, okumak, güncelleştirmek ve silmek için kullanılabilecek temel bir yöntem kümesi sağlar.
Gizli sürüm, Key Vault'taki bir gizli dizi sürümüdür. Kullanıcı benzersiz bir gizli dizi adına her değer atayışında, bu gizli dizinin yeni bir sürümü oluşturulur. Sorguya belirli bir sürüm sağlanmadığı sürece, gizli diziyi bir ada göre almak her zaman atanan en son değeri döndürür.
Geçici silme Key Vault'ların silmeyi ve temizlemeyi iki ayrı adım olarak desteklemesine olanak tanır, bu nedenle silinen gizli diziler hemen kaybolmaz. Bu durum yalnızca Key Vault geçici silme etkin olduğunda gerçekleşir.
Oluşturulan herhangi bir gizli diziden Gizli Dizi yedekleme oluşturulabilir. Bu yedeklemeler ikili veri olarak gelir ve yalnızca daha önce silinmiş bir gizli diziyi yeniden oluşturmak için kullanılabilir.

Azure Active Directory ile kimlik doğrulaması

Key Vault hizmeti, API'lerine yönelik isteklerin kimliğini doğrulamak için Azure Active Directory'ye dayanır. @azure/identity paketi, uygulamanızın bunu yapmak için kullanabileceği çeşitli kimlik bilgisi türleri sağlar. @azure/identity için README, başlamanıza yönelik daha fazla ayrıntı ve örnek sağlar.

Azure Key Vault hizmetiyle etkileşim kurmak için SecretClient sınıfının bir örneğini, kasası url'sini ve kimlik bilgisi nesnesini oluşturmanız gerekir. Bu belgede gösterilen örneklerde, yerel geliştirme ve üretim ortamları dahil olmak üzere çoğu senaryo için uygun olan DefaultAzureCredentialadlı bir kimlik bilgisi nesnesi kullanılır. Ayrıca, üretim ortamlarında kimlik doğrulaması için yönetilen kimlik kullanmanızı öneririz.

Kimlik doğrulamasının farklı yolları ve bunların ilgili kimlik bilgileri türleri hakkında daha fazla bilgiyi Azure Kimliği belgelerinde bulabilirsiniz.

İşte hızlı bir örnek. İlk olarak, DefaultAzureCredential içeri aktarıp SecretClient. Bunlar içeri aktarıldıktan sonra Key Vault hizmetine bağlanabiliriz:

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 hizmet API'sinin sürümünü belirtme

Varsayılan olarak, bu paket 7.1en son Azure Key Vault hizmet sürümünü kullanır. Desteklenen diğer tek sürüm 7.0. İstemci oluşturucusunda serviceVersion seçeneğini aşağıda gösterildiği gibi ayarlayarak kullanılan hizmet sürümünü değiştirebilirsiniz:

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

Örnekler

Aşağıdaki bölümlerde Azure Key Vault Gizli Dizilerini kullanan bazı yaygın görevleri kapsayan kod parçacıkları sağlanır. Burada ele alınan senaryolar şunlardan oluşur:

gizli dizi oluşturma ve ayarlama .
Gizli dizi alma.
öznitelikleriyle gizli dizi oluşturma ve güncelleştirme.
Gizlisilme.
gizli dizi listelerini yineleme.

Gizli dizi oluşturma ve ayarlama

setSecret belirtilen gizli dizi adına sağlanan bir değer atar. Aynı ada sahip bir gizli dizi zaten varsa, gizli dizinin yeni bir sürümü oluşturulur.

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

Gizli dizi alma

Kasadan gizli dizileri okumanın en basit yolu, ada göre bir gizli dizi almaktır. Bu, gizli dizinin en son sürümünü alır. İsteğe bağlı parametrelerin bir parçası olarak belirtirseniz isteğe bağlı olarak anahtarın farklı bir sürümünü alabilirsiniz.

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

Özniteliklerle gizli dizi oluşturma ve güncelleştirme

Gizli dizi, adından ve değerinden daha fazla bilgiye sahip olabilir. Ayrıca aşağıdaki öznitelikleri de içerebilir:

tags: Gizli dizileri aramak ve filtrelemek için kullanılabilecek herhangi bir anahtar-değer kümesi.
contentType: Gizli dizi alıcısının gizli dizi değerinin nasıl kullanılacağını anlamasına yardımcı olmak için kullanılabilecek herhangi bir dize.
enabled: Gizli dizi değerinin okunup okunamayacağını belirleyen boole değeri.
notBefore: Gizli dizi değerinin alınabildiği belirli bir tarih.
expiresOn: Gizli dizi değerinin alınamadığı belirli bir tarih.

Bu özniteliklere sahip bir nesne, gizli dizinin adının ve değerinin hemen ardından setSecretüçüncü parametresi olarak aşağıdaki gibi gönderilebilir:

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

Bu, sağlanan en son özniteliklere sahip olacak aynı gizli dizinin yeni bir sürümünü oluşturur.

Öznitelikler, updateSecretPropertiesile var olan bir gizli dizi sürümüne de aşağıdaki gibi güncelleştirilebilir:

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

Gizli dizi silme

beginDeleteSecret yöntemi gizli dizi silme işlemini başlatır. Bu işlem, gerekli kaynaklar kullanılabilir duruma gelir gelmez arka planda gerçekleşir.

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

Key Vault için geçici silme etkinleştirilirse, bu işlem gizli diziyi yalnızca silinen gizli dizi olarak etiketler. Silinen gizli dizi güncelleştirilemez. Bunlar yalnızca okunabilir, kurtarılabilir veya temizlenebilir.

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

Gizli dizilerin tamamen silinmesi biraz zaman aldığından, beginDeleteSecret temel alınan Uzun Süre Çalışan İşlemi yönergelerimize göre izleyen bir Poller nesnesi döndürür: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Alınan poller, poller.getResult()çağrısı yaparak silinen gizli diziyi almanıza olanak sağlar. Ayrıca gizli dizi silinene kadar tek tek hizmet çağrılarını çalıştırarak veya işlem bitene kadar bekleyerek silme işleminin bitmesini de bekleyebilirsiniz:

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

Gizli dizi tamamen silinene kadar beklemenin bir diğer yolu da tek tek çağrıları aşağıdaki gibi yapmaktır:

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

Gizli dizi listelerini yineleme

SecretClient kullanarak, bir Key Vault'taki tüm gizli dizileri ve silinen tüm gizli dizileri ve belirli bir gizli dizinin sürümlerini alıp yineleyebilirsiniz. Aşağıdaki API yöntemleri kullanılabilir:

listPropertiesOfSecrets, silinmeyen tüm gizli dizilerinizi yalnızca en son sürümlerinde adlarına göre listeler.
listDeletedSecrets silinen tüm gizli dizilerinizi yalnızca en son sürümlerinde adlarına göre listeler.
listPropertiesOfSecretVersions gizli dizinin tüm sürümlerini gizli dizi adına göre listeler.

Aşağıdaki gibi kullanılabilir:

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

Bu yöntemlerin tümü tüm kullanılabilir sonuçları aynı anda döndürür. Bunları sayfalara göre almak için, kullanmak istediğiniz API yöntemini çağırdıktan hemen sonra aşağıdaki gibi .byPage() ekleyin:

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

Sorun giderme

Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için sorun giderme kılavuzumuza bakın.

Loglamayı etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, çalışma zamanında setLogLevel@azure/logger çağrılarak günlük tutma etkinleştirilebilir.

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

setLogLevel("info");

Sonraki Adımlar

Aşağıdaki bağlantılardan daha fazla kod örneği bulabilirsiniz:

Key Vault Gizli Dizi Örnekleri (JavaScript)
Key Vault Gizli Dizi Örnekleri (TypeScript)
Key Vault Gizli Dizileri Test Çalışmalarını

Katkıda Bulunmak

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-06-11