Pustaka klien Azure App Configuration untuk JavaScript - versi 1.10.0

Azure App Configuration adalah layanan terkelola yang membantu pengembang mempusatkan pengaturan aplikasi dan fitur mereka dengan sederhana dan aman.

Tautan kunci:

Kode sumber
Paket (NPM)
Dokumentasi referensi API
dokumentasi produk
Sampel

Pilih paket yang tepat

Gunakan konfigurasi @azure/app (library ini) untuk:

Mengelola pengaturan konfigurasi dan rekam jepret di Azure App Configuration
Lakukan pembacaan terperinci yang beroperasi di luar ranah konsumsi konfigurasi normal

Sebagian besar aplikasi harus dimulai dengan pustaka @azure/app-configuration-provider , yang dibangun di atas pustaka klien tingkat rendah ini dan merupakan cara yang direkomendasikan untuk menggunakan konfigurasi saat runtime. Ia menambahkan:

Pola akses fleksibel menggunakan konfigurasi sebagai peta kunci/nilai atau objek JSON terstruktur
Mekanisme kueri untuk menyusun konfigurasi aplikasi secara deklaratif
Refresh konfigurasi selama runtime
Keandalan tinggi dengan caching, penemuan replika, failover, dan penyeimbangan beban
Resolusi referensi brankas kunci dan penyegaran otomatis
Integrasi bendera fitur untuk pustaka manajemen @microsoft/fitur

Untuk informasi selengkapnya, silakan buka ikhtisar penyedia konfigurasi.

Persiapan

Menginstal paket

npm install @azure/app-configuration

Nota: Untuk aplikasi yang hanya perlu membaca nilai konfigurasi, sebaiknya gunakan library @azure/app-configuration-provider sebagai gantinya.

Lingkungan yang saat ini didukung

versi LTS Node.js
Versi terbaru Safari, Chrome, Edge, dan Firefox.

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

Langganan Azure
Sumber daya App Configuration

Membuat sumber daya App Configuration

Anda dapat menggunakan Portal Azure atau Azure CLI untuk membuat sumber daya Azure App Configuration.

Contoh (Azure CLI):

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

Mengautentikasi klien

AppConfigurationClient dapat mengautentikasi menggunakan perwakilan layanan atau menggunakan string koneksi .

Mengautentikasi dengan perwakilan layanan

Autentikasi melalui perwakilan layanan dilakukan dengan:

Membuat kredensial menggunakan paket @azure/identity.
Mengatur aturan RBAC yang sesuai pada sumber daya AppConfiguration Anda. Informasi selengkapnya tentang peran App Configuration dapat ditemukan di sini.

Menggunakan DefaultAzureCredential

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

Informasi selengkapnya tentang @azure/identity dapat ditemukan di sini

Awan Berdaulat

Untuk mengautentikasi dengan sumber daya di Sovereign Cloud, Anda harus mengatur audience opsi di AppConfigurationClient konstruktor.

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

Catatan: Ketika audience properti tidak ditentukan, SDK akan default ke Azure Public Cloud.

Mengautentikasi dengan string koneksi

Untuk mendapatkan string koneksi Utama untuk sumber daya App Configuration, Anda dapat menggunakan perintah Azure CLI ini:

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

Dan dalam kode, Anda sekarang dapat membuat klien App Configuration dengan string koneksi Anda dapatkan dari Azure CLI:

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

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

Konsep utama

AppConfigurationClient memiliki beberapa perubahan terminologi dari App Configuration di portal.

Pasangan Kunci/Nilai direpresentasikan sebagai objek ConfigurationSetting
Mengunci dan membuka kunci pengaturan diwakili di bidang isReadOnly, yang dapat Anda alihkan menggunakan setReadOnly.
Rekam jepret direpresentasikan sebagai objek ConfigurationSnapshot.

Klien mengikuti metodologi desain sederhana - ConfigurationSetting dapat diteruskan ke metode apa pun yang mengambil ConfigurationSettingParam atau ConfigurationSettingId.

Ini berarti pola ini berfungsi:

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

atau, misalnya, mendapatkan kembali pengaturan:

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

Versi API 2022-11-01-preview mendukung rekam jepret konfigurasi: salinan point-in-time penyimpanan konfigurasi yang tidak dapat diubah. Rekam jepret dapat dibuat dengan filter yang menentukan pasangan kunci-nilai mana yang terkandung dalam rekam jepret, membuat tampilan penyimpanan konfigurasi yang tidak dapat diubah dan disusun. Fitur ini memungkinkan aplikasi untuk menyimpan tampilan konfigurasi yang konsisten, memastikan bahwa tidak ada ketidakcocokan versi pada pengaturan individual karena membaca saat pembaruan dilakukan. Misalnya, fitur ini dapat digunakan untuk membuat "rekam jepret konfigurasi rilis" dalam App Configuration. Lihat membuat dan mendapatkan bagian rekam jepret dalam contoh di bawah ini.

Contoh

Nota: Jika aplikasi Anda hanya perlu mengambil nilai konfigurasi dan tidak memerlukan melakukan operasi pembuatan, pembaruan, atau penghapusan pada pengaturan konfigurasi, pertimbangkan untuk menggunakan pustaka penyedia @azure/app-configuration-provider sebagai gantinya. Pustaka penyedia menawarkan pengalaman yang disederhanakan untuk memuat data konfigurasi saat runtime dan fitur tambahan. Anda dapat menemukan banyak sampel kode dalam dokumentasi Konfigurasi Aplikasi Azure di Microsoft Learn.

Membuat dan mendapatkan pengaturan

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

Membuat rekam jepret

beginCreateSnapshot memberi Anda polling untuk polling untuk pembuatan rekam jepret.

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

Anda juga dapat menggunakan beginCreateSnapshotAndWait untuk memiliki hasil pembuatan langsung setelah polling selesai.

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

Mendapatkan rekam jepret

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

Mencantumkan `ConfigurationSetting` dalam rekam jepret

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

Mencantumkan semua rekam jepret dari layanan

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

Memulihkan dan mengarsipkan rekam jepret

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

Pemecahan masalah

Penebangan

Mengaktifkan pengelogan dapat membantu mengungkap informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

Dukungan React Native

React Native tidak mendukung beberapa API JavaScript yang digunakan oleh pustaka SDK ini sehingga Anda perlu menyediakan polifill untuk mereka. Silakan lihat sampel React Native kami dengan Expo untuk detail selengkapnya.

Langkah berikutnya

Sampel berikut menunjukkan berbagai cara untuk berinteraksi dengan App Configuration:

helloworld.ts - Dapatkan, atur, dan hapus nilai konfigurasi.
helloworldWithLabels.ts - Gunakan label untuk menambahkan dimensi tambahan ke pengaturan Anda untuk skenario seperti beta vs produksi.
optimisticConcurrencyViaEtag.ts - Atur nilai menggunakan etag untuk mencegah penimpaan yang tidak disengaja.
setReadOnlySample.ts - Menandai pengaturan sebagai baca-saja untuk mencegah modifikasi.
getSettingOnlyIfChanged.ts - Dapatkan pengaturan hanya jika berubah dari terakhir kali Anda mendapatkannya.
listRevisions.ts - Mencantumkan revisi kunci, memungkinkan Anda melihat nilai sebelumnya dan kapan nilai tersebut ditetapkan.
secretReference.ts - SecretReference mewakili pengaturan konfigurasi yang mereferensikan sebagai rahasia KeyVault.
snapshot.ts - Membuat, mencantumkan pengaturan konfigurasi, dan mengarsipkan rekam jepret.
featureFlag.ts - Bendera fitur adalah pengaturan yang mengikuti skema JSON tertentu untuk nilai tersebut.

Contoh yang lebih mendalam dapat ditemukan di folder sampel di GitHub.

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Pengujian modul ini adalah campuran pengujian langsung dan unit, yang mengharuskan Anda memiliki instans Azure App Configuration. Untuk menjalankan pengujian, Anda harus menjalankan:

pnpm install
pnpm build --filter @azure/app-configuration...
Buat file .env dengan konten ini di folder sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Lihat folder pengujian kami untuk detail selengkapnya.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-11-13