App Configuration-clientbibliotheek voor JavaScript

Artikel
07/17/2024

Azure App Configuration is een beheerde service waarmee ontwikkelaars hun toepassings- en functie-instellingen eenvoudig en veilig kunnen centraliseren.

Gebruik de clientbibliotheek voor App Configuration om:

Flexibele sleutelweergaven en -toewijzingen maken
Sleutels taggen met labels
Instellingen voor opnieuw afspelen vanaf een bepaald tijdstip
Momentopnamen van de configuratie van een app beheren

Sleutelkoppelingen:

Slag

Het pakket installeren

npm install @azure/app-configuration

Momenteel ondersteunde omgevingen

LTS-versies van Node.js
Nieuwste versies van Safari, Chrome, Edge en Firefox.

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

Een Azure-abonnement
Een App Configuration--resource

Een App Configuration-resource maken

U kunt de Azure Portal of de Azure CLI- gebruiken om een Azure App Configuration-resource te maken.

Voorbeeld (Azure CLI):

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

De client verifiëren

AppConfigurationClient kan worden geverifieerd met behulp van een service-principal of met behulp van een verbindingsreeks.

Verifiëren met een service-principal

Verificatie via service-principal wordt uitgevoerd door:

Een referentie maken met behulp van het @azure/identity-pakket.
De juiste RBAC-regels instellen voor uw AppConfiguration-resource. Meer informatie over App Configuration-rollen vindt u hier .

DefaultAzureCredential- gebruiken

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

Meer informatie over @azure/identity vindt u hier

Onafhankelijke clouds

Als u wilt verifiëren met een resource in een Sovereign Cloud, moet u de authorityHost instellen in de referentieopties of via de omgevingsvariabele 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 })
);

Meer informatie over @azure/identity vindt u hier

Verifiëren met een verbindingsreeks

Als u de primaire verbindingsreeks wilt ophalen voor een App Configuration-resource, kunt u deze Azure CLI-opdracht gebruiken:

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

En in code kunt u nu uw App Configuration-client maken met de verbindingsreeks u hebt verkregen vanuit de Azure CLI:

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

Sleutelbegrippen

De AppConfigurationClient heeft enkele terminologiewijzigingen ten laste van App Configuration in de portal.

Sleutel-/waardeparen worden weergegeven als ConfigurationSetting objecten
Het vergrendelen en ontgrendelen van een instelling wordt weergegeven in het isReadOnly veld, dat u kunt in- en uitschakelen met behulp van setReadOnly.
Momentopnamen worden weergegeven als ConfigurationSnapshot objecten.

De klant volgt een eenvoudige ontwerpmethodologie: ConfigurationSetting kan worden doorgegeven aan elke methode die een ConfigurationSettingParam of ConfigurationSettingIdgebruikt.

Dit betekent dat dit patroon werkt:

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

of bijvoorbeeld het opnieuw ophalen van een instelling:

let setting = await client.getConfigurationSetting({
  key: "hello"
});

// re-get the setting
setting = await client.getConfigurationSetting(setting);

De 2022-11-01-preview API-versie ondersteunt configuratiemomentopnamen: onveranderbare, point-in-time kopieën van een configuratiearchief. Momentopnamen kunnen worden gemaakt met filters die bepalen welke sleutel-waardeparen zich in de momentopname bevinden, waardoor een onveranderbare, samengestelde weergave van het configuratiearchief wordt gemaakt. Met deze functie kunnen toepassingen een consistente weergave van de configuratie houden, zodat er geen versies overeenkomen met afzonderlijke instellingen vanwege het lezen wanneer er updates zijn uitgevoerd. Deze functie kan bijvoorbeeld worden gebruikt om 'momentopnamen van releaseconfiguratie' te maken in een App Configuration. Zie de sectie maken en een momentopname maken in het onderstaande voorbeeld.

Voorbeelden

Een instelling maken en ophalen

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

Een momentopname maken

beginCreateSnapshot geeft u de poller om te peilen naar het maken van de momentopname.

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

U kunt ook beginCreateSnapshotAndWait gebruiken om het resultaat van het maken direct nadat de polling is voltooid.

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

Een momentopname ophalen

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

De `ConfigurationSetting` weergeven in de momentopname

const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");

for await (const setting of retrievedSnapshotSettings) {
  console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}

Alle momentopnamen van de service weergeven

const snapshots = await client.listSnapshots();

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

De momentopname herstellen en archiveren

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

Probleemoplossing

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

React Native-ondersteuning

React Native biedt geen ondersteuning voor sommige JavaScript-API's die door deze SDK-bibliotheek worden gebruikt, dus u moet polyfills voor deze api's opgeven. Zie ons React Native-voorbeeld met Expo voor meer informatie.

Volgende stappen

In de volgende voorbeelden ziet u de verschillende manieren waarop u met App Configuration kunt werken:

helloworld.ts: configuratiewaarden ophalen, instellen en verwijderen.
helloworldWithLabels.ts: gebruik labels om extra dimensies toe te voegen aan uw instellingen voor scenario's zoals bèta versus productie.
optimisticConcurrencyViaEtag.ts : stel waarden in met behulp van etags om onbedoelde overschrijven te voorkomen.
setReadOnlySample.ts: instellingen markeren als alleen-lezen om wijziging te voorkomen.
getSettingOnlyIfChanged.ts- Haal een instelling alleen op als deze is gewijzigd van de laatste keer dat u deze hebt gekregen.
listRevisions.ts: de revisies van een sleutel weergeven, zodat u eerdere waarden en wanneer ze zijn ingesteld, kunt zien.
secretReference.ts - SecretReference vertegenwoordigt een configuratie-instelling die verwijst naar KeyVault-geheim.
snapshot.ts: configuratie-instellingen maken, vermelden en momentopnamen archiveren.
featureFlag.ts: functievlagmen zijn instellingen die het specifieke JSON-schema voor de waarde volgen.

Meer uitgebreide voorbeelden vindt u in de voorbeelden map op GitHub.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

De tests van deze module zijn een combinatie van live- en eenheidstests, waarvoor u een Azure App Configuration-exemplaar moet hebben. Als u de tests wilt uitvoeren, moet u het volgende uitvoeren:

rush update
rush build -t @azure/app-configuration
Maak een .env-bestand met deze inhoud in de map sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Bekijk de map tests voor meer informatie.

indrukken

Delen via

App Configuration-clientbibliotheek voor JavaScript

Slag

Het pakket installeren

Momenteel ondersteunde omgevingen

Voorwaarden

Een App Configuration-resource maken

De client verifiëren

Verifiëren met een service-principal

Onafhankelijke clouds

Verifiëren met een verbindingsreeks

Sleutelbegrippen

Voorbeelden

Een instelling maken en ophalen

Een momentopname maken

Een momentopname ophalen

De `ConfigurationSetting` weergeven in de momentopname

Alle momentopnamen van de service weergeven

De momentopname herstellen en archiveren

Probleemoplossing

Logboekregistratie

React Native-ondersteuning

Volgende stappen

Bijdragen

Aanvullende resources

Delen via

App Configuration-clientbibliotheek voor JavaScript

Slag

Het pakket installeren

Momenteel ondersteunde omgevingen

Voorwaarden

Een App Configuration-resource maken

De client verifiëren

Verifiëren met een service-principal

Onafhankelijke clouds

Verifiëren met een verbindingsreeks

Sleutelbegrippen

Voorbeelden

Een instelling maken en ophalen

Een momentopname maken

Een momentopname ophalen

De ConfigurationSetting weergeven in de momentopname

Alle momentopnamen van de service weergeven

De momentopname herstellen en archiveren

Probleemoplossing

Logboekregistratie

React Native-ondersteuning

Volgende stappen

Bijdragen

Verwante projecten

Aanvullende resources

De `ConfigurationSetting` weergeven in de momentopname