Biblioteca de cliente de configuração de aplicativo para JavaScript

Artigo
07/17/2024

de Configuração de Aplicativos do Azure é um serviço gerenciado que ajuda os desenvolvedores a centralizar suas configurações de aplicativos e recursos de forma simples e segura.

Use a biblioteca de cliente para Configuração de Aplicativo para:

Crie representações e mapeamentos de chaves flexíveis
Teclas de etiqueta com etiquetas
Reproduzir configurações a partir de qualquer ponto no tempo
Gerenciar instantâneos da configuração de um aplicativo

Ligações principais:

Primeiros passos

Instalar o pacote

npm install @azure/app-configuration

Ambientes atualmente suportados

versões LTS do Node.js
Versões mais recentes do Safari, Chrome, Edge e Firefox.

Consulte o nosso de política de suporte para obter mais detalhes.

Pré-requisitos

Um de Subscrição do Azure
Um recurso de de configuração de aplicativo

Criar um recurso de Configuração de Aplicativo

Você pode usar o do Portal do Azure ou o da CLI do Azure para criar um recurso de Configuração do Aplicativo do Azure.

Exemplo (CLI do Azure):

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

Autenticar o cliente

AppConfigurationClient pode autenticar usando um principal de serviço ou usando uma cadeia de conexão .

Autenticação com uma entidade de serviço

A autenticação via entidade de serviço é feita por:

Criação de uma credencial usando o pacote @azure/identity.
Definir regras RBAC apropriadas em seu recurso AppConfiguration. Mais informações sobre as funções de Configuração de Aplicativo podem ser encontradas aqui.

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

Mais informações sobre @azure/identity podem ser encontradas aqui

Nuvens soberanas

Para autenticar com um recurso em um Sovereign Cloud, você precisará definir o authorityHost nas opções de credencial ou por meio da variável de ambiente 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 })
);

Mais informações sobre @azure/identity podem ser encontradas aqui

Autenticando com uma cadeia de conexão

Para obter o de cadeia de conexão Primary para um recurso de Configuração de Aplicativo, você pode usar este comando da CLI do Azure:

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

E no código, agora você pode criar seu cliente de Configuração de Aplicativo com a cadeia de conexão obtida da CLI do Azure:

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

Conceitos-chave

O AppConfigurationClient tem algumas alterações terminológicas da Configuração do Aplicativo no portal.

Os pares chave/valor são representados como objetos ConfigurationSetting
Bloquear e desbloquear uma configuração é representado no campo isReadOnly, que você pode alternar usando setReadOnly.
Os instantâneos são representados como objetos ConfigurationSnapshot.

O cliente segue uma metodologia de design simples - ConfigurationSetting pode ser passada para qualquer método que leve um ConfigurationSettingParam ou ConfigurationSettingId.

Isso significa que esse padrão 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);

ou, por exemplo, obter novamente uma configuração:

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

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

A versão da API 2022-11-01-preview suporta instantâneos de configuração: cópias point-in-time imutáveis de um repositório de configuração. Os snapshots podem ser criados com filtros que determinam quais pares chave-valor estão contidos no snapshot, criando uma exibição composta e imutável do repositório de configuração. Esse recurso permite que os aplicativos mantenham uma visão consistente da configuração, garantindo que não haja incompatibilidades de versão para configurações individuais devido à leitura à medida que as atualizações são feitas. Por exemplo, esse recurso pode ser usado para criar "instantâneos de configuração de versão" dentro de uma Configuração de Aplicativo. Consulte o criar e obter um instantâneo seção no exemplo abaixo.

Exemplos

Criar e obter uma configuração

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

Criar um instantâneo

beginCreateSnapshot dá-lhe o poller para sondar para a criação do instantâneo.

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

Você também pode usar beginCreateSnapshotAndWait para ter o resultado da criação diretamente após a sondagem ser feita.

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

Obter um instantâneo

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

Listar os `ConfigurationSetting` no instantâneo

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

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

Listar todos os instantâneos do serviço

const snapshots = await client.listSnapshots();

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

Recupere e arquive o snapshot

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

Solução de problemas

Registo

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode consultar os documentos do pacote @azure/logger.

Suporte React Native

O React Native não suporta algumas APIs JavaScript usadas por esta biblioteca SDK, portanto, você precisa fornecer polipreenchimentos para eles. Consulte a nossa amostra React Native com a Expo para obter mais detalhes.

Próximos passos

Os exemplos a seguir mostram as várias maneiras de interagir com a Configuração do aplicativo:

helloworld.ts - Obter, definir e excluir valores de configuração.
helloworldWithLabels.ts - Use rótulos para adicionar dimensões adicionais às suas configurações para cenários como beta vs produção.
optimisticConcurrencyViaEtag.ts - Defina valores usando etags para evitar substituições acidentais.
setReadOnlySample.ts - Marcar as configurações como somente leitura para evitar modificações.
getSettingOnlyIfChanged.ts - Obtenha uma configuração somente se ela tiver sido alterada da última vez que você a recebeu.
listRevisions.ts - Liste as revisões de uma chave, permitindo que você veja os valores anteriores e quando eles foram definidos.
secretReference.ts - SecretReference representa uma definição de configuração que faz referência como segredo KeyVault.
snapshot.ts - Crie, liste definições de configuração e arquive instantâneos.
featureFlag.ts - Os sinalizadores de recursos são configurações que seguem um esquema JSON específico para o valor.

Exemplos mais detalhados podem ser encontrados na pasta exemplos de no GitHub.

Contribuição

Se você quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Os testes deste módulo são uma mistura de testes ao vivo e de unidade, que exigem que você tenha uma instância de Configuração de Aplicativo do Azure. Para executar os testes, você precisará executar:

rush update
rush build -t @azure/app-configuration
Crie um arquivo .env com este conteúdo na pasta sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Veja nossa pasta testes para obter mais detalhes.

SDK do Microsoft Azure para JavaScript
de Configuração de Aplicativos do Azure

Impressões

Partilhar via

Biblioteca de cliente de configuração de aplicativo para JavaScript

Primeiros passos

Instalar o pacote

Ambientes atualmente suportados

Pré-requisitos

Criar um recurso de Configuração de Aplicativo

Autenticar o cliente

Autenticação com uma entidade de serviço

Nuvens soberanas

Autenticando com uma cadeia de conexão

Conceitos-chave

Exemplos

Criar e obter uma configuração

Criar um instantâneo

Obter um instantâneo

Listar os `ConfigurationSetting` no instantâneo

Listar todos os instantâneos do serviço

Recupere e arquive o snapshot

Solução de problemas

Registo

Suporte React Native

Próximos passos

Contribuição

Recursos adicionais

Partilhar via

Biblioteca de cliente de configuração de aplicativo para JavaScript

Primeiros passos

Instalar o pacote

Ambientes atualmente suportados

Pré-requisitos

Criar um recurso de Configuração de Aplicativo

Autenticar o cliente

Autenticação com uma entidade de serviço

Nuvens soberanas

Autenticando com uma cadeia de conexão

Conceitos-chave

Exemplos

Criar e obter uma configuração

Criar um instantâneo

Obter um instantâneo

Listar os ConfigurationSetting no instantâneo

Listar todos os instantâneos do serviço

Recupere e arquive o snapshot

Solução de problemas

Registo

Suporte React Native

Próximos passos

Contribuição

Projetos relacionados

Recursos adicionais

Listar os `ConfigurationSetting` no instantâneo