Biblioteca cliente de App Configuration para JavaScript

Artículo
11/06/2024

Azure App Configuration es un servicio administrado que ayuda a los desarrolladores a centralizar su configuración de aplicaciones y características de forma sencilla y segura.

Use la biblioteca cliente para App Configuration para:

Creación de representaciones y asignaciones de claves flexibles
Etiquetar claves con etiquetas
Reproducir la configuración desde cualquier momento dado
Administrar instantáneas de la configuración de una aplicación

Vínculos clave:

código fuente
paquete de (NPM)
documentación de referencia de api de
documentación del producto de
ejemplos de

Empezar

Instalación del paquete

npm install @azure/app-configuration

Entornos admitidos actualmente

versiones ltS de Node.js
Versiones más recientes de Safari, Chrome, Edge y Firefox.

Consulte nuestra de directiva de soporte técnico de para obtener más información.

Prerrequisitos

Un de suscripción de Azure de
Un recurso de App Configuration

Creación de un recurso de App Configuration

Puede usar el azure Portal o la CLI de Azure para crear un recurso de Azure App Configuration.

Ejemplo (CLI de Azure):

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

Autenticación del cliente

AppConfigurationClient puede autenticarse mediante una entidad de servicio de o mediante una cadena de conexión .

Autenticación con una entidad de servicio

La autenticación a través de la entidad de servicio se realiza mediante:

Creación de una credencial mediante el paquete de @azure/identity.
Establecer las reglas de RBAC adecuadas en el recurso AppConfiguration. Puede encontrar más información sobre los roles de App Configuration aquí.

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

Puede encontrar más información sobre @azure/identityaquí

Nubes soberanas

Para autenticarse con un recurso en una nube soberana de , deberá establecer el authorityHost en las opciones de credenciales o a través de la variable de entorno 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 })
);

Puede encontrar más información sobre @azure/identityaquí

Autenticación con una cadena de conexión

Para obtener la cadena de conexión principal para un recurso de App Configuration, puede usar este comando de la CLI de Azure:

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

Además, en el código ahora puede crear el cliente de App Configuration con la cadena de conexión obtuvo de la CLI de Azure:

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

Conceptos clave

El AppConfigurationClient tiene algunos cambios de terminología de App Configuration en el portal.

Los pares clave-valor se representan como objetos ConfigurationSetting
El bloqueo y desbloqueo de una configuración se representa en el campo isReadOnly, que puede alternar mediante setReadOnly.
Las instantáneas se representan como objetos ConfigurationSnapshot.

El cliente sigue una metodología de diseño sencilla: ConfigurationSetting se puede pasar a cualquier método que tome un ConfigurationSettingParam o ConfigurationSettingId.

Esto significa que este patrón funciona:

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

o, por ejemplo, volver a obtener una configuración:

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

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

La versión de api de 2022-11-01-preview admite instantáneas de configuración: copias inmutables y a un momento dado de un almacén de configuración. Las instantáneas se pueden crear con filtros que determinan qué pares clave-valor se encuentran dentro de la instantánea, creando una vista inmutable y compuesta del almacén de configuración. Esta característica permite a las aplicaciones mantener una vista coherente de la configuración, lo que garantiza que no haya coincidencias de versiones con la configuración individual debido a la lectura a medida que se realizaron actualizaciones. Por ejemplo, esta característica se puede usar para crear "instantáneas de configuración de versión" dentro de una instancia de App Configuration. Consulte la sección crear y obtener una instantánea en el ejemplo siguiente.

Ejemplos

Crear y obtener una configuración

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

Creación de una instantánea

beginCreateSnapshot proporciona el sondeo para sondear la creación de instantáneas.

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

También puede usar beginCreateSnapshotAndWait para tener el resultado de la creación directamente después de que se realice el sondeo.

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

Obtención de una instantánea

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

Enumeración del `ConfigurationSetting` en la instantánea

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

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

Enumeración de todas las instantáneas del servicio

const snapshots = await client.listSnapshots();

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

Recuperar y archivar la instantánea

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

Solución de problemas

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Compatibilidad con React Native

React Native no admite algunas API de JavaScript que usa esta biblioteca del SDK, por lo que debe proporcionar polyfills para ellos. Consulte nuestro ejemplo de React Native con Expo para obtener más detalles.

Pasos siguientes

En los ejemplos siguientes se muestran las distintas formas de interactuar con App Configuration:

helloworld.ts: obtener, establecer y eliminar valores de configuración.
helloworldWithLabels.ts: use etiquetas para agregar dimensiones adicionales a la configuración de escenarios como beta frente a producción.
optimisticConcurrencyViaEtag.ts: establezca valores mediante etags para evitar sobrescrituras accidentales.
setReadOnlySample.ts: marcar la configuración como de solo lectura para evitar la modificación.
getSettingOnlyIfChanged.ts: obtenga una configuración solo si cambió de la última vez que la obtuvo.
listRevisions.ts: enumera las revisiones de una clave, lo que le permite ver los valores anteriores y cuándo se establecieron.
secretReference.ts: SecretReference representa un valor de configuración que hace referencia a como secreto de KeyVault.
snapshot.ts: crear, enumerar las opciones de configuración y archivar instantáneas.
featureFlag.ts: las marcas de características son configuraciones que siguen un esquema JSON específico para el valor.

Puede encontrar ejemplos más detallados en la carpeta ejemplos en GitHub.

Contribuyendo

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.

Las pruebas de este módulo son una combinación de pruebas dinámicas y unitarias, que requieren que tenga una instancia de Azure App Configuration. Para ejecutar las pruebas, deberá ejecutar:

rush update
rush build -t @azure/app-configuration
Cree un archivo .env con estos contenidos en la carpeta sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Consulte nuestra carpeta pruebas de para obtener más detalles.

impresiones

Compartir a través de

Biblioteca cliente de App Configuration para JavaScript

Empezar

Instalación del paquete

Entornos admitidos actualmente

Prerrequisitos

Creación de un recurso de App Configuration

Autenticación del cliente

Autenticación con una entidad de servicio

Nubes soberanas

Autenticación con una cadena de conexión

Conceptos clave

Ejemplos

Crear y obtener una configuración

Creación de una instantánea

Obtención de una instantánea

Enumeración del `ConfigurationSetting` en la instantánea

Enumeración de todas las instantáneas del servicio

Recuperar y archivar la instantánea

Solución de problemas

Registro

Compatibilidad con React Native

Pasos siguientes

Contribuyendo

Recursos adicionales

Compartir a través de

Biblioteca cliente de App Configuration para JavaScript

Empezar

Instalación del paquete

Entornos admitidos actualmente

Prerrequisitos

Creación de un recurso de App Configuration

Autenticación del cliente

Autenticación con una entidad de servicio

Nubes soberanas

Autenticación con una cadena de conexión

Conceptos clave

Ejemplos

Crear y obtener una configuración

Creación de una instantánea

Obtención de una instantánea

Enumeración del ConfigurationSetting en la instantánea

Enumeración de todas las instantáneas del servicio

Recuperar y archivar la instantánea

Solución de problemas

Registro

Compatibilidad con React Native

Pasos siguientes

Contribuyendo

Proyectos relacionados

Recursos adicionales

Enumeración del `ConfigurationSetting` en la instantánea