Libreria client di Configurazione app per JavaScript

Articolo
11/06/2024

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

Usare la libreria client per Configurazione app per:

Creare rappresentazioni e mapping di chiavi flessibili
Contrassegna le chiavi con etichette
Impostazioni di riproduzione da qualsiasi punto nel tempo
Gestire gli snapshot della configurazione di un'app

Collegamenti chiave:

Introduttiva

Installare il pacchetto

npm install @azure/app-configuration

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

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

Altre informazioni sulle @azure/identity sono disponibili qui

Cloud sovrani

Per eseguire l'autenticazione con una risorsa in un cloud sovrano , è necessario impostare il authorityHost nelle opzioni delle credenziali o tramite la variabile di ambiente 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 })
);

Altre informazioni sulle @azure/identity sono disponibili qui

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:

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

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:

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:

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

Creare e ottenere un'impostazione

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

Creare uno snapshot

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

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

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

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

Ottenere uno snapshot

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

Elencare il `ConfigurationSetting` nello snapshot

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

const snapshots = await client.listSnapshots();

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

Ripristinare e archiviare lo snapshot

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

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

rush update
rush build -t @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.

impressioni

Condividi tramite

Libreria client di Configurazione app per JavaScript

Introduttiva

Installare il pacchetto

Ambienti attualmente supportati

Prerequisiti

Creare una risorsa di Configurazione app

Autenticare il client

Autenticazione con un'entità servizio

Cloud sovrani

Autenticazione con una stringa di connessione

Concetti chiave

Esempi

Creare e ottenere un'impostazione

Creare uno snapshot

Ottenere uno snapshot

Elencare il `ConfigurationSetting` nello snapshot

Elencare tutti gli snapshot dal servizio

Ripristinare e archiviare lo snapshot

Risoluzione dei problemi

Registrazione

Supporto di React Native

Passaggi successivi

Contribuire

Risorse aggiuntive

Condividi tramite

Libreria client di Configurazione app per JavaScript

Introduttiva

Installare il pacchetto

Ambienti attualmente supportati

Prerequisiti

Creare una risorsa di Configurazione app

Autenticare il client

Autenticazione con un'entità servizio

Cloud sovrani

Autenticazione con una stringa di connessione

Concetti chiave

Esempi

Creare e ottenere un'impostazione

Creare uno snapshot

Ottenere uno snapshot

Elencare il ConfigurationSetting nello snapshot

Elencare tutti gli snapshot dal servizio

Ripristinare e archiviare lo snapshot

Risoluzione dei problemi

Registrazione

Supporto di React Native

Passaggi successivi

Contribuire

Progetti correlati

Risorse aggiuntive

Elencare il `ConfigurationSetting` nello snapshot