Bagikan melalui

Pustaka klien App Configuration untuk JavaScript

  • Artikel

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

Gunakan pustaka klien untuk App Configuration untuk:

  • Membuat representasi dan pemetaan kunci yang fleksibel
  • Tandai kunci dengan label
  • Pengaturan pemutaran ulang dari titik waktu mana pun
  • Mengelola rekam jepret konfigurasi aplikasi

Tautan kunci:

Persiapan

Menginstal paket

npm install @azure/app-configuration

Lingkungan yang saat ini didukung

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 

const azureIdentity = require("@azure/identity");
const appConfig = require("@azure/app-configuration");

const credential = new azureIdentity.DefaultAzureCredential();
const client = new appConfig.AppConfigurationClient(
  endpoint, // ex: <https://<your appconfig resource>.azconfig.io>
  credential
);

Informasi selengkapnya tentang @azure/identity dapat ditemukan di sini

Sovereign Clouds

Untuk mengautentikasi dengan sumber daya di Sovereign Cloud, Anda harus mengatur authorityHost dalam opsi kredensial atau melalui variabel lingkungan AZURE_AUTHORITY_HOST.

const { AppConfigurationClient } = require("@azure/app-configuration");
const { DefaultAzureCredential, AzureAuthorityHosts } = require("@azure/identity");

// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(
  endpoint, // ex: <https://<your appconfig resource>.azconfig.azure.cn>
  new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina })
);

Informasi selengkapnya tentang @azure/identity dapat ditemukan di sini

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:

const client = new AppConfigurationClient("<connection string>");

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:

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:

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

Membuat dan mendapatkan pengaturan

const appConfig = require("@azure/app-configuration");

const client = new appConfig.AppConfigurationClient(
  "<App Configuration connection string goes here>"
);

async function run() {
  const newSetting = 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.
    // /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);
}

run().catch((err) => console.log("ERROR:", err));

Membuat rekam jepret

beginCreateSnapshot memberi Anda polling untuk polling untuk pembuatan rekam jepret.

const { AppConfigurationClient } = require("@azure/app-configuration");

const client = new AppConfigurationClient(
  "<App Configuration connection string goes here>"
);


async function run() {
  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();
}

run().catch((err) => console.log("ERROR:", err));

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

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

Mendapatkan rekam jepret

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

Mencantumkan ConfigurationSetting dalam rekam jepret

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

const snapshots = await client.listSnapshots();

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

Memulihkan dan mengarsipkan rekam jepret

// 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:

const { setLogLevel } = require("@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:

  1. rush update
  2. rush build -t @azure/app-configuration
  3. Buat file .env dengan konten ini di folder sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
  4. cd sdk\appconfiguration\app-configuration
  5. npm run test.

Lihat folder pengujian kami untuk detail selengkapnya.

Tayangan