Libreria client Configurazione app di Azure per JavaScript - versione 1.10.0

configurazione app di Azure è un servizio gestito che consente agli sviluppatori di centralizzare le impostazioni di applicazione e funzionalità in modo semplice e sicuro.

Collegamenti chiave:

Scegli il pacchetto giusto

Utilizza @azure/app-configuration (questa libreria) per:

Gestire le impostazioni di configurazione e gli snapshot in Configurazione app di Azure
Eseguire letture granulari che operano al di fuori dell'ambito del normale consumo della configurazione

La maggior parte delle applicazioni deve iniziare con la libreria @azure/app-configuration-provider , che si basa su questa libreria client di basso livello ed è il modo consigliato per utilizzare la configurazione in fase di esecuzione. E aggiunge:

Modelli di accesso flessibili utilizzando la configurazione come mappa chiave/valore o oggetto JSON strutturato
Meccanismo di query per comporre in modo dichiarativo la configurazione dell'app
Aggiornamento della configurazione durante il runtime
Elevata affidabilità con memorizzazione nella cache, rilevamento delle repliche, failover e bilanciamento del carico
Risoluzione dei riferimenti all'insieme di credenziali delle chiavi e aggiornamento automatico
Integrazione dei flag di funzionalità per la libreria di gestione @microsoft/funzionalità

Per ulteriori informazioni, vedere Panoramica del provider di configurazione.

Introduttiva

Installare il pacchetto

npm install @azure/app-configuration

Nota: Per le applicazioni che devono solo leggere i valori di configurazione, è consigliabile usare la libreria @azure/app-configuration-provider .

Ambienti attualmente supportati

versioni LTS di Node.js
Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

Una sottoscrizione di Azure
Una risorsa configurazione app di

Creare una risorsa di Configurazione app

È possibile usare portale di Azure o l'interfaccia della riga di comando di Azure per creare una risorsa di Configurazione app di Azure.

Esempio (interfaccia della riga di comando di Azure):

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

Autenticare il client

AppConfigurationClient può eseguire l'autenticazione usando un'entità servizio o usando una stringa di connessione .

Autenticazione con un'entità servizio

L'autenticazione tramite entità servizio viene eseguita da:

Creazione di credenziali usando il pacchetto @azure/identity.
Impostazione delle regole di controllo degli accessi in base al ruolo appropriate nella risorsa AppConfiguration. Altre informazioni sui ruoli di Configurazione app sono disponibili qui.

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

Altre informazioni sulle @azure/identity sono disponibili qui

Cloud sovrani

Per eseguire l'autenticazione con una risorsa in un Sovereign Cloud, è necessario impostare le audience opzioni nel AppConfigurationClient costruttore.

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

Nota: quando audience la proprietà non è definita, per impostazione predefinita l'SDK utilizzerà il cloud pubblico di Azure.

Autenticazione con una stringa di connessione

Per ottenere la stringa di connessione primaria per una risorsa di Configurazione app, è possibile usare questo comando dell'interfaccia della riga di comando di Azure:

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

Nel codice è ora possibile creare il client di Configurazione app con la stringa di connessione ottenuta dall'interfaccia della riga di comando di Azure:

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

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

Concetti chiave

Il AppConfigurationClient presenta alcune modifiche alla terminologia apportate da Configurazione app nel portale.

Le coppie chiave/valore sono rappresentate come oggetti ConfigurationSetting
Il blocco e lo sblocco di un'impostazione sono rappresentati nel campo isReadOnly, che è possibile attivare o disattivare usando setReadOnly.
Gli snapshot vengono rappresentati come oggetti ConfigurationSnapshot.

Il client segue una semplice metodologia di progettazione: ConfigurationSetting può essere passata in qualsiasi metodo che accetta un ConfigurationSettingParam o ConfigurationSettingId.

Questo significa che questo modello funziona:

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

oppure, ad esempio, recuperare nuovamente un'impostazione:

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

La versione dell'API 2022-11-01-preview supporta gli snapshot di configurazione: copie temporizzate non modificabili di un archivio di configurazione. È possibile creare snapshot con filtri che determinano quali coppie chiave-valore sono contenute nello snapshot, creando una visualizzazione non modificabile e composta dall'archivio di configurazione. Questa funzionalità consente alle applicazioni di mantenere una visualizzazione coerente della configurazione, assicurandosi che non siano presenti mancate corrispondenze di versione alle singole impostazioni a causa della lettura come sono stati eseguiti aggiornamenti. Ad esempio, questa funzionalità può essere usata per creare "snapshot di configurazione della versione" all'interno di una configurazione app. Vedere la sezione creare e ottenere uno snapshot nell'esempio seguente.

Esempi

Nota: Se l'applicazione deve solo recuperare i valori di configurazione e non richiede l'esecuzione di operazioni di creazione, aggiornamento o eliminazione sulle impostazioni di configurazione, è consigliabile usare la libreria @azure/app-configuration-provider . La libreria del provider offre un'esperienza semplificata per il caricamento dei dati di configurazione in fase di esecuzione e funzionalità aggiuntive. È possibile trovare molti esempi di codice nella documentazione di Configurazione app di Azure in Microsoft Learn.

Creare e ottenere un'impostazione

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

Creare uno snapshot

beginCreateSnapshot consente di eseguire il polling del poller per la creazione dello snapshot.

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

È anche possibile usare beginCreateSnapshotAndWait per ottenere il risultato della creazione direttamente al termine del polling.

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

Ottenere uno snapshot

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

Elencare il `ConfigurationSetting` nello snapshot

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

Elencare tutti gli snapshot dal servizio

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

Ripristinare e archiviare lo snapshot

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

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Supporto di React Native

React Native non supporta alcune API JavaScript usate da questa libreria SDK, quindi è necessario fornire polyfill per tali API. Per altri dettagli, vedere l'esempio react native di con Expo.

Passaggi successivi

Gli esempi seguenti illustrano i vari modi in cui è possibile interagire con Configurazione app:

helloworld.ts: ottenere, impostare ed eliminare valori di configurazione.
helloworldWithLabels.ts : usare le etichette per aggiungere altre dimensioni alle impostazioni per scenari come beta e produzione.
optimisticConcurrencyViaEtag.ts : impostare i valori usando etag per evitare sovrascrizioni accidentali.
setReadOnlySample.ts : contrassegnare le impostazioni come di sola lettura per impedire la modifica.
getSettingOnlyIfChanged.ts: ottenere un'impostazione solo se è stata modificata dall'ultima volta che è stata ottenuta.
listRevisions.ts: elencare le revisioni di una chiave, consentendo di visualizzare i valori precedenti e quando sono stati impostati.
secretReference.ts - SecretReference rappresenta un'impostazione di configurazione che fa riferimento come segreto KeyVault.
snapshot.ts: creare, elencare le impostazioni di configurazione e gli snapshot di archiviazione.
featureFlag.ts: i flag di funzionalità sono impostazioni che seguono uno schema JSON specifico per il valore.

Altri esempi approfonditi sono disponibili nella cartella degli esempi di su GitHub.

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

I test di questo modulo sono una combinazione di unit test live e che richiedono l'uso di un'istanza di Configurazione app di Azure. Per eseguire i test è necessario eseguire:

pnpm install
pnpm build --filter @azure/app-configuration...
Creare un file con estensione env con questi contenuti nella cartella sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Per altri dettagli, vedere i test test cartella.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-13