Compartilhar via

Biblioteca de clientes da Configuração de Aplicativo para JavaScript

  • Artigo

a 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 clientes para a Configuração de Aplicativos para:

  • Criar representações e mapeamentos de chave flexíveis
  • Teclas de marca com rótulos
  • Configurações de reprodução de qualquer ponto no tempo
  • Gerenciar instantâneos da configuração de um aplicativo

Links de chave:

Introdução

Instalar o pacote

npm install @azure/app-configuration

Ambientes com suporte no momento

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

  • Uma assinatura do Azure
  • Um recurso de Configuração de Aplicativo

Criar um recurso de Configuração de Aplicativo

Você pode usar a do Portal do Azure ou a CLI do Azure para criar um recurso de Configuração de 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 uma entidade de serviço ou usando uma cadeia de conexão .

Autenticação com uma entidade de serviço

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

  • Criando uma credencial usando o pacote @azure/identity.
  • Definindo 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 de Nuvem Soberana, 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

Autenticação com uma cadeia de conexão

Para obter a cadeia de conexão de primária 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]"

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

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

Principais conceitos

O AppConfigurationClient tem algumas alterações de terminologia da Configuração de Aplicativos no portal.

  • Pares chave/valor são representados como objetos ConfigurationSetting
  • O bloqueio e o desbloqueio de uma configuração são representados no campo isReadOnly, que você pode alternar usando setReadOnly.
  • Instantâneos são representados como objetos ConfigurationSnapshot.

O cliente segue uma metodologia de design simples – ConfigurationSetting pode ser passado para qualquer método que usa 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 dá suporte a instantâneos de configuração: cópias pontuais e imutáveis de um repositório de configuração. Instantâneos podem ser criados com filtros que determinam quais pares chave-valor estão contidos no instantâneo, criando uma exibição imutável e composta do repositório de configuração. Esse recurso permite que os aplicativos mantenham uma exibição consistente da configuração, garantindo que não haja incompatibilidades de versão nas configurações individuais devido à leitura à medida que as atualizações foram feitas. Por exemplo, esse recurso pode ser usado para criar "instantâneos de configuração de versão" em 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 fornece o sondador para sondar 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 conclusão da sondagem.

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 o 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}`);
}

Recuperar e arquivar o instantâneo

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

Solucionando problemas

Log

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 runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

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

Suporte do React Native

O React Native não dá suporte a alguma API JavaScript usada por essa biblioteca do SDK, portanto, você precisa fornecer polyfills para eles. Confira nosso exemplo do React Native com o Expo para obter mais detalhes.

Próximas etapas

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

  • 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 versus produção.
  • optimisticConcurrencyViaEtag.ts – Defina valores usando etags para evitar substituições acidentais.
  • setReadOnlySample.ts - Marcando as configurações como somente leitura para impedir a modificação.
  • getSettingOnlyIfChanged.ts - Obtenha uma configuração somente se ela tiver sido alterada da última vez que você a tiver.
  • listRevisions.ts - Listar as revisões de uma chave, permitindo que você veja os valores anteriores e quando eles foram definidos.
  • secretReference.ts – SecretReference representa uma configuração que faz referência como segredo KeyVault.
  • snapshot.ts – Criar, listar configurações e arquivar instantâneos.
  • featureFlag.ts - Sinalizadores de recurso são configurações que seguem um esquema JSON específico para o valor.

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

Contribuindo

Se você quiser contribuir com essa 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 dinâmicos 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:

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

Exiba nossos testes de pasta para obter mais detalhes.

impressões