Delen via

App Configuration clientbibliotheek voor JavaScript

  • Artikel

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 het volgende te doen:

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

Belangrijke koppelingen:

Aan de slag

Het pakket installeren

npm install @azure/app-configuration

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Vereisten

Een App Configuration resource maken

U kunt 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 hierover @azure/identity vindt u hier

Onafhankelijke clouds

Als u wilt verifiëren met een resource in een onafhankelijke cloud, moet u de authorityHost instellen in de referentieopties of via de AZURE_AUTHORITY_HOST omgevingsvariabele.

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 hierover @azure/identity vindt u hier

Verifiëren met een verbindingsreeks

Als u de primaire verbindingsreeks voor een App Configuration resource wilt ophalen, 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 ontvangen van de Azure CLI:

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

Belangrijkste concepten

De AppConfigurationClient heeft enkele terminologiewijzigingen ten aanzien 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- of uitschakelen met .setReadOnly
  • Momentopnamen worden weergegeven als ConfigurationSnapshot objecten.

De client 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, een instelling opnieuw ophalen:

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

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

De 2022-11-01-preview API-versie ondersteunt momentopnamen van configuraties: onveranderbare, naar een bepaald tijdstip opgeslagen 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 behouden, zodat er geen versies zijn die niet overeenkomen met afzonderlijke instellingen vanwege het lezen van updates. Deze functie kan bijvoorbeeld worden gebruikt om 'momentopnamen van de releaseconfiguratie' te maken binnen een App Configuration. Zie de sectie Een momentopname maken en ophalen 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"
  });

  let 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 voor 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 gebruiken beginCreateSnapshotAndWait 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);

ConfigurationSetting De weergeven in de momentopname

let 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

let 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
let archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);

// Snapshot is in archive status
let recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);

Problemen oplossen

Logboekregistratie

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

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.

React Native ondersteuning

React Native biedt geen ondersteuning voor bepaalde JavaScript-API's die door deze SDK-bibliotheek worden gebruikt, dus u moet polyfills voor hen 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 overschrijvingen te voorkomen.
  • setReadOnlySample.ts - Instellingen markeren als alleen-lezen om wijziging te voorkomen.
  • getSettingOnlyIfChanged.ts - Haal een instelling alleen op als deze is gewijzigd ten opzichte van de laatste keer dat u deze hebt ontvangen.
  • listRevisions.ts - Vermeld de revisies van een sleutel, zodat u eerdere waarden kunt zien en wanneer deze zijn ingesteld.
  • secretReference.ts - SecretReference vertegenwoordigt een configuratie-instelling die verwijst als KeyVault-geheim.
  • snapshot.ts - Maken, configuratie-instellingen weergeven en momentopnamen archiveren.
  • featureFlag.ts - Functievlagmen zijn instellingen die een specifiek JSON-schema voor de waarde volgen.

Meer gedetailleerde voorbeelden vindt u in de map met voorbeelden op GitHub.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de handleiding 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:

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

Bekijk onze testmap voor meer informatie.

Weergaven