App Configuration client library for JavaScript
Azure App Configuration is a managed service that helps developers centralize their application and feature settings simply and securely.
Use the client library for App Configuration to:
- Create flexible key representations and mappings
- Tag keys with labels
- Replay settings from any point in time
- Manage snapshots of an app's configuration
Key links:
Getting started
Install the package
npm install @azure/app-configuration
Currently supported environments
See our support policy for more details.
Prerequisites
Create an App Configuration resource
You can use the Azure Portal or the Azure CLI to create an Azure App Configuration resource.
Example (Azure CLI):
az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus
Authenticate the client
AppConfigurationClient can authenticate using a service principal or using a connection string.
Authenticating with a service principal
Authentication via service principal is done by:
- Creating a credential using the
@azure/identity
package. - Setting appropriate RBAC rules on your AppConfiguration resource.
More information on App Configuration roles can be found here.
Using DefaultAzureCredential
const azureIdentity = require("@azure/identity");
const appConfig = require("@azure/app-configuration");
const credential = new azureIdentity.DefaultAzureCredential();
const client = new appConfig.AppConfigurationClient(
endpoint,
credential
);
More information about @azure/identity
can be found here
Sovereign Clouds
To authenticate with a resource in a Sovereign Cloud, you will need to set the authorityHost
in the credential options or via the AZURE_AUTHORITY_HOST
environment variable.
const { AppConfigurationClient } = require("@azure/app-configuration");
const { DefaultAzureCredential, AzureAuthorityHosts } = require("@azure/identity");
const client = new AppConfigurationClient(
endpoint,
new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina })
);
More information about @azure/identity
can be found here
Authenticating with a connection string
To get the Primary connection string for an App Configuration resource you can use this Azure CLI command:
az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"
And in code you can now create your App Configuration client with the connection string you got from the Azure CLI:
const client = new AppConfigurationClient("<connection string>");
Key concepts
The AppConfigurationClient
has some terminology changes from App Configuration in the portal.
- Key/Value pairs are represented as
ConfigurationSetting
objects - Locking and unlocking a setting is represented in the
isReadOnly
field, which you can toggle using setReadOnly
. - Snapshots are represented as
ConfigurationSnapshot
objects.
The client follows a simple design methodology - ConfigurationSetting
can be passed into any method that takes a ConfigurationSettingParam
or ConfigurationSettingId
.
This means this pattern works:
const setting = await client.getConfigurationSetting({
key: "hello"
});
setting.value = "new value!";
await client.setConfigurationSetting(setting);
await client.setReadOnly(setting, true);
await client.deleteConfigurationSetting(setting);
or, for example, re-getting a setting:
let setting = await client.getConfigurationSetting({
key: "hello"
});
setting = await client.getConfigurationSetting(setting);
The 2022-11-01-preview
API version supports configuration snapshots: immutable, point-in-time copies of a configuration store. Snapshots can be created with filters that determine which key-value pairs are contained within the snapshot, creating an immutable, composed view of the configuration store. This feature enables applications to hold a consistent view of configuration, ensuring that there are no version mismatches to individual settings due to reading as updates were made. For example, this feature can be used to create "release configuration snapshots" within an App Configuration. See the create and get a snapshot section in the example below.
Examples
Create and get a setting
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",
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));
Create a snapshot
beginCreateSnapshot
gives you the poller to poll for the snapshot creation.
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));
You can also use beginCreateSnapshotAndWait
to have the result of the creation directly after the polling is done.
const snapshot = await client.beginCreateSnapshotAndWait({
name:"testsnapshot",
retentionPeriod: 2592000,
filters: [{keyFilter: key, labelFilter: label}],
});
Get a snapshot
const retrievedSnapshot = await client.getSnapshot("testsnapshot");
console.log("Retrieved snapshot:", retrievedSnapshot);
List the ConfigurationSetting
in the snapshot
const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");
for await (const setting of retrievedSnapshotSettings) {
console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}
List all snapshots from the service
const snapshots = await client.listSnapshots();
for await (const snapshot of snapshots) {
console.log(`Found snapshot: ${snapshot.name}`);
}
Recover and archive the snapshot
const archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);
const recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);
Troubleshooting
Logging
Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL
environment variable to info
. Alternatively, logging can be enabled at runtime by calling setLogLevel
in the @azure/logger
:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.
React Native support
React Native does not support some JavaScript API used by this SDK library so you need to provide polyfills for them. Please see our React Native sample with Expo for more details.
Next steps
The following samples show you the various ways you can interact with App Configuration:
More in-depth examples can be found in the samples folder on GitHub.
Contributing
If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.
This module's tests are a mixture of live and unit tests, which require you to have an Azure App Configuration instance. To execute the tests you'll need to run:
rush update
rush build -t @azure/app-configuration
- Create a .env file with these contents in the
sdk\appconfiguration\app-configuration
folder:
APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test
.
View our tests
folder for more details.
Related projects