Bibliothèque cliente App Configuration pour JavaScript

Article
11/06/2024

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é.

Utilisez la bibliothèque cliente pour App Configuration pour :

Créer des représentations et des mappages de clés flexibles
Baliser des clés avec des étiquettes
Relecture des paramètres à partir de n’importe quel point dans le temps
Gérer les instantanés de la configuration d’une application

Liens clés :

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

Commencer

Installer le package

npm install @azure/app-configuration

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

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

Vous trouverez plus d’informations sur @azure/identityici

Clouds souverains

Pour vous authentifier auprès d’une ressource dans unde cloud souverain , vous devez définir l' dans les options d’informations d’identification ou via la variable d’environnement .

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

Vous trouverez plus d’informations sur @azure/identityici

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 :

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

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 :

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 :

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

Créer et obtenir un paramètre

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

Créer un instantané

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

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

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

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

Obtenir un instantané

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

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

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

const snapshots = await client.listSnapshots();

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

Récupérer et archiver l’instantané

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

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

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

Impressions

Partager via

Bibliothèque cliente App Configuration pour JavaScript

Commencer

Installer le package

Environnements actuellement pris en charge

Conditions préalables

Créer une ressource App Configuration

Authentifier le client

Authentification auprès d’un principal de service

Clouds souverains

Authentification avec une chaîne de connexion

Concepts clés

Exemples

Créer et obtenir un paramètre

Créer un instantané

Obtenir un instantané

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

Répertorier tous les instantanés du service

Récupérer et archiver l’instantané

Dépannage

Exploitation forestière

Prise en charge de React Native

Étapes suivantes

Contribuant

Ressources supplémentaires

Partager via

Bibliothèque cliente App Configuration pour JavaScript

Commencer

Installer le package

Environnements actuellement pris en charge

Conditions préalables

Créer une ressource App Configuration

Authentifier le client

Authentification auprès d’un principal de service

Clouds souverains

Authentification avec une chaîne de connexion

Concepts clés

Exemples

Créer et obtenir un paramètre

Créer un instantané

Obtenir un instantané

Répertorier les ConfigurationSetting dans l’instantané

Répertorier tous les instantanés du service

Récupérer et archiver l’instantané

Dépannage

Exploitation forestière

Prise en charge de React Native

Étapes suivantes

Contribuant

Projets connexes

Ressources supplémentaires

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