Azure Key Vault Secret client library for JavaScript - version 4.11.1

Azure Key Vault, güvenli anahtarlar kullanarak kimlik doğrulama anahtarlarını, depolama hesabı anahtarlarını, veri şifreleme anahtarlarını, .pfx dosyalarını ve şifreleri şifrelemenize olanak tanıyan bir hizmettir. Azure Key Vault hakkında daha fazla bilgi edinmek isterseniz, şu adresleri inceleyebilirsiniz: Azure Key Vault?

Azure Key Vault Secrets yönetimi, tokenlara, şifrelere, sertifikalara, API anahtarlarına ve diğer sırlara erişimi güvenli bir şekilde saklamanıza ve sıkı kontrol etmenize olanak tanır.

Node.js uygulamanızdaki Azure Key Vault Secrets için istemci kütüphanesini şu şekilde kullanın:

  • 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: Bu paket, Azure Key Vault hizmet sınırlamaları nedeniyle tarayıcıda kullanılamaz, lütfen rehberlik için this document sayfasına bakınız.

Önemli bağlantılar:

Başlangıç Yapmak

Şu anda desteklenen ortamlar

Önkoşullar

Paketi yükle

Azure Key Vault Secret client library npm kullanılarak kurulum:

npm install @azure/keyvault-secrets

Kimlik kitaplığını yükleme

Key Vault istemcileri, Azure Identity Library kullanılarak 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

  • Secret istemcisi Azure Key Vault API'deki sırlarla ilgili API yöntemleriyle etkileşime giren birincil arayüzdür. 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 versiyonu Key Vault'daki bir sırrın bir versiyonudur. 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 sadece Key Vault soft-delete olur.
  • 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.

Authenticating with Azure Active Directory

Key Vault hizmeti, API'lerine gelen istekleri 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. README @azure/identity için daha fazla detay ve deneme sunuyor.

Azure Key Vault servisiyle etkileşime girmek için SecretClient sınıfının bir örneğini, bir vault url ve bir credential nesnesi 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.

Farklı kimlik doğrulama yolları ve bunlara karşılık gelen kimlik bilgileri türleri hakkında daha fazla bilgiyi Azure Kimlik belgeleri adresinde bulabilirsiniz.

İşte hızlı bir örnek. İlk olarak, DefaultAzureCredential içeri aktarıp SecretClient. Bunlar içe 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 secrets client and connect to the service
const client = new SecretClient(url, credential);

Tarayıcı ortamlarında kimlik doğrulaması yapmak için InteractiveBrowserCredential paketindeki @azure/identity kullanın.

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

Azure Key Vault service API sürümünün belirtilmesi

Varsayılan olarak, bu paket 7.1 olan en son Azure Key Vault servis 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ümler, Azure Key Vault Secrets kullanılarak kullanılan bazı yaygın görevleri kapsayan kod parçalarını sunar. 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);

Eğer Key Vault için soft-delete etkinleştirilmişse, bu işlem sırrı yalnızca deleted sırrı 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 sırları ve silinmiş sırları ve belirli bir sırrın versiyonlarını alıp tekrar edebiliyorsunuz. 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 arıza senaryolarının nasıl teşhis edileceğine dair detaylar için sorun giderme rehberimize bakınız.

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:

Katkıda Bulunmak

Bu kütüphaneye katkıda bulunmak isterseniz, kodun nasıl oluşturulacağı ve test edileceği hakkında daha fazla bilgi edinmek için lütfen katkı rehberi adresini okuyun.

  • Last updated on