JavaScript yapılandırma sağlayıcısı

Azure Uygulama Yapılandırması, geliştiricilerin uygulama yapılandırmalarını basit ve güvenli bir biçimde merkezileştirmesine yardımcı olan, yönetilen bir hizmettir. JavaScript yapılandırma sağlayıcısı kitaplığı, Azure Uygulaması Yapılandırma deposundan yapılandırmanın yönetilen bir şekilde yüklenmesini sağlar. Bu istemci kitaplığı, JavaScript için Azure SDK'nın üzerine ek işlevler ekler.

Yapılandırmayı Yükle

load paketinde @azure/app-configuration-provider dışarı aktarılan yöntem, Azure Uygulama Yapılandırması'ndan yapılandırmayı yüklemek için kullanılır. Yöntem, load Uygulama Yapılandırması deposuna bağlanmak için Microsoft Entra ID veya bağlantı dizesi kullanmanıza olanak tanır.

Microsoft Entra ID

DefaultAzureCredential öğesini, Uygulama Yapılandırması deponuzda kimlik doğrulaması yapmak için kullanırsınız. Kimlik bilgilerinizi Uygulama Yapılandırması Veri Okuyucusu rolü atamak için yönergeleri izleyin.

const { load } = require("@azure/app-configuration-provider");
const { DefaultAzureCredential } = require("@azure/identity");
const endpoint = process.env.AZURE_APPCONFIG_ENDPOINT;
const credential = new DefaultAzureCredential(); // For more information, see https://learn.microsoft.com/azure/developer/javascript/sdk/credential-chains#use-defaultazurecredential-for-flexibility

async function run() {
    // Connect to Azure App Configuration using a token credential and load all key-values with no label.
    const appConfig = await load(endpoint, credential);
    console.log('appConfig.get("message"):', appConfig.get("message"));
}

run();

Bağlantı dizesi

const { load } = require("@azure/app-configuration-provider");
const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;

async function run() {
    // Connect to Azure App Configuration using a connection string and load all key-values with no label.
    const appConfig = await load(connectionString);
    console.log('appConfig.get("message"):', appConfig.get("message"));
}

run();

load yöntemi, aşağıdaki gibi tanımlanan bir tür örneği AzureAppConfiguration döndürür:

type AzureAppConfiguration = {
    refresh(): Promise<void>;
    onRefresh(listener: () => any, thisArg?: any): Disposable;
} & IGettable & ReadonlyMap<string, any> & IConfigurationObject;

refresh ve onRefresh yöntemleri hakkında daha fazla bilgi için Yapılandırma Yenileme bölümüne bakın.

Yapılandırmayı tüketme

türü AzureAppConfiguration aşağıdaki arabirimleri genişletir:

• IGettable

  interface IGettable {
      get<T>(key: string): T | undefined;
  }
  

  Arayüz, Map tarzı veri yapısından bir anahtar-değer çiftinin değerini almak için bir yöntem sağlar.

  const appConfig = await load(endpoint, credential);
  const fontSize = appConfig.get("app:font:size"); // value of the key "app:font:size" from the App Configuration store
  

• ReadonlyMap

  Ayrıca AzureAppConfiguration türü, ReadonlyMap arabirimini genişletir ve anahtar-değer çiftlerine salt okunur erişim sağlar.

• IConfigurationObject

  interface IConfigurationObject {
      constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
  }
  

  Bu arabirim, harita stili veri yapısına ve hiyerarşik anahtarlara dayalı bir yapılandırma nesnesi oluşturmak için bir yöntem IConfigurationObject sağlar constructConfigurationObject. İsteğe bağlı ConfigurationObjectConstructionOptions parametre, hiyerarşik anahtarları nesne özelliklerine dönüştürmek için ayırıcıyı belirtmek için kullanılabilir. Varsayılan olarak ayırıcı "."'dir.

  interface ConfigurationObjectConstructionOptions {
      separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
  }
  

  JavaScript'te, nesneler veya haritalar genellikle yapılandırmaları temsil eden birincil veri yapıları olarak kullanılır. JavaScript yapılandırma sağlayıcısı kitaplığı her iki yapılandırma yaklaşımını da destekler ve geliştiricilere ihtiyaçlarına en uygun seçeneği belirleme esnekliği sağlar.

  const appConfig = await load(endpoint, credential);
  const settingsObj = appConfig.constructConfigurationObject({separator: ":"});
  const fontSize1 = appConfig.get("app:font:size"); // map-style configuration representation
  const fontSize2 = settingsObj.app.font.size; // object-style configuration representation
  

JSON içerik türü işleme

Uygulama Yapılandırması'nda JSON anahtar değerleri oluşturabilirsiniz . Azure Uygulama Yapılandırması'ndan anahtar-değerleri yüklerken, yapılandırma sağlayıcısı geçerli JSON içerik türünün (uygulama/json gibi) anahtar değerlerini otomatik olarak nesneye dönüştürür.

{
    "key": "font",
    "label": null,
    "value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
    "content_type": "application/json"
}

Yukarıdaki anahtar-değer olarak { size: 12, color: "red" }yüklenir.

const appConfig = await load(endpoint, credential);
const { size, color } = appConfig.get("font");

Not

2.2.0 sürümünden @azure/app-configuration-providerbaşlayarak, yapılandırma sağlayıcısı içerik türüne sahip anahtar değerlerinde (application/json) tanımlandığı gibi açıklamalara izin verir.

Seçicileri kullanarak belirli anahtar değerlerini yükleme

Varsayılan olarak, load yöntemi yapılandırma deposundan etiket içermeyen tüm yapılandırmaları yükler. yöntemin load davranışını, AzureAppConfigurationOptions türündeki isteğe bağlı parametre aracılığıyla yapılandırabilirsiniz.

Uygulama Yapılandırması deposundan yüklenen yapılandırmaları daraltmak veya genişletmek için, özelliğinin altında AzureAppConfigurationOptions.selectors anahtar veya etiket seçicilerini belirtebilirsiniz.

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys starting with "app1." prefix and "test" label
            keyFilter: "app1.*",
            labelFilter: "test"
        },
        { // load the subset of keys with "dev" label"
            keyFilter: "*",
            labelFilter: "dev"
        }
    ]
});

Not

Anahtar-değerler, seçicilerin listelendiği sırayla yüklenir. Birden çok seçici aynı anahtara sahip anahtar-değerleri alırsa, sonuncudaki değer daha önce yüklenmiş olan tüm değerleri geçersiz kılar.

Etiket filtreleri

Etiket filtreleri parametresi, belirli etiketlere sahip anahtar-değerleri seçer. Anahtar-değer yalnızca filtrelerde belirtilen tüm etiketlere ve karşılık gelen değerlere sahipse yüklenir.

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys with "test" label" and three tags
            keyFilter: "*",
            labelFilter: "test",
            tagFilters: [
                "emptyTag=",
                "nullTag=\0",
                "tag1=value1"
            ]
        }
    ]
});

Not

Yıldız işareti (*), virgül (,) ve ters eğik çizgi (\) karakterleri ayrılmıştır ve etiket filtresinde kullanıldığında ters eğik çizgiyle kaçış karakteriyle kullanılmalıdır.

Anahtarlardan önekleri kırpın

Anahtarların ön ekini AzureAppConfigurationOptions.trimKeyPrefixes özelliğine kırpılmış anahtar ön eklerinin bir listesini sağlayarak kırpabilirsiniz.

const appConfig = await load(endpoint, credential, {
    selectors: [{
        keyFilter: "app.*"
    }],
    trimKeyPrefixes: ["app."]
});

Yapılandırma yenilemesi

Yapılandırmalar için dinamik yenileme, uygulamayı yeniden başlatmak zorunda kalmadan en son değerlerini Uygulama Yapılandırması deposundan çekmenizi sağlar. Yenilemeyi etkinleştirmek ve yenileme seçeneklerini yapılandırmak için ayarlayabilirsiniz AzureAppConfigurationOptions.refreshOptions . Sunucuda seçili anahtar değerlerinde herhangi bir değişiklik algılandığında yüklenen yapılandırma güncelleştirilir. Varsayılan olarak, 30 saniyelik bir yenileme aralığı kullanılır, ancak özelliğiyle refreshIntervalInMs geçersiz kılabilirsiniz.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        refreshIntervalInMs: 15_000
    }
});

Yalnızca refreshOptions ayarlamak, yapılandırmayı otomatik olarak güncellemez. load yöntemi tarafından döndürülen AzureAppConfiguration örneğinde refresh yöntemini çağırarak bir yenileme tetiklemeniz gerekir.

// this call is not blocking, the configuration will be updated asynchronously
appConfig.refresh();

Bu tasarım, uygulamanız boşta olduğunda Uygulama Yapılandırması'na gereksiz istekleri önler. Çağrıyı refresh uygulama etkinliğinizin gerçekleştiği yere eklemeniz gerekir. Bu, etkinlik temelli yapılandırma yenilemesi olarak bilinir. Örneğin, gelen bir isteği işlerken veya karmaşık bir görev gerçekleştirdiğiniz bir yinelemenin içinde çağırabilirsiniz refresh .

const server = express();
// Use an express middleware to refresh configuration whenever a request comes in
server.use((req, res, next) => {
    appConfig.refresh();
    next();
})

Yenileme çağrısı herhangi bir nedenle başarısız olsa bile, uygulamanız önbelleğe alınmış yapılandırmayı kullanmaya devam eder. Yapılandırılan yenileme aralığı geçtiğinde ve uygulama etkinliğiniz tarafından yenileme çağrısı tetiklendiğinde başka bir deneme yapılır. Çağrı refresh, yapılandırılan yenileme aralığı geçmeden önce yapıldığında etkisiz bir çağrıdır, bu nedenle sık sık yapılsa bile performans etkisi minimaldir.

Özel yenileme geri araması

onRefresh yöntemi, yerel yapılandırma Azure App Configuration deposundaki değişikliklerle başarıyla güncelleştirildiğinde çağırılacak özel geri çağrım fonksiyonlarına olanak tanır. Atılabilir bir nesne döndürür, bu nesneyi kayıtlı geri çağırmayı kaldırmak için kullanabilirsiniz.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true
    }
});
const disposer = appConfig.onRefresh(() => {
    console.log("Config refreshed.");
});

appConfig.refresh();
// Once the refresh is successful, the callback function you registered will be executed.
// In this example, the message "Config refreshed" will be printed.

disposer.dispose();

Sentinel anahtarını yenile

Sentinel anahtarı, diğer tüm anahtarların değiştirilmesini tamamladıktan sonra güncelleştirdiğiniz bir anahtardır. Yapılandırma sağlayıcısı, seçilen tüm anahtar-değerler yerine sentinel anahtarını izler. Bir değişiklik algılandığında uygulamanız tüm yapılandırma değerlerini yeniler.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        watchedSettings: [
            { key: "sentinel" }
        ]
    }
});

Yenileme yapılandırması hakkında daha fazla bilgi için Bkz . JavaScript'te dinamik yapılandırmayı kullanma.

Özellik bayrağı

Azure Uygulaması Yapılandırması'nda özellik bayrakları oluşturabilirsiniz. Varsayılan olarak, özellik bayrakları yapılandırma sağlayıcısı tarafından yüklenmez. yöntemini çağırırken AzureAppConfigurationOptions.featureFlagOptions özellik üzerinden load özellik bayraklarının yüklenmesini ve yenilenmesini etkinleştirebilirsiniz.

const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
        refresh: {
            enabled: true, // enable refreshing feature flags
            refreshIntervalInMs: 60_000
        }
    }
});

Not

Etkinleştirilirse ve seçici belirtilmezsefeatureFlagOptions, yapılandırma sağlayıcısı Uygulama Yapılandırması deposundan etiket içermeyen tüm özellik bayraklarını yükler.

Önemli

Azure Uygulama Yapılandırması'ndan yüklenen özellik bayraklarını etkili bir şekilde tüketmek ve yönetmek için @microsoft/feature-management paketini yükleyin ve kullanın. Bu kitaplık, uygulamanızdaki özellik davranışını denetlemek için yapılandırılmış bir yol sağlar.

Özellik yönetimi

Özellik yönetimi kitaplığı, özellik bayraklarına göre uygulama işlevselliği geliştirmenin ve kullanıma sunmanın bir yolunu sağlar. Özellik yönetimi kitaplığı, yapılandırma sağlayıcısı kitaplığıyla birlikte çalışacak şekilde tasarlanmıştır. Yapılandırma sağlayıcısı, feature_management bölümünün feature_flags listesi altındaki yapılandırmaya tüm seçilen özellik bayraklarını yükler. Özellik yönetimi kitaplığı, uygulamanız için yüklenen özellik bayraklarını tüketir ve yönetir.

Aşağıdaki örnek, @microsoft/feature-management kütüphanesinin yapılandırma sağlayıcısıyla tümleştirerek, Express uygulamasında API erişilebilirliğini, özellik bayrağının Beta durumuna bağlı olarak dinamik olarak kontrol etmeyi göstermektedir.

// Load feature flags from Azure App Configuration
import { load } from "@azure/app-configuration-provider";
const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        refresh: {
            enabled: true // enable refreshing feature flags
        }
    }
});

import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
// Create a feature flag provider which uses the configuration provider as feature flag source
const ffProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
// Create a feature manager which will evaluate the feature flag
const featureManager = new FeatureManager(ffProvider);

import express from "express";
const server = express();

// Use a middleware to achieve request-driven configuration refresh
server.use((req, res, next) => {
    // this call is not blocking, the configuration will be updated asynchronously
    appConfig.refresh();
    next();
});

server.get("/Beta", async (req, res) => {
    if (await featureManager.isEnabled("Beta")) {
        res.send("Welcome to the Beta page!");
    } else {
        res.status(404).send("Page not found");
    }
});

JavaScript özellik yönetimi kitaplığını kullanma hakkında daha fazla bilgi için özellik bayrağı hızlı başlangıç kılavuzuna gidin.

Key Vault referansı

Azure Uygulama Yapılandırması, Azure Key Vault'ta depolanan gizli bilgilere başvurmayı destekler. Uygulama Yapılandırması'da Key Vault'ta depolanan gizli dizilere eşleyen anahtarlar oluşturabilirsiniz. Gizli bilgiler Key Vault'ta güvenli bir şekilde saklanır, ancak yüklendikten sonra diğer yapılandırma ayarları gibi erişilebilir.

Yapılandırma sağlayıcısı kütüphanesi, Uygulama Yapılandırmasında depolanan diğer anahtarlar gibi Key Vault başvurularını da alır. İstemci anahtarları Key Vault başvuruları olarak tanıdığından, benzersiz bir içerik türüne sahiptir ve istemci, uygulamanızın değerlerini almak için Key Vault'a bağlanır. Yapılandırma sağlayıcısının Azure Key Vault'a bağlanmasına izin vermek için özelliği uygun kimlik bilgileriyle yapılandırmanız AzureAppConfigurationOptions.KeyVaultOptions gerekir.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential
    }
});

SecretClient örneğini doğrudan KeyVaultOptions adresine de sağlayabilirsiniz. Bu şekilde, oluştururken SecretClientseçenekleri özelleştirebilirsiniz.

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

const credential = new DefaultAzureCredential();
const secretClient = new SecretClient(keyVaultUrl, credential, {
    serviceVersion: "7.0",
});
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretClients: [ secretClient ]
    }
});

Ayrıca, kendisiyle ilişkilendirilmiş bir Key Vault'a sahip olmayan gizli bilgileri yerel olarak çözümlemek için secretResolver özelliğini ayarlayabilirsiniz.

const resolveSecret = (url) => "From Secret Resolver";
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretResolver: resolveSecret
    }
});

Ayrıca, kayıtlı clientOptions olmayan Azure Key Vault'a bağlanmak için kullanılan SecretClientOptions özelliğini yapılandıracak şekilde SecretClient'i ayarlayabilirsiniz.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        clientOptions: { // configure a custom SecretClientOptions
            retryOptions: { 
                maxRetries: 3, 
                maxRetryDelayInMs: 1000 
            }
        }
    }
});

Paralel gizli çözüm

Azure Key Vault, tek bir istekte birden fazla gizli bilgiyi almak için toplu API sağlamaz. Uygulamanızın çok sayıda Key Vault referansını yüklemesi gerektiğinde, paralel sır çözümlemeyi etkinleştirmek için parallelSecretResolutionEnabled özelliğini KeyVaultOptions içinde açarak performansı iyileştirebilirsiniz. Bu, sağlayıcının sıralı şekilde değil, birden çok gizliyi paralel olarak getirmesine olanak tanır.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        parallelSecretResolutionEnabled: true
    }
});

Not

Gizli bilgileri paralel olarak çözerken, Azure Key Vault'un hizmet sınırı ile karşılaşabilirsiniz. Throttling'i etkili bir şekilde yönetmek için, için uygun yeniden deneme seçeneklerini yapılandırarak SecretClient implemente edin. Özel SecretClient örnekleri kaydedebilir veya clientOptions aracılığıyla AzureAppConfigurationOptions.keyVaultOptions yapılandırabilirsiniz.

Key Vault sırrı yenileme

Azure Uygulama Yapılandırması, gizli dizi yenileme aralıklarını yapılandırma yenileme döngünüzden bağımsız olarak yapılandırmanıza olanak tanır. Bu güvenlik açısından çok önemlidir çünkü Uygulama Yapılandırması'ndaki Key Vault başvuru URI'si değişmeden kalırken, Key Vault'taki temel gizli dizi güvenlik uygulamalarınızın bir parçası olarak döndürülebilir.

Not

Gizli yenileme, en az bir dakika süresi kullanır. Bu, gizli anahtarların aşırı yeniden yüklenmesini ve bunun sonucunda Key Vault üzerinde sınırlamaya yol açabilmesini önler.

Uygulamanızın her zaman en güncel gizli değerleri kullandığından emin olmak için secretRefreshIntervalInMs özelliğini KeyVaultOptions içinde yapılandırın. Bu, aşağıdaki durumlarda sağlayıcıyı Key Vault'tan yeni gizli anahtar değerlerini almaya zorlar:

• Uygulamanız AzureAppConfiguration.refresh çağrısı yapıyor
• Gizli için yapılandırılan yenileme aralığının süresi doldu

Bu mekanizma, Uygulama Yapılandırma deponuzda hiçbir değişiklik algılanmadığında bile çalışır ve uygulamanızın döndürülen gizli dizilerle eşitlenmiş durumda kalmasını sağlar.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        secretRefreshIntervalInMs: 7200_000 // 2 hours
    }
});

Anlık Görüntü

Anlık görüntü , Bir Uygulama Yapılandırma deposunun anahtar-değerlerinin adlandırılmış, sabit bir alt kümesidir. Anlık görüntüyü oluşturan anahtar-değerler, anahtar ve etiket filtreleri kullanımı aracılığıyla oluşturma sırasında seçilir. Anlık görüntü oluşturulduktan sonra içindeki anahtar-değerlerin değişmeden kalacağı garanti edilir.

Anlık görüntüden anahtar-değerleri veya özellik bayraklarını yüklemek için anlık görüntü seçiciyi kullanabilirsiniz:

const appConfig = await load(endpoint, credential, {
    selectors: [
        { snapshotName: "MySnapshot" }, // load key-values from snapshot
        { keyFilter: "test*", labelFilter: "test" }
    ],
    featureFlagOptions: {
        enabled: true,
        selectors: [
            { snapshotName: "MySnapshot" }, // load feature flags from snapshot
            { keyFilter: "*", labelFilter: "test" }
        ]
    }
});

Anlık görüntü referansı

Anlık görüntü referansı, aynı Uygulama Yapılandırma deposundaki bir anlık görüntüye başvuran bir yapılandırma ayarıdır. Yüklendiğinde sağlayıcı bu sorunu çözer ve bu anlık görüntüdeki tüm anahtar değerlerini ekler. Anlık görüntü başvurularının kullanılması, yeni bir anlık görüntüye geçmek için kod değişiklikleri ve/veya yeniden başlatmalar gerektiren bir anlık görüntü seçici eklemenin aksine çalışma zamanında anlık görüntüler arasında geçiş yapılmasını sağlar.

Anlık görüntü başvurusu oluşturma hakkında daha fazla bilgi için anlık görüntü başvurusu kavramına gidin.

Not

Anlık görüntü başvurularını kullanmak için 2.3.0 veya sonraki bir @azure/app-configuration-providersürümünü kullanın.

Başlatma tekrar denemesi

Yapılandırma yüklemesi, uygulama başlatma sırasında kritik bir yol işlemidir. Güvenilirliği sağlamak için Azure Uygulama Yapılandırması sağlayıcısı, ilk yapılandırma yükü sırasında sağlam bir yeniden deneme mekanizması uygular. Bu, uygulamanızın başlatma işleminin başarılı olmasını engelleyebilecek geçici ağ sorunlarından korunmasına yardımcı olur.

Bu davranışı şu AzureAppConfigurationOptions.startupOptionsşekilde özelleştirebilirsiniz:

const appConfig = await load(endpoint, credential, { 
    startupOptions: { 
        timeoutInMs: 300_000
    }
});

Coğrafi çoğaltma

Coğrafi çoğaltma kullanımı hakkında bilgi için Coğrafi çoğaltmayı etkinleştirme bölümüne gidin.

Azure Front Door'a bağlanma

Azure Front Door tümleştirmesi, istemci uygulamalarının yapılandırmayı doğrudan Uygulama Yapılandırması yerine uç önbelleğe alınmış uç noktalardan getirmesine olanak tanır. Bu mimari, genel CDN dağıtımının performans avantajlarıyla güvenli, ölçeklenebilir yapılandırma erişimi sunar.

Aşağıdaki örnekte, Azure Front Door'dan yapılandırma ayarlarının nasıl yüklenecekleri gösterilmektedir:

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

const appConfig = await loadFromAzureFrontDoor("{YOUR-AFD-ENDPOINT}", {
    selectors: [{
        keyFilter: "app.*"
    }],
    refreshOptions: {
        enabled: true,
        refreshIntervalInMs: 60_000
    }
});

const message = appConfig.get("app.message");

Azure Front Door hakkında daha fazla bilgi için bkz. İstemci Uygulamalarında Azure Front Door'dan Yükleme Yapılandırması.

Sonraki adımlar

JavaScript yapılandırma sağlayıcısını kullanmayı öğrenmek için aşağıdaki öğreticiye geçin.

JavaScript'te dinamik yapılandırmayı kullanma

JavaScript özellik yönetimi kitaplığını kullanmayı öğrenmek için aşağıdaki belgelere geçin.

JavaScript Özellik Yönetimi