JavaScript için Azure Uygulaması Yapılandırması istemci kitaplığı - sürüm 1.10.0

Azure Uygulama Yapılandırma, geliştiricilerin uygulama ve özellik ayarlarını basit ve güvenli bir şekilde merkezileştirmesine yardımcı olan yönetilen bir hizmettir.

Önemli bağlantılar:

Doğru paketi seçin

Aşağıdakileri yapmak için @azure/app-configuration (bu kitaplık) kullanın:

Azure Uygulaması Yapılandırması'nda yapılandırma ayarlarını ve anlık görüntüleri yönetme
Normal yapılandırma tüketimi alanının dışında çalışan ayrıntılı okumalar gerçekleştirme

Çoğu uygulama, bu düşük düzeyli istemci kitaplığını temel alan ve çalışma zamanında yapılandırmayı kullanmanın önerilen yolu olan @azure/app-configuration-provider kitaplığıyla başlamalıdır. Şunu ekliyor:

Yapılandırmayı anahtar/değer eşlemesi veya yapılandırılmış JSON nesnesi olarak kullanan esnek erişim desenleri
Uygulama yapılandırmasını bildirimli olarak oluşturmak için sorgu mekanizması
Çalışma zamanı sırasında yapılandırma yenilemesi
Önbelleğe alma, replika bulma, yük devretme ve yük dengeleme ile yüksek güvenilirlik
Anahtar kasası başvuru çözümlemesi ve otomatik yenileme
@microsoft/özellik yönetimi kitaplığı için özellik bayrağı tümleştirmesi

Daha fazla bilgi için lütfen yapılandırma sağlayıcısına genel bakış bölümüne gidin.

Başlarken

Paketi yükleme

npm install @azure/app-configuration

Not:Yalnızca yapılandırma değerlerini okuması gereken uygulamalar için bunun yerine @azure/app-configuration-provider kitaplığını kullanmanızı öneririz.

Şu anda desteklenen ortamlar

Node.js LTS sürümleri
Safari, Chrome, Edge ve Firefox'un en son sürümleri.

Daha fazla bilgi için bkz. destek ilkesi.

Önkoşullar

Azure Aboneliği
Uygulama Yapılandırması kaynağı

Uygulama Yapılandırma kaynağı oluşturma

Azure Uygulama Yapılandırma kaynağı oluşturmak için azure portal veya Azure CLI kullanabilirsiniz.

Örnek (Azure CLI):

az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus

İstemcinin kimliğini doğrulama

AppConfigurationClient, hizmet sorumlusu veyabağlantı dizesi kullanarak kimlik doğrulaması yapabilir.

Hizmet sorumlusuyla kimlik doğrulaması

Hizmet sorumlusu aracılığıyla kimlik doğrulaması şu şekilde yapılır:

@azure/identity paketini kullanarak kimlik bilgisi oluşturma.
AppConfiguration kaynağınızda uygun RBAC kurallarını ayarlama. Uygulama Yapılandırması rolleri hakkında daha fazla bilgiyi buradabulabilirsiniz.

DefaultAzureCredential kullanma

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

@azure/identity hakkında daha fazla bilgi burada bulunabilir

Bağımsız Bulutlar

Bağımsız Buluttaki bir kaynakla kimlik doğrulaması yapmak için oluşturucu seçeneklerinde ayarlamanız audienceAppConfigurationClient gerekir.

import { AppConfigurationClient, KnownAppConfigAudience } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(endpoint, new DefaultAzureCredential(), {
  audience: KnownAppConfigAudience.AzureChina,
});

Not: Özellik tanımlanmadığında audience , SDK varsayılan olarak Azure Genel Bulut'a ayarlanır.

Bağlantı dizesiyle kimlik doğrulaması

Bir Uygulama Yapılandırması kaynağının Birincil bağlantı dizesi almak için şu Azure CLI komutunu kullanabilirsiniz:

az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"

Kodda artık Azure CLI'dan bağlantı dizesiyle Uygulama Yapılandırma istemcinizi oluşturabilirsiniz:

import { AppConfigurationClient } from "@azure/app-configuration";

const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);

Temel kavramlar

AppConfigurationClient portalda Uygulama Yapılandırması'ndan bazı terminoloji değişiklikleri vardır.

Anahtar/Değer çiftleri ConfigurationSetting nesneler olarak temsil edilir
Bir ayarın kilitlenmesi ve kilidinin açılması, isReadOnly alanında gösterilir ve setReadOnlykullanarak geçiş yapabilirsiniz.
Anlık görüntüler ConfigurationSnapshot nesneler olarak temsil edilir.

İstemci basit bir tasarım metodolojisini izler- ConfigurationSettingConfigurationSettingParam veya ConfigurationSettingIdalan herhangi bir yönteme geçirilebilir.

Bu, bu desenin çalıştığı anlamına gelir:

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const setting = await client.getConfigurationSetting({
  key: "hello",
});

setting.value = "new value!";
await client.setConfigurationSetting(setting);

// fields unrelated to just identifying the setting are simply
// ignored (for instance, the `value` field)
await client.setReadOnly(setting, true);

// delete just needs to identify the setting so other fields are
// just ignored
await client.deleteConfigurationSetting(setting);

veya örneğin, bir ayarı yeniden alma:

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

let setting = await client.getConfigurationSetting({
  key: "hello",
});

// re-get the setting
setting = await client.getConfigurationSetting(setting);

2022-11-01-preview API sürümü yapılandırma anlık görüntülerini destekler: sabit, bir yapılandırma deposunun belirli bir noktaya kopyaları. Anlık görüntüler, anlık görüntüde hangi anahtar-değer çiftlerinin bulunduğunu belirleyen filtrelerle oluşturulabilir ve yapılandırma deposunun sabit, birleştirilmiş görünümünü oluşturur. Bu özellik, güncelleştirmeler yapıldıktan sonra okuma nedeniyle tek tek ayarlarda sürüm uyuşmazlığı olmadığından emin olarak uygulamaların tutarlı bir yapılandırma görünümünü tutmasına olanak tanır. Örneğin, bu özellik bir Uygulama Yapılandırması içinde "yayın yapılandırma anlık görüntüleri" oluşturmak için kullanılabilir. Aşağıdaki örnekte oluşturma ve anlık görüntü alma bölümüne bakın.

Örnekler

Not: Uygulamanızın yalnızca yapılandırma değerlerini alması gerekiyorsa ve yapılandırma ayarlarında oluşturma, güncelleştirme veya silme işlemleri gerçekleştirmeyi gerektirmiyorsa, bunun yerine @azure/app-configuration-provider kitaplığını kullanmayı göz önünde bulundurun. Sağlayıcı kitaplığı, çalışma zamanında yapılandırma verilerini ve ek özellikleri yüklemek için basitleştirilmiş bir deneyim sunar. Microsoft Learn'deki Azure Uygulaması Yapılandırması belgelerinde çok sayıda kod örneği bulabilirsiniz.

Ayar oluşturma ve alma

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

await client.setConfigurationSetting({
  key: "testkey",
  value: "testvalue",
  // Labels allow you to create variants of a key tailored
  // for specific use-cases like supporting multiple environments.
  // https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
  label: "optional-label",
});

const retrievedSetting = await client.getConfigurationSetting({
  key: "testkey",
  label: "optional-label",
});

console.log("Retrieved value:", retrievedSetting.value);

Anlık görüntü oluşturma

beginCreateSnapshot size anlık görüntü oluşturma için yoklama yapmak için poller verir.

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

await client.addConfigurationSetting({
  key,
  value,
  label,
});

const poller = await client.beginCreateSnapshot({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});
const snapshot = await poller.pollUntilDone();

Oluşturma işleminin sonucunu yoklama tamamlandıktan hemen sonra elde etmek için beginCreateSnapshotAndWait de kullanabilirsiniz.

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

const snapshot = await client.beginCreateSnapshotAndWait({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});

Anlık görüntü alma

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshot = await client.getSnapshot("testsnapshot");
console.log("Retrieved snapshot:", retrievedSnapshot);

Anlık görüntüdeki `ConfigurationSetting` listeleme

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");

for await (const setting of retrievedSnapshotSettings) {
  console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}

Hizmetten gelen tüm anlık görüntüleri listeleme

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const snapshots = await client.listSnapshots();

for await (const snapshot of snapshots) {
  console.log(`Found snapshot: ${snapshot.name}`);
}

Anlık görüntüyü kurtarma ve arşivle

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

// Snapshot is in ready status
const archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);

// Snapshot is in archive status
const recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);

Sorun giderme

Günlük tutmak

Günlüğe kaydetmeyi 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 AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, setLogLevel@azure/logger çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için@azure/günlükçü paketi belgelerine bakabilirsiniz.

React Native desteği

React Native, bu SDK kitaplığı tarafından kullanılan bazı JavaScript API'lerini desteklemediğinden, bunlar için polifill sağlamanız gerekir. Daha fazla bilgi için lütfen Expo ile React Native örneğimize bakın.

Sonraki adımlar

Aşağıdaki örnekler, Uygulama Yapılandırması ile etkileşim kurmanın çeşitli yollarını gösterir:

helloworld.ts - Yapılandırma değerlerini alma, ayarlama ve silme.
helloworldWithLabels.ts - Beta ve üretim gibi senaryolarda ayarlarınıza ek boyutlar eklemek için etiketleri kullanın.
optimisticConcurrencyViaEtag.ts - Yanlışlıkla üzerine yazmayı önlemek için etag'leri kullanarak değerleri ayarlayın.
setReadOnlySample.ts - Değişikliği önlemek için ayarları salt okunur olarak işaretleme.
getSettingOnlyIfChanged.ts - Ayarı yalnızca son aldığınızdan sonra değiştirildiğinde alırsınız.
listRevisions.ts - Bir anahtarın düzeltmelerini listeleyerek önceki değerleri ve bunların ne zaman ayarlandığını görmenizi sağlar.
secretReference.ts - SecretReference, KeyVault gizli dizisi olarak başvuran bir yapılandırma ayarını temsil eder.
snapshot.ts - Yapılandırma ayarlarını oluşturun, listeleyin ve anlık görüntüleri arşivleyin.
featureFlag.ts - Özellik bayrakları, değer için belirli JSON şemasını izleyen ayarlardır.

GitHub'daki örnekleri klasöründe daha ayrıntılı örnekler bulunabilir.

Katkıda

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.

Bu modülün testleri, bir Azure Uygulama Yapılandırması örneğine sahip olmanız gereken canlı ve birim testlerinin bir karışımıdır. Testleri yürütmek için çalıştırmanız gerekir:

pnpm install
pnpm build --filter @azure/app-configuration...
sdk\appconfiguration\app-configuration klasöründe şu içeriklere sahip bir .env dosyası oluşturun: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Daha fazla ayrıntı için testleri klasörümüzü görüntüleyin.

JavaScript için Microsoft Azure SDK
Azure Uygulaması Yapılandırması

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-13