Share via

Usar o tipo de conteúdo para armazenar valores de chave JSON na Configuração do Aplicativo

  • Artigo

Os dados são armazenados na Configuração do Aplicativo como valores-chave, onde os valores são tratados como o tipo de cadeia de caracteres por padrão. No entanto, você pode especificar um tipo personalizado usando a propriedade de tipo de conteúdo associada a cada valor-chave. Esse processo preserva o tipo original de seus dados ou faz com que seu aplicativo se comporte de forma diferente com base no tipo de conteúdo.

Descrição geral

Na Configuração do aplicativo, você pode usar o tipo de mídia JSON como o tipo de conteúdo de seus valores-chave para aproveitar os seguintes benefícios:

  • Gerenciamento de dados mais simples: gerenciar valores-chave, como matrizes, se tornará muito mais fácil no portal do Azure.
  • Exportação de dados aprimorada: tipos primitivos, matrizes e objetos JSON serão preservados durante a exportação de dados.
  • Suporte nativo com o provedor de Configuração de Aplicativo: os valores-chave com tipo de conteúdo JSON funcionarão bem quando consumidos pelas bibliotecas do provedor de Configuração de Aplicativo em seus aplicativos.

Tipo de conteúdo JSON válido

Os tipos de mídia, conforme definido aqui, podem ser atribuídos ao tipo de conteúdo associado a cada valor-chave. Um tipo de mídia consiste em um tipo e um subtipo. Se o tipo for e o subtipo (ou sufixo) for applicationjson, o tipo de mídia será considerado um tipo de conteúdo JSON válido. Alguns exemplos de tipos de conteúdo JSON válidos são:

  • application/json
  • application/activity+json
  • application/vnd.foobar+json;charset=utf-8

Valores JSON válidos

Quando um valor-chave tem um tipo de conteúdo JSON, seu valor deve estar no formato JSON válido para que os clientes o processem corretamente. Caso contrário, os clientes podem falhar ou voltar atrás e tratá-lo como formato de cadeia de caracteres. Alguns exemplos de valores JSON válidos são:

  • "John Doe"
  • 723
  • false
  • null
  • "2020-01-01T12:34:56.789Z"
  • [1, 2, 3, 4]
  • {"ObjectSetting":{"Targeting":{"Default":true,"Level":"Information"}}}

Nota

Para o restante deste artigo, qualquer valor-chave na Configuração do Aplicativo que tenha um tipo de conteúdo JSON válido e um valor JSON válido será referido como valor-chave JSON.

Neste tutorial, irá aprender a:

  • Crie valores-chave JSON na Configuração do aplicativo.
  • Importe valores-chave JSON de um arquivo JSON.
  • Exporte valores-chave JSON para um arquivo JSON.
  • Consuma valores-chave JSON em seus aplicativos.

Se não tiver uma subscrição do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

  • Uma loja de configuração de aplicativos. Crie uma loja.
  • Este tutorial requer a versão 2.10.0 ou posterior da CLI do Azure. Se estiver usando o Azure Cloud Shell, a versão mais recente já está instalada.

Criar valores-chave JSON na Configuração do Aplicativo

Os valores-chave JSON podem ser criados usando o portal do Azure, a CLI do Azure ou importando de um arquivo JSON. Nesta seção, você encontrará instruções sobre como criar os mesmos valores-chave JSON usando os três métodos.

Criar valores-chave JSON usando o portal do Azure

Adicione os seguintes valores-chave à App Configuration store. Deixe Label com seu valor padrão. Para obter mais informações sobre como adicionar valores-chave a uma loja usando o portal do Azure ou a CLI, vá para Criar um valor-chave.

Key valor Tipo de Conteúdo
Configurações:BackgroundColor "Verde" Aplicação/JSON
Configurações:FontSize 24 Aplicação/JSON
Configurações:UseDefaultRouting falso Aplicação/JSON
Configurações:Usuários bloqueados nulo Aplicação/JSON
Configurações:ReleaseDate "2020-08-04T12:34:56.789Z" Aplicação/JSON
Configurações:RolloutPercentage [25,50,75,100] Aplicação/JSON
Configurações:Registro em log {"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}} Aplicação/JSON
  1. Selecione Aplicar.

Criar valores-chave JSON usando a CLI do Azure

Os comandos a seguir criarão valores-chave JSON em sua loja de configuração de aplicativos. Substitua <appconfig_name> pelo nome da sua loja de configuração de aplicativos.

appConfigName=<appconfig_name>
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:BackgroundColor --value \"Green\"
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:FontSize --value 24
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:UseDefaultRouting --value false
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:BlockedUsers --value null
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:ReleaseDate --value \"2020-08-04T12:34:56.789Z\"
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:RolloutPercentage --value [25,50,75,100]
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:Logging --value {\"Test\":{\"Level\":\"Debug\"},\"Prod\":{\"Level\":\"Warning\"}}

Importante

Se você estiver usando a CLI do Azure ou o Azure Cloud Shell para criar valores-chave JSON, o valor fornecido deverá ser uma cadeia de caracteres JSON com escape.

Importar valores de chave JSON de um arquivo

Crie um arquivo JSON chamado Import.json com o seguinte conteúdo e importe-o como valores-chave para a Configuração do aplicativo:

{
  "Settings": {
    "BackgroundColor": "Green",
    "BlockedUsers": null,
    "FontSize": 24,
    "Logging": {"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}},
    "ReleaseDate": "2020-08-04T12:34:56.789Z",
    "RolloutPercentage": [25,50,75,100],
    "UseDefaultRouting": false
  }
}

az appconfig kv import -s file --format json --path "~/Import.json" --content-type "application/json" --separator : --depth 2

Nota

O --depth argumento é usado para nivelar dados hierárquicos de um arquivo em valores-chave. Neste tutorial, a profundidade é especificada para demonstrar que você também pode armazenar objetos JSON como valores na Configuração do aplicativo. Se a profundidade não for especificada, os objetos JSON serão nivelados para o nível mais profundo por padrão.

Os valores-chave JSON criados devem ter esta aparência na Configuração do aplicativo:

Screenshot that shows the Config store containing JSON key-values.

Para verificar isso, abra seu recurso de Configuração de Aplicativo no portal do Azure e vá para Gerenciador de configuração.

Exportar valores-chave JSON para um arquivo

Um dos principais benefícios do uso de valores-chave JSON é a capacidade de preservar o tipo de dados original de seus valores durante a exportação. Se um valor-chave na Configuração do Aplicativo não tiver o tipo de conteúdo JSON, seu valor será tratado como uma cadeia de caracteres.

Considere estes valores-chave sem o tipo de conteúdo JSON:

Key valor Tipo de Conteúdo
Configurações:FontSize 24
Configurações:UseDefaultRouting false

Quando você exporta esses valores-chave para um arquivo JSON, os valores serão exportados como cadeias de caracteres:

{
  "Settings": {
    "FontSize": "24",
    "UseDefaultRouting": "false"
  }
}

No entanto, quando você exporta valores-chave JSON para um arquivo, todos os valores preservarão seu tipo de dados original. Para verificar esse processo, exporte valores-chave da Configuração do Aplicativo para um arquivo JSON. Você verá que o arquivo exportado tem o mesmo conteúdo do Import.json arquivo importado anteriormente.

az appconfig kv export -d file --format json --path "~/Export.json" --separator :

Nota

Se a sua loja de configuração de aplicativos tiver alguns valores-chave sem o tipo de conteúdo JSON, eles também serão exportados para o mesmo arquivo no formato de cadeia de caracteres.

Consumindo valores-chave JSON em aplicativos

A maneira mais fácil de consumir valores de chave JSON em seu aplicativo é por meio de bibliotecas do provedor de Configuração de Aplicativo. Com as bibliotecas do provedor, você não precisa implementar manipulação especial de valores-chave JSON em seu aplicativo. Eles serão analisados e convertidos para corresponder à configuração nativa do seu aplicativo.

Por exemplo, se você tiver o seguinte valor-chave na Configuração do aplicativo:

Key valor Tipo de Conteúdo
Definições {"FontSize":24,"UseDefaultRouting":false} application/json

Sua configuração de aplicativo .NET terá os seguintes valores-chave:

Key valor
Configurações:FontSize 24
Configurações:UseDefaultRouting false

Você pode acessar as novas chaves diretamente ou pode optar por vincular valores de configuração a instâncias de objetos .NET.

Importante

O suporte nativo para valores de chave JSON está disponível no provedor de configuração .NET versão 4.0.0 (ou posterior). Para obter mais informações, vá para a seção Próximas etapas .

Se você estiver usando o SDK ou a API REST para ler valores-chave da Configuração do aplicativo, com base no tipo de conteúdo, seu aplicativo será responsável por analisar o valor de um valor-chave JSON.

Clean up resources (Limpar recursos)

Se não quiser continuar a utilizar os recursos criados neste artigo, elimine o grupo de recursos que criou aqui para evitar cobranças.

Importante

A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são excluídos permanentemente. Certifique-se de não excluir acidentalmente o grupo de recursos ou recursos errados. Se você criou os recursos para este artigo dentro de um grupo de recursos que contém outros recursos que deseja manter, exclua cada recurso individualmente de seu respetivo 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, introduza o nome do seu grupo de recursos.
  3. Na lista de resultados, selecione o nome do grupo de recursos para ver uma visão geral.
  4. Selecione Eliminar grupo de recursos.
  5. É-lhe pedido que confirme a eliminação do grupo de recursos. Insira o nome do grupo de recursos a ser confirmado e selecione Excluir.

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

Próximos passos

Agora que você sabe como trabalhar com valores-chave JSON em sua loja de configuração de aplicativos, crie um aplicativo para consumir esses valores-chave:

Guia de início rápido do ASP.NET Core

Início rápido do .NET Core