Biblioteca de cliente de Configuração de Aplicativo do Azure para JavaScript - versão 1.10.0

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.

Ligações principais:

• Código fonte
• Pacote (NPM)
• Documentação de referência da API
• Documentação do produto
• Amostras

Escolha o pacote certo

Use @azure/app-configuration (esta biblioteca) para:

• Gerenciar definições de configuração e instantâneos na Configuração do Aplicativo do Azure
• Executar leituras granulares que operam fora do âmbito do consumo normal de configuração

A maioria dos aplicativos deve começar com a biblioteca @azure/app-configuration-provider , que se baseia nessa biblioteca de cliente de baixo nível e é a maneira recomendada de consumir a configuração em tempo de execução. E acrescenta:

• Padrões de acesso flexíveis usando a configuração como um mapa de chave/valor ou um objeto JSON estruturado
• Mecanismo de consulta para compor declarativamente a configuração do aplicativo
• Atualização de configuração durante o tempo de execução
• Alta confiabilidade com cache, deteção de réplicas, failover e balanceamento de carga
• Resolução de referência do cofre de chaves e atualização automática
• Integração de sinalizadores de recursos para biblioteca de gerenciamento de @microsoft/recursos

Para obter mais informações, vá para Visão geral do provedor de configuração.

Primeiros passos

Instalar o pacote

npm install @azure/app-configuration

Observação: Para aplicativos que só precisam ler valores de configuração, sugerimos usar a biblioteca @azure/app-configuration-provider .

Ambientes atualmente suportados

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

Consulte a nossa 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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

Nuvens soberanas

Para autenticar com um recurso em uma nuvem soberana, você precisará definir as audienceAppConfigurationClient opções no construtor.

import { AppConfigurationClient, KnownAppConfigAudience } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(endpoint, new DefaultAzureCredential(), {
  audience: KnownAppConfigAudience.AzureChina,
});

Observação: quando audience a propriedade não estiver definida, o SDK assumirá como padrão a Nuvem Pública do Azure.

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:

import { AppConfigurationClient } from "@azure/app-configuration";

const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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:

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

Observação: Se seu aplicativo só precisa recuperar valores de configuração e não requer a execução de operações de criação, atualização ou exclusão em definições de configuração, considere usar a biblioteca @azure/app-configuration-provider . A biblioteca do provedor oferece uma experiência simplificada para carregar dados de configuração em tempo de execução e recursos adicionais. Você pode encontrar muitos exemplos de código na documentação de Configuração do Aplicativo do Azure no Microsoft Learn.

Criar e obter uma configuração

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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.
  // https://learn.microsoft.com/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);

Criar um instantâneo

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

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

Obter um instantâneo

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

Listar os ConfigurationSetting no instantâneo

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const snapshots = await client.listSnapshots();

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

Recupere e arquive o snapshot

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

// 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:

import { setLogLevel } from "@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:

1. pnpm install
2. pnpm build --filter @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.

Veja nossa pasta testes para obter mais detalhes.

Projetos relacionados

• SDK do Microsoft Azure para JavaScript
• Configuração do Aplicativo do Azure