Share via

biblioteca cliente de App Configuration para JavaScript

  • Artículo

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
  • Reproducción de la configuración desde cualquier momento dado
  • Administrar instantáneas de la configuración de una aplicación

Vínculos principales:

Introducción

Instalar el paquete

npm install @azure/app-configuration

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Creación de un recurso de App Configuration

Puede usar 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

Autenticar el cliente

AppConfigurationClient puede autenticarse mediante una entidad de servicio o mediante un 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 @azure/identity paquete.
  • Establecer las reglas de RBAC adecuadas en el recurso AppConfiguration. Puede encontrar más información sobre App Configuration roles aquí.

Usar 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 aquí.@azure/identity

Nubes soberanas

Para autenticarse con un recurso en una nube soberana, deberá establecer en authorityHost las opciones de credenciales o a través de la variable de AZURE_AUTHORITY_HOST entorno.

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 aquí.@azure/identity

Autenticación con un cadena de conexión

Para obtener el cadena de conexión principal de 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]"

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

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

Conceptos clave

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

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

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

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 2022-11-01-preview versión de la API 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 compuesta del almacén de configuración. Esta característica permite a las aplicaciones contener 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 de las actualizaciones realizadas. Por ejemplo, esta característica se puede usar para crear "instantáneas de configuración de versión" dentro de un App Configuration. Consulte la sección crear y obtener una instantánea en el ejemplo siguiente.

Ejemplos

Creación y obtención de 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"
  });

  let retrievedSetting = await client.getConfigurationSetting({
    key: "testkey",
    label: "optional-label"
  });

  console.log("Retrieved value:", retrievedSetting.value);
}

run().catch((err) => console.log("ERROR:", err));

Crear una instantánea

beginCreateSnapshot proporciona al sondeo que se va a sondear para la creación de la instantánea.

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

Obtiene una instantánea

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

Enumeración de en ConfigurationSetting la instantánea

let 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

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

Solución de problemas

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los 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 @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

compatibilidad con React Native

React Native no admite algunas API de JavaScript usadas por 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 en que puede 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 - Establecer valores mediante etags para evitar sobrescrituras accidentales.
  • setReadOnlySample.ts - Marcar la configuración como de solo lectura para evitar la modificación.
  • getSettingOnlyIfChanged.ts - Obtener 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 una 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 samples de GitHub.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución 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:

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

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

Impresiones