Suporte à Configuração de Aplicativos do Azure para arquivos de configuração

Uma maneira comum de armazenar dados de configuração é usar arquivos. Se você quiser usar a Configuração de Aplicativos do Azure para gerenciar seus dados de configuração, mas usar arquivos no momento, não precisará inserir seus dados manualmente. Você pode usar ferramentas para importar seus arquivos de configuração.

Se você planeja gerenciar seus dados na Configuração de Aplicativos, a operação de importação será uma migração de dados única. Outra opção é continuar gerenciando seus dados de configuração em arquivos e importar os arquivos recorrentemente como parte do processo de CI/CD (integração contínua e entrega contínua). Esse caso aparece quando você adota a configuração como código.

Dois perfis de conteúdo de arquivo estão disponíveis quando você usa arquivos de configuração:

• O perfil de conteúdo de arquivo padrão: o esquema de arquivo de configuração convencional
• O perfil de conteúdo do arquivo KVSet: um esquema que contém todas as propriedades chave-valor da Configuração de Aplicativo

Este artigo discute os dois perfis de conteúdo de arquivo. Ele também fornece exemplos de importação e exportação de arquivos de configuração. Os exemplos usam a CLI do Azure, mas os conceitos neste artigo também se aplicam a outros métodos de importação de Configuração de Aplicativo.

Perfil do conteúdo do arquivo: padrão

Nas ferramentas de Configuração de Aplicativo, o perfil de conteúdo de arquivo padrão é o esquema de arquivo de configuração convencional amplamente adotado por estruturas e sistemas de programação existentes. Esse perfil é usado em ferramentas de importação da Configuração de Aplicativo, como o portal do Azure, a CLI do Azure, a tarefa de Importação de Configuração de Aplicativo do Azure no Azure Pipelines e o GitHub Actions. A Configuração de Aplicativo dá suporte a formatos de arquivo JSON, YAML e Properties.

Esse perfil será útil se você quiser usar um arquivo como a configuração de fallback para seu aplicativo ou a configuração local durante o desenvolvimento. Ao importar o arquivo de configuração, especifique como deseja que os dados sejam transformados em valores de chave e sinalizadores de recursos da Configuração de Aplicativo.

O arquivo de configuração a seguir,appsettings.json, fornece um exemplo do perfil de conteúdo de arquivo padrão. Esse arquivo contém uma configuração e um sinalizador de recurso.

{
    "Logging": {
        "LogLevel": {
            "Default": "Warning"
        }
    },
    "feature_management": {
        "feature_flags": [
            {
                "id": "Beta",
                "enabled": false
            }
        ]
    }
}

Para importar esse arquivo para a Configuração de Aplicativos, execute o seguinte comando da CLI do Azure. Aplica um rótulo dev à configuração e ao sinalizador de recurso e usa dois-pontos (:) como separador para nivelar o nome da chave.

az appconfig kv import --label dev --separator : --name <App-Configuration-store-name> --source file --path appsettings.json --format json

Opcionalmente, você pode adicionar o seguinte parâmetro ao comando anterior: --profile appconfig/default. O parâmetro é opcional, pois o perfil padrão é appconfig/default.

As referências do Azure Key Vault exigem um tipo de conteúdo específico durante a importação. Como resultado, você os mantém em um arquivo separado, conforme mostrado no arquivo a seguir, keyvault-refs.json:

{
    "Database:ConnectionString": {
        "uri": "https://<Key-Vault-name>.vault.azure.net/secrets/db-secret"
    }  
}

Para importar esse arquivo, execute o seguinte comando da CLI do Azure. Ele aplica um test rótulo à referência do Key Vault e usa o tipo de conteúdo de referência do Key Vault.

az appconfig kv import --label test --content-type "application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8" --name <App-Configuration-store-name> --source file --path keyvault-refs.json --format json

A tabela a seguir mostra todos os dados importados no repositório de Configuração de Aplicativos:

Perfil do conteúdo do arquivo: KVSet

Nas ferramentas de Configuração de Aplicativo, o perfil de conteúdo do arquivo KVSet é um esquema de arquivo que contém todas as propriedades de um valor-chave da Configuração de Aplicativo. Incluem-se o nome da chave, seu valor, seu rótulo, seu tipo de conteúdo e suas marcas. Como todas as propriedades de um valor-chave estão no arquivo, você não precisa especificar regras de transformação ao importar o arquivo.

Ao usar o perfil KVSet, você pode definir valores de chave regulares, referências do Key Vault e sinalizadores de recursos em um arquivo. Como resultado, esse perfil será útil se você quiser gerenciar todos os dados da Configuração de Aplicativos em um arquivo e importá-los em uma etapa.

Os arquivos que usam esse perfil estão no formato JSON. Para obter a especificação do esquema, consulte o esquema de arquivo KVSet.

O seguinte arquivo, appconfigdata.json, é baseado no perfil de conteúdo do arquivo KVSet. Esse arquivo contém um sinalizador de recurso, uma referência do Key Vault e um valor-chave padrão.

{
  "items": [
    {
      "key": ".appconfig.featureflag/Beta",
      "value": "{\"id\":\"Beta\",\"description\":\"Beta feature\",\"enabled\":true,\"conditions\":{\"client_filters\":[]}}",
      "label": "dev",
      "content_type": "application/vnd.microsoft.appconfig.ff+json;charset=utf-8",
      "tags": {}
    },
    {
      "key": "Database:ConnectionString",
      "value": "{\"uri\":\"https://<Key-Vault-name>.vault.azure.net/secrets/db-secret\"}",
      "label": "test",
      "content_type": "application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8",
      "tags": {}
    },
    {
      "key": "Logging:LogLevel:Default",
      "value": "Debug",
      "label": "dev",
      "content_type": null,
      "tags": {}
    }
  ]
}

Na seção anterior, um exemplo mostra como importar dados para o repositório de Configuração de Aplicativos. Você pode exportar esses dados para um arquivo usando o seguinte comando da CLI do Azure:

az appconfig kv export --profile appconfig/kvset --label * --name <App-Configuration-store-name> --destination file --path appconfigdata.json --format json 

Depois de exportar o arquivo, abra-o em um editor de texto e faça as seguintes alterações:

• Defina a propriedade Beta do sinalizador de recurso enabled como true.
• Defina a propriedade Logging:LogLevel:Default como Debug.

Para importar o arquivo atualizado para o repositório de Configuração de Aplicativos, execute o seguinte comando da CLI, que inclui o --profile appconfig/kvset parâmetro. Você não precisa especificar regras de transformação de dados, como um separador, rótulo ou tipo de conteúdo, como você fez para o perfil de conteúdo de arquivo padrão. Todas as informações necessárias já estão no arquivo.

az appconfig kv import --profile appconfig/kvset --name <App-Configuration-store-name> --source file --path appconfigdata.json --format json

A tabela a seguir mostra todos os dados importados no repositório de Configuração de Aplicativos:

Próximas etapas