Penyedia konfigurasi JavaScript

Azure App Configuration adalah layanan terkelola yang membantu pengembang mempusatkan konfigurasi aplikasi mereka dengan sederhana dan aman. Pustaka penyedia konfigurasi JavaScript memungkinkan konfigurasi pemuatan dari penyimpanan Azure App Configuration dengan cara terkelola. Pustaka klien ini menambahkan fungsionalitas tambahan di atas Azure SDK untuk JavaScript.

Memuat konfigurasi

Metode load yang @azure/app-configuration-provider diekspor dalam paket digunakan untuk memuat konfigurasi dari Azure App Configuration. Metode ini load memungkinkan Anda menggunakan ID Microsoft Entra atau string koneksi untuk menyambungkan ke penyimpanan App Configuration.

Microsoft Entra ID
String koneksi

Anda menggunakan DefaultAzureCredential untuk mengautentikasi ke penyimpanan App Configuration Anda. Ikuti instruksi untuk menetapkan kredensial Anda peran Pembaca Data App Configuration.

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

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

Metode mengembalikan load instans jenis AzureAppConfiguration yang didefinisikan sebagai berikut:

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

Untuk informasi selengkapnya tentang refresh metode dan onRefresh , lihat bagian Refresh konfigurasi.

Mengonsumsi konfigurasi

Jenis memperluas AzureAppConfiguration antarmuka berikut:

IGettable

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

Antarmuka IGettable menyediakan get metode untuk mengambil nilai nilai kunci dari struktur data bergaya peta.

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

Jenis ini AzureAppConfiguration juga memperluas ReadonlyMap antarmuka, menyediakan akses baca-saja ke pasangan kunci-nilai.
IConfigurationObject
```
interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}
```
Antarmuka IConfigurationObject menyediakan constructConfigurationObject metode untuk membangun objek konfigurasi berdasarkan struktur data bergaya Peta dan kunci hierarkis. Parameter opsional ConfigurationObjectConstructionOptions dapat digunakan untuk menentukan pemisah untuk mengonversi kunci hierarkis ke properti objek. Secara default, pemisahnya adalah ".".
```
interface ConfigurationObjectConstructionOptions {
    separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
}
```
Di JavaScript, objek atau peta umumnya digunakan sebagai struktur data utama untuk mewakili konfigurasi. Pustaka penyedia konfigurasi JavaScript mendukung kedua pendekatan konfigurasi, memberikan fleksibilitas kepada pengembang untuk memilih opsi yang paling sesuai dengan kebutuhan mereka.
```
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
```

Penanganan tipe konten JSON

Anda dapat membuat nilai kunci JSON di App Configuration. Saat memuat nilai kunci dari Azure App Configuration, penyedia konfigurasi akan secara otomatis mengonversi nilai kunci jenis konten JSON yang valid (misalnya aplikasi/json) menjadi objek.

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

Nilai kunci di atas akan dimuat sebagai { size: 12, color: "red" }.

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

Catatan

Dimulai dengan versi 2.2.0 dari @azure/app-configuration-provider, penyedia konfigurasi memungkinkan komentar, seperti yang didefinisikan dalam (JSONC), pada nilai kunci dengan jenis konten application/json.

Memuat nilai kunci tertentu menggunakan pemilih

Secara default, metode ini load akan memuat semua konfigurasi tanpa label dari penyimpanan konfigurasi. Anda dapat mengonfigurasi perilaku load metode melalui parameter opsional jenis AzureAppConfigurationOptions .

Untuk menyempurnakan atau memperluas konfigurasi yang dimuat dari penyimpanan App Configuration, Anda dapat menentukan pemilih kunci atau label di AzureAppConfigurationOptions.selectors bawah properti .

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

Catatan

Nilai kunci dimuat dalam urutan pemilih dicantumkan. Jika beberapa pemilih mengambil nilai kunci dengan kunci yang sama, nilai dari yang terakhir akan mengambil alih nilai yang dimuat sebelumnya.

Filter tag

Parameter filter tag memilih nilai kunci dengan tag tertentu. Nilai kunci hanya dimuat jika memiliki semua tag dan nilai terkait yang ditentukan dalam filter.

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

Catatan

Karakter tanda bintang (*), koma (,), dan garis miring terbalik (\) direservasi dan harus di-escape dengan garis miring terbalik saat digunakan dalam filter tag.

Memangkas awalan dari kunci

Anda dapat memangkas prefiks dari kunci dengan memberikan daftar awalan kunci yang dipangkas ke AzureAppConfigurationOptions.trimKeyPrefixes properti .

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

Refresh konfigurasi

Refresh dinamis untuk konfigurasi memungkinkan Anda menarik nilai terbarunya dari penyimpanan App Configuration tanpa harus menghidupkan ulang aplikasi. Anda dapat mengatur AzureAppConfigurationOptions.refreshOptions untuk mengaktifkan opsi refresh dan mengonfigurasi refresh. Konfigurasi yang dimuat akan diperbarui ketika setiap perubahan nilai kunci yang dipilih terdeteksi di server. Secara default, interval refresh 30 detik digunakan, tetapi Anda dapat menggantinya dengan refreshIntervalInMs properti .

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

refreshOptions Menyiapkan saja tidak akan secara otomatis menyegarkan konfigurasi. Anda perlu memanggil refresh metode pada AzureAppConfiguration instans yang load dikembalikan oleh metode untuk memicu refresh.

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

Desain ini mencegah permintaan yang tidak perlu ke App Configuration saat aplikasi Anda diam. Anda harus menyertakan refresh panggilan tempat aktivitas aplikasi Anda terjadi. Ini dikenal sebagai refresh konfigurasi berbasis aktivitas. Misalnya, Anda dapat memanggil refresh saat memproses permintaan masuk atau di dalam iterasi tempat Anda melakukan tugas yang kompleks.

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

Bahkan jika panggilan refresh gagal karena alasan apa pun, aplikasi Anda akan terus menggunakan konfigurasi cache. Upaya lain akan dilakukan ketika interval refresh yang dikonfigurasi telah berlalu dan panggilan refresh dipicu oleh aktivitas aplikasi Anda. refresh Panggilan adalah no-op sebelum interval refresh yang dikonfigurasi berlalu, sehingga dampak performanya minimal bahkan jika sering dipanggil.

Panggilan balik refresh kustom

Metode ini onRefresh memungkinkan Anda memanggil kembali fungsi kustom yang akan dipanggil setiap kali konfigurasi lokal berhasil diperbarui dengan perubahan dari penyimpanan Azure App Configuration. Ini mengembalikan objek Sekali Pakai, yang dapat Anda gunakan untuk menghapus panggilan balik terdaftar

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

Refresh pada kunci sentinel

Kunci sentinel adalah kunci yang Anda perbarui setelah menyelesaikan perubahan semua kunci lainnya. Penyedia konfigurasi akan memantau kunci sentinel alih-alih semua nilai kunci yang dipilih. Saat perubahan terdeteksi, aplikasi Anda me-refresh semua nilai konfigurasi.

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

Untuk informasi selengkapnya tentang konfigurasi refresh, buka Menggunakan konfigurasi dinamis di JavaScript.

Bendera fitur

Anda dapat membuat bendera fitur di Azure App Configuration. Secara default, bendera fitur tidak akan dimuat oleh penyedia konfigurasi. Anda dapat mengaktifkan bendera fitur pemuatan dan refresh melalui AzureAppConfigurationOptions.featureFlagOptions properti saat memanggil load metode .

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

Catatan

Jika featureFlagOptions diaktifkan dan tidak ada pemilih yang ditentukan, penyedia konfigurasi akan memuat semua bendera fitur tanpa label dari penyimpanan App Configuration.

Penting

Untuk mengonsumsi dan mengelola flag fitur yang dimuat secara efektif dari Azure App Configuration, instal dan gunakan paket @microsoft/feature-management. Pustaka ini menyediakan cara terstruktur untuk mengontrol perilaku fitur di aplikasi Anda.

Manajemen fitur

Pustaka manajemen fitur menyediakan cara untuk mengembangkan dan mengekspos fungsionalitas aplikasi berdasarkan bendera fitur. Pustaka manajemen fitur dirancang untuk bekerja bersama dengan pustaka penyedia konfigurasi. Penyedia konfigurasi akan memuat semua bendera fitur yang dipilih ke dalam konfigurasi di feature_flags bawah daftar bagian feature_management . Pustaka manajemen fitur akan menggunakan dan mengelola bendera fitur yang dimuat untuk aplikasi Anda.

Contoh berikut menunjukkan cara mengintegrasikan pustaka @microsoft/feature-management dengan penyedia konfigurasi untuk mengontrol aksesibilitas API secara dinamis dalam aplikasi Express berdasarkan status flag fitur Beta.

// 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 fm = 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");
    }
});

Untuk informasi selengkapnya tentang cara menggunakan pustaka manajemen fitur JavaScript, buka mulai cepat bendera fitur.

Referensi Key Vault

Azure App Configuration mendukung referensi rahasia yang disimpan di Azure Key Vault. Di App Configuration, Anda dapat membuat kunci yang memetakan ke rahasia yang disimpan di Key Vault. Rahasia disimpan dengan aman di Key Vault, tetapi dapat diakses seperti konfigurasi lain setelah dimuat.

Pustaka penyedia konfigurasi mengambil referensi Key Vault, seperti halnya untuk kunci lain yang disimpan dalam App Configuration. Karena klien mengenali kunci sebagai referensi Key Vault, mereka memiliki jenis konten yang unik, dan klien akan terhubung ke Key Vault untuk mengambil nilainya untuk aplikasi Anda. Anda perlu mengonfigurasi AzureAppConfigurationOptions.KeyVaultOptions properti dengan kredensial yang tepat untuk memungkinkan penyedia konfigurasi tersambung ke Azure Key Vault.

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

Anda juga dapat menyediakan SecretClient instans langsung ke KeyVaultOptions. Dengan cara ini, Anda dapat menyesuaikan opsi saat membuat SecretClient.

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

Anda juga dapat mengatur secretResolver properti untuk menyelesaikan rahasia secara lokal yang tidak memiliki Key Vault yang terkait dengannya.

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

Anda juga dapat mengatur properti clientOptions untuk mengonfigurasi SecretClientOptions yang digunakan untuk menyambungkan ke Azure Key Vault yang tidak memiliki SecretClient terdaftar.

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

Resolusi rahasia paralel

Azure Key Vault tidak menyediakan API batch untuk mengambil beberapa rahasia dalam satu permintaan. Ketika aplikasi Anda perlu memuat banyak referensi Key Vault, Anda dapat meningkatkan performa dengan mengaktifkan resolusi rahasia paralel menggunakan parallelSecretResolutionEnabled properti di KeyVaultOptions. Ini memungkinkan penyedia untuk mengambil beberapa rahasia secara paralel daripada secara berurutan:

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

Catatan

Saat menyelesaikan rahasia secara paralel, Anda mungkin menemukan batas layanan Azure Key Vault. Untuk menangani pembatasan secara efektif, terapkan praktik terbaik pembatasan pada sisi klien dengan mengonfigurasi opsi pengulangan yang sesuai untuk SecretClient. Anda dapat mendaftarkan instans kustom SecretClient atau mengonfigurasi clientOptions melalui AzureAppConfigurationOptions.keyVaultOptions.

Pembaruan rahasia Key Vault

Azure App Configuration memungkinkan Anda mengonfigurasi interval refresh rahasia secara independen dari siklus refresh konfigurasi Anda. Ini sangat penting untuk keamanan karena meskipun URI referensi Key Vault di App Configuration tetap tidak berubah, rahasia dasar di Key Vault dapat diganti sebagai bagian dari praktik keamanan Anda.

Untuk memastikan aplikasi Anda selalu menggunakan nilai rahasia terbaru, konfigurasikan secretRefreshIntervalInMs properti di KeyVaultOptions. Ini memaksa penyedia untuk mengambil nilai rahasia baru dari Key Vault saat:

Panggilan aplikasi Anda AzureAppConfiguration.refresh
Interval penyegaran yang dikonfigurasi untuk informasi rahasia telah berlalu

Mekanisme ini berfungsi bahkan ketika tidak ada perubahan yang terdeteksi di penyimpanan App Configuration Anda, memastikan aplikasi Anda tetap sinkron dengan rahasia yang telah diperbarui.

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

Cuplikan

Snapshot adalah subset bernama yang tidak dapat diubah dari nilai kunci dalam penyimpanan App Configuration. Nilai kunci yang membentuk rekam jepret dipilih selama waktu pembuatan melalui penggunaan filter kunci dan label. Setelah rekam jepret dibuat, nilai kunci di dalamnya dijamin tidak berubah.

Anda dapat menggunakan pemilih rekam jepret untuk memuat nilai kunci atau bendera fitur dari rekam jepret:

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

Memulai ulang startup

Pemuatan konfigurasi adalah operasi kunci dalam jalur kritis selama pengaktifan aplikasi. Untuk memastikan keandalan, penyedia Azure App Configuration menerapkan mekanisme coba lagi yang kuat selama beban konfigurasi awal. Ini membantu melindungi aplikasi Anda dari masalah jaringan sementara yang mungkin mencegah keberhasilan startup.

Anda dapat menyesuaikan perilaku ini melalui AzureAppConfigurationOptions.startupOptions:

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

Replikasi lokasi geografis

Untuk informasi tentang menggunakan replikasi geografis, buka Mengaktifkan replikasi geografis.

Langkah berikutnya

Untuk mempelajari cara menggunakan penyedia konfigurasi JavaScript, lanjutkan ke tutorial berikut.

Menggunakan konfigurasi dinamis di JavaScript

Untuk mempelajari cara menggunakan pustaka manajemen fitur JavaScript, lanjutkan ke dokumentasi berikut.

Manajemen JavaScript Fitur

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-08-20

Bagikan melalui

Penyedia konfigurasi JavaScript

Memuat konfigurasi

Mengonsumsi konfigurasi

Penanganan tipe konten JSON

Memuat nilai kunci tertentu menggunakan pemilih

Filter tag

Memangkas awalan dari kunci

Refresh konfigurasi

Panggilan balik refresh kustom

Refresh pada kunci sentinel

Bendera fitur

Manajemen fitur

Referensi Key Vault

Resolusi rahasia paralel

Pembaruan rahasia Key Vault

Cuplikan

Memulai ulang startup

Replikasi lokasi geografis

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: