Bibliothèque cliente Azure App Configuration pour JavaScript - version 1.10.0

azure App Configuration est un service géré qui permet aux développeurs de centraliser leurs paramètres d’application et de fonctionnalité simplement et en toute sécurité.

Liens clés :

code source
package (NPM)
Documentation de référence de l’API
Documentation concernant le produit
Exemples

Choisissez le bon forfait

Utilisez @azure/app-configuration (cette bibliothèque) pour :

Gérer les paramètres de configuration et les instantanés dans Azure App Configuration
Effectuer des lectures granulaires qui fonctionnent en dehors du domaine de la consommation normale de la configuration

La plupart des applications doivent commencer par la bibliothèque @azure/app-configuration-provider , qui s’appuie sur cette bibliothèque cliente de bas niveau et constitue la méthode recommandée pour consommer la configuration au moment de l’exécution. Il ajoute :

Modèles d’accès flexibles utilisant la configuration sous forme de mappage clé/valeur ou d’objet JSON structuré
Mécanisme de requête pour composer de manière déclarative la configuration de l’application
Actualisation de la configuration pendant l’exécution
Haute fiabilité avec mise en cache, découverte de réplicas, basculement et équilibrage de charge
Résolution de référence du coffre de clés et actualisation automatique
Intégration de l’indicateur de fonctionnalité pour la bibliothèque de gestion des @microsoft/fonctionnalités

Pour plus d’informations, consultez la page Vue d’ensemble du fournisseur de configuration.

Commencer

Installer le package

npm install @azure/app-configuration

Note: Pour les applications qui n’ont besoin de lire que les valeurs de configuration, nous vous suggérons d’utiliser la bibliothèque @azure/app-configuration-provider à la place.

Environnements actuellement pris en charge

versions LTS de Node.js
Dernières versions de Safari, Chrome, Edge et Firefox.

Pour plus d’informations, consultez notre de stratégie de support .

Conditions préalables

Un abonnement Azure
Ressource App Configuration

Créer une ressource App Configuration

Vous pouvez utiliser le portail Azure ou le Azure CLI pour créer une ressource Azure App Configuration.

Exemple (Azure CLI) :

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

Authentifier le client

AppConfigurationClient peut s’authentifier à l’aide d’un principal de service ou à l’aide d’une chaîne de connexion .

Authentification auprès d’un principal de service

L’authentification via le principal de service est effectuée par :

Création d’informations d’identification à l’aide du package @azure/identity.
Définition des règles RBAC appropriées sur votre ressource AppConfiguration. Vous trouverez plus d’informations sur les rôles App Configuration ici.

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

Vous trouverez plus d’informations sur @azure/identityici

Clouds souverains

Pour vous authentifier avec une ressource dans un cloud souverain, vous devez définir les options dans audience le AppConfigurationClient constructeur.

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

Remarque : Lorsque audience la propriété n’est pas définie, le SDK utilise par défaut Azure Public Cloud.

Authentification avec une chaîne de connexion

Pour obtenir la chaîne de connexion principale pour une ressource App Configuration, vous pouvez utiliser cette commande Azure CLI :

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

Et dans le code, vous pouvez maintenant créer votre client App Configuration avec la chaîne de connexion vous avez obtenu à partir d’Azure CLI :

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

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

Concepts clés

Le AppConfigurationClient a des modifications de terminologie à partir d’App Configuration dans le portail.

Les paires clé/valeur sont représentées en tant qu’objets ConfigurationSetting
Le verrouillage et le déverrouillage d’un paramètre sont représentés dans le champ isReadOnly, que vous pouvez basculer à l’aide de setReadOnly.
Les instantanés sont représentés sous forme d’objets ConfigurationSnapshot.

Le client suit une méthodologie de conception simple : ConfigurationSetting peut être passé dans n’importe quelle méthode qui prend un ConfigurationSettingParam ou ConfigurationSettingId.

Cela signifie que ce modèle fonctionne :

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

ou, par exemple, récupérer un paramètre :

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 version de l’API 2022-11-01-preview prend en charge les captures instantanées de configuration : copies immuables et ponctuelles d’un magasin de configuration. Les instantanés peuvent être créés avec des filtres qui déterminent les paires clé-valeur contenues dans l’instantané, créant une vue immuable composée du magasin de configuration. Cette fonctionnalité permet aux applications de conserver une vue cohérente de la configuration, en s’assurant qu’il n’existe aucune incompatibilité de version avec les paramètres individuels en raison de la lecture des mises à jour. Par exemple, cette fonctionnalité peut être utilisée pour créer des « captures instantanées de configuration de mise en production » au sein d’une app Configuration. Consultez la créer et obtenir une section de capture instantanée dans l’exemple ci-dessous.

Exemples

Note: Si votre application a uniquement besoin de récupérer les valeurs de configuration et ne nécessite pas d’effectuer d’opérations de création, de mise à jour ou de suppression sur les paramètres de configuration, envisagez d’utiliser la bibliothèque @azure/app-configuration-provider à la place. La bibliothèque du fournisseur offre une expérience simplifiée pour le chargement des données de configuration au moment de l’exécution et des fonctionnalités supplémentaires. Vous trouverez de nombreux exemples de code dans la documentation Configuration d’application Azure sur Microsoft Learn.

Créer et obtenir un paramètre

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

Créer un instantané

beginCreateSnapshot vous donne le polleur pour interroger la création d’instantanés.

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

Vous pouvez également utiliser beginCreateSnapshotAndWait pour avoir le résultat de la création directement après l’interrogation.

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

Obtenir un instantané

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

Répertorier les `ConfigurationSetting` dans l’instantané

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

Répertorier tous les instantanés du service

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

Récupérer et archiver l’instantané

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

Dépannage

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.

Prise en charge de React Native

React Native ne prend pas en charge certaines API JavaScript utilisées par cette bibliothèque sdk. Vous devez donc fournir des polyfills pour eux. Pour plus d’informations, consultez notre exemple React Native avec Expo.

Étapes suivantes

Les exemples suivants vous montrent les différentes façons d’interagir avec App Configuration :

helloworld.ts - Obtenir, définir et supprimer des valeurs de configuration.
helloworldWithLabels.ts : utilisez des étiquettes pour ajouter des dimensions supplémentaires à vos paramètres pour des scénarios tels que la version bêta et la production.
optimisticConcurrencyViaEtag.ts : définissez des valeurs à l’aide d’etags pour empêcher les remplacements accidentels.
setReadOnlySample.ts : marquage des paramètres en lecture seule pour empêcher la modification.
getSettingOnlyIfChanged.ts - Obtenez un paramètre uniquement s’il a changé à partir de la dernière fois que vous l’avez obtenu.
listRevisions.ts - Répertoriez les révisions d’une clé, ce qui vous permet de voir les valeurs précédentes et quand elles ont été définies.
secretReference.ts - SecretReference représente un paramètre de configuration qui fait référence au secret KeyVault.
snapshot.ts - Créer, répertorier les paramètres de configuration et archiver des instantanés.
featureFlag.ts : les indicateurs de fonctionnalité sont des paramètres qui suivent un schéma JSON spécifique pour la valeur.

Vous trouverez des exemples plus détaillés dans les exemples dossier sur GitHub.

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Les tests de ce module sont un mélange de tests en direct et unitaires, ce qui vous oblige à disposer d’une instance Azure App Configuration. Pour exécuter les tests, vous devez exécuter :

pnpm install
pnpm build --filter @azure/app-configuration...
Créez un fichier .env avec ce contenu dans le dossier sdk\appconfiguration\app-configuration : APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Pour plus d’informations, consultez notre dossier tests.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-11-13