Criar um aplicativo Node.js com o SDK do Azure para JavaScript

Este documento mostra exemplos de como usar o SDK do Azure para JavaScript para acessar chave-valores na Configuração de Aplicativos do Azure.

Dica

A Configuração de Aplicativos oferece uma biblioteca de provedores do JavaScript, que foi criada com base no SDK do JavaScript e projetada para ser mais fácil de usar com recursos mais avançados. Ela permite que os parâmetros de configuração sejam usadas como um objeto Mapa e oferece outros recursos, como composição de configuração de vários rótulos, corte de nome da chave e resolução automática de referências do Key Vault. Acesse o início rápido do JavaScript para saber mais.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa – Crie uma conta gratuitamente
• Um repositório de Configuração de Aplicativos. Criar um repositório.
• Versões LTS do Node.js. Para obter informações sobre como instalar o Node.js diretamente no Windows ou usando o WSL (Subsistema do Windows para Linux), confira Introdução ao Node.js

Criar um valor de chave

Adicione o valor-chave a seguir ao repositório de Configuração de Aplicativos e deixe os campos Rótulo e Tipo de Conteúdo com seus valores padrão. Para mais informações sobre como adicionar valores-chave a um repositório usando o portal do Azure ou a CLI, acesse Criar um valor-chave.

Chave	Valor
TestApp:Settings:Message	Dados da Configuração de Aplicativo do Azure

Como configurar o aplicativo Node.js

1. Neste tutorial, você criará um diretório novo para o projeto chamado app-configuration-example.

   mkdir app-configuration-example
   

2. Mude para o diretório app-configuration-example que foi recém-criado.

   cd app-configuration-example
   

3. Instale a biblioteca de clientes da Configuração de Aplicativos do Azure usando o comando npm install.

   npm install @azure/app-configuration
   

4. Crie um arquivo chamado app-configuration-example.js no diretório app-configuration-example e adicione o seguinte código:

   const { AppConfigurationClient } = require("@azure/app-configuration");
   
   async function run() {
     console.log("Azure App Configuration - JavaScript example");
     // Example code goes here
   }
   
   run().catch(console.error);
   

Observação

Os snippets de código deste exemplo ajudarão você a começar a usar a biblioteca de clientes da Configuração de Aplicativos para JavaScript. Você também deverá considerar usar um tratamento de exceções para o aplicativo de acordo com suas necessidades. Para saber mais sobre o tratamento de exceções, confira nossa documentação do SDK do JavaScript.

Configurar uma cadeia de conexão da Configuração de Aplicativos

1. Defina uma variável de ambiente chamada AZURE_APPCONFIG_CONNECTION_STRING como a cadeia de conexão para seu repositório da Configuração de Aplicativos. Na linha de comando, execute o seguinte comando:

   Prompt de comando do Windows

   Para executar o aplicativo localmente usando o prompt de comando do Windows, execute o seguinte comando e substitua <app-configuration-store-connection-string> pela cadeia de conexão do repositório de configuração do aplicativo:

   setx AZURE_APPCONFIG_CONNECTION_STRING "<app-configuration-store-connection-string>"
   

   PowerShell

   Se você usa o Windows PowerShell, execute o seguinte comando e substitua <app-configuration-store-connection-string> pela cadeia de conexão do repositório de configuração do aplicativo:

   $Env:AZURE_APPCONFIG_CONNECTION_STRING = "<app-configuration-store-connection-string>"
   

   macOS

   Se você usa o macOS, execute o seguinte comando e substitua <app-configuration-store-connection-string> pela cadeia de conexão do repositório de configuração do aplicativo:

   export AZURE_APPCONFIG_CONNECTION_STRING='<app-configuration-store-connection-string>'
   

   Linux

   Se você usa Linux, execute o seguinte comando e substitua <app-configuration-store-connection-string> pela cadeia de conexão do repositório de configuração do aplicativo:

   export AZURE_APPCONFIG_CONNECTION_STRING='<app-configuration-store-connection-string>'
   

2. Imprima o valor da variável de ambiente para confirmar que ela está definida corretamente usando o comando a seguir.

   Prompt de comando do Windows

   Usando o prompt de comando do Windows, reinicie o prompt de comando para permitir que a alteração entre em vigor e execute o seguinte comando:

   echo %AZURE_APPCONFIG_CONNECTION_STRING%
   

   PowerShell

   Se você usa o Windows PowerShell, execute o comando a seguir:

   $Env:AZURE_APPCONFIG_CONNECTION_STRING
   

   macOS

   Se você usar o macOS, execute o seguinte comando:

   echo "$AZURE_APPCONFIG_CONNECTION_STRING"
   

   Linux

   Se você usar o Linux, execute o seguinte comando:

   echo "$AZURE_APPCONFIG_CONNECTION_STRING"
   

Exemplos de código

Os snippets de código de exemplo desta seção mostrarão como executar operações comuns com a biblioteca de clientes da Configuração de Aplicativos para JavaScript. Adicione esses snippets de código ao corpo da função run no arquivo app-configuration-example.js criado anteriormente.

Observação

A biblioteca de clientes da Configuração de Aplicativos se refere a um objeto chave-valor como ConfigurationSetting. Portanto, neste artigo, os pares chave-valor no repositório da Configuração de Aplicativos serão chamadas de Parâmetros de configuração.

Saiba abaixo como:

• Conectar um repositório de Configuração de Aplicativos
• Obter um parâmetro de configuração
• Adicionar um parâmetro de configuração
• Obter uma lista de parâmetros de configuração
• Bloquear um parâmetro de configuração
• Desbloquear um parâmetro de configuração
• Atualizar um parâmetro de configuração
• Excluir um parâmetro de configuração

Conectar um repositório de Configuração de Aplicativos

O snippet de código a seguir criará uma instância do AppConfigurationClient usando a cadeia de conexão armazenada nas variáveis de ambiente.

const connection_string = process.env.AZURE_APPCONFIG_CONNECTION_STRING;
const client = new AppConfigurationClient(connection_string);

Obter um parâmetro de configuração

O snippet de código a seguir recuperará um parâmetro de configuração por nome de key.

    const retrievedConfigSetting = await client.getConfigurationSetting({
        key: "TestApp:Settings:Message"
    });
    console.log("\nRetrieved configuration setting:");
    console.log(`Key: ${retrievedConfigSetting.key}, Value: ${retrievedConfigSetting.value}`);

Adicionar um parâmetro de configuração

O snippet de código a seguir criará um objeto ConfigurationSetting com os campos key e value, bem como invocará o método addConfigurationSetting. Esse método gerará uma exceção caso tente adicionar um parâmetro de configuração que já exista em seu repositório. Caso queira evitar essa exceção, o método setConfigurationSetting pode ser usado como alternativa.

    const configSetting = {
        key:"TestApp:Settings:NewSetting",
        value:"New setting value"
    };
    const addedConfigSetting = await client.addConfigurationSetting(configSetting);
    console.log("\nAdded configuration setting:");
    console.log(`Key: ${addedConfigSetting.key}, Value: ${addedConfigSetting.value}`);

Obter uma lista de parâmetros de configuração

O snippet de código a seguir recuperará uma lista de parâmetros de configuração. Os argumentos keyFilter e labelFilter poderão ser fornecidos para filtrar pares chave-valor com base na key e no label, respectivamente. Para obter mais informações sobre filtragem, confira como consultar parâmetros de configuração.

    const filteredSettingsList = client.listConfigurationSettings({
        keyFilter: "TestApp*"
    });
    console.log("\nRetrieved list of configuration settings:");
    for await (const filteredSetting of filteredSettingsList) {
        console.log(`Key: ${filteredSetting.key}, Value: ${filteredSetting.value}`);
    }

Bloquear um parâmetro de configuração

O status do bloqueio de uma chave-valor na Configuração de Aplicativos será indicado pelo atributo readOnly do objeto ConfigurationSetting. Caso readOnly seja true, a configuração será bloqueada. O método setReadOnly poderá ser invocado com true como o segundo argumento para bloquear o parâmetro de configuração.

    const lockedConfigSetting = await client.setReadOnly(addedConfigSetting, true /** readOnly */);
    console.log(`\nRead-only status for ${lockedConfigSetting.key}: ${lockedConfigSetting.isReadOnly}`);

Desbloquear um parâmetro de configuração

Caso o atributo readOnly do ConfigurationSetting seja false, a configuração será desbloqueada. O método setReadOnly poderá ser invocado com false como o segundo argumento para desbloquear o parâmetro de configuração.

    const unlockedConfigSetting = await client.setReadOnly(lockedConfigSetting, false /** readOnly */);
    console.log(`\nRead-only status for ${unlockedConfigSetting.key}: ${unlockedConfigSetting.isReadOnly}`);

Atualizar um parâmetro de configuração

O método setConfigurationSetting poderá ser usado para atualizar uma configuração existente ou para criar um configuração. O snippet de código a seguir alterará o valor de um parâmetro de configuração existente.

    addedConfigSetting.value = "Value has been updated!";
    const updatedConfigSetting = await client.setConfigurationSetting(addedConfigSetting);
    console.log("\nUpdated configuration setting:");
    console.log(`Key: ${updatedConfigSetting.key}, Value: ${updatedConfigSetting.value}`);

Excluir um parâmetro de configuração

O snippet de código a seguir excluirá um parâmetro de configuração por nome de key.

    const deletedConfigSetting = await client.deleteConfigurationSetting({
        key: "TestApp:Settings:NewSetting"
    });
    console.log("\nDeleted configuration setting:");
    console.log(`Key: ${deletedConfigSetting.key}, Value: ${deletedConfigSetting.value}`);

Executar o aplicativo

Neste exemplo, você criou um aplicativo Node.js que usa uma biblioteca de clientes da Configuração de Aplicativos do Azure para recuperar um parâmetro de configuração criado por meio do portal do Azure, além de adicionar um novo parâmetro, recuperar uma lista de parâmetros existentes, bloquear e desbloquear um parâmetro, atualizar um parâmetro e, por fim, excluir um parâmetro.

Nesse momento, o arquivo app-configuration-example.js deve ter o seguinte código:

const { AppConfigurationClient } = require("@azure/app-configuration");

async function run() {
    console.log("Azure App Configuration - JavaScript example");

    const connection_string = process.env.AZURE_APPCONFIG_CONNECTION_STRING;
    const client = new AppConfigurationClient(connection_string);

    const retrievedConfigSetting = await client.getConfigurationSetting({
        key: "TestApp:Settings:Message"
    });
    console.log("\nRetrieved configuration setting:");
    console.log(`Key: ${retrievedConfigSetting.key}, Value: ${retrievedConfigSetting.value}`);

    const configSetting = {
        key: "TestApp:Settings:NewSetting",
        value: "New setting value"
    };
    const addedConfigSetting = await client.addConfigurationSetting(configSetting);
    console.log("Added configuration setting:");
    console.log(`Key: ${addedConfigSetting.key}, Value: ${addedConfigSetting.value}`);

    const filteredSettingsList = client.listConfigurationSettings({
        keyFilter: "TestApp*"
    });
    console.log("Retrieved list of configuration settings:");
    for await (const filteredSetting of filteredSettingsList) {
        console.log(`Key: ${filteredSetting.key}, Value: ${filteredSetting.value}`);
    }

    const lockedConfigSetting = await client.setReadOnly(addedConfigSetting, true /** readOnly */);
    console.log(`Read-only status for ${lockedConfigSetting.key}: ${lockedConfigSetting.isReadOnly}`);

    const unlockedConfigSetting = await client.setReadOnly(lockedConfigSetting, false /** readOnly */);
    console.log(`Read-only status for ${unlockedConfigSetting.key}: ${unlockedConfigSetting.isReadOnly}`);

    addedConfigSetting.value = "Value has been updated!";
    const updatedConfigSetting = await client.setConfigurationSetting(addedConfigSetting);
    console.log("Updated configuration setting:");
    console.log(`Key: ${updatedConfigSetting.key}, Value: ${updatedConfigSetting.value}`);

    const deletedConfigSetting = await client.deleteConfigurationSetting({
        key: "TestApp:Settings:NewSetting"
    });
    console.log("Deleted configuration setting:");
    console.log(`Key: ${deletedConfigSetting.key}, Value: ${deletedConfigSetting.value}`);
}

run().catch(console.error);

Na janela do console, acesse o diretório que contém o arquivo app-configuration-example.js e execute o seguinte comando para executar o aplicativo:

node app.js

Você deve ver o seguinte resultado:

Azure App Configuration - JavaScript example

Retrieved configuration setting:
Key: TestApp:Settings:Message, Value: Data from Azure App Configuration

Added configuration setting:
Key: TestApp:Settings:NewSetting, Value: New setting value

Retrieved list of configuration settings:
Key: TestApp:Settings:Message, Value: Data from Azure App Configuration
Key: TestApp:Settings:NewSetting, Value: New setting value

Read-only status for TestApp:Settings:NewSetting: true

Read-only status for TestApp:Settings:NewSetting: false

Updated configuration setting:
Key: TestApp:Settings:NewSetting, Value: Value has been updated!

Deleted configuration setting:
Key: TestApp:Settings:NewSetting, Value: Value has been updated!

Limpar os recursos

Se não deseja continuar usando os recursos criados neste artigo, exclua o grupo de recursos que você criou aqui para evitar encargos.

Importante

A exclusão de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos contidos nele são excluídos permanentemente. Não exclua acidentalmente grupo de recursos ou recursos incorretos. Se tiver criado os recursos para este artigo dentro de um grupo de recursos que contém outros recursos que você deseja manter, exclua cada um individualmente do respectivo painel em vez de excluir o grupo de recursos.

1. Entre no portal do Azure e selecione Grupos de recursos.
2. Na caixa Filtrar por nome..., digite o nome do seu grupo de recursos.
3. Na lista de resultados, selecione o nome do grupo de recursos para conferir uma visão geral.
4. Selecione Excluir grupo de recursos.
5. Você receberá uma solicitação para confirmar a exclusão do grupo de recursos. Insira o nome do grupo de recursos para confirmar e selecione Excluir.

Após alguns instantes, o grupo de recursos e todos os recursos dele são excluídos.

Próximas etapas

Este guia mostrou como usar o SDK do Azure para JavaScript para acessar chave-valores na Configuração de Aplicativos do Azure.

Para obter códigos de exemplo adicionais, visite:

Exemplos de biblioteca de clientes da Configuração de Aplicativos do Azure

Para saber como usar a Configuração de Aplicativos do Azure com aplicativos JavaScript, acesse:

Criar um aplicativo JavaScript com a Configuração de Aplicativos do Azure