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

Os dados são armazenados na Configuração de Aplicativos como valores-chave, em que 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 chave-valor. 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.

Visão geral

Na Configuração de Aplicativos, 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: o gerenciamento de 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 Aplicativos: os valores-chave com tipo de conteúdo JSON funcionarão bem quando consumidos pelas bibliotecas do provedor de Configuração de Aplicativos 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 chave-valor. Um tipo de mídia consiste em um tipo e um subtipo. Se o tipo for application e o subtipo (ou sufixo) for json, 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 os clientes processá-lo corretamente. Caso contrário, os clientes poderão encontrar falhas ou executar fallback e tratá-lo como um 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"}}}

Observação

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

Neste tutorial, você aprenderá a:

• Crie valores de chave JSON na Configuração do Aplicativo.
• Importe valores de chave JSON de um arquivo JSON.
• Exportar valores de chave JSON para um arquivo JSON.
• Consumir pares chave-valor JSON em seus aplicativos.

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

Pré-requisitos

• Utilize o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Introdução ao Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Se você estiver executando no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se você estiver usando uma instalação local, entre na CLI do Azure usando o comando az login . Para concluir o processo de autenticação, siga as etapas exibidas em seu terminal. Para obter outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar e gerenciar extensões com a CLI do Azure.

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

• Um repositório de Configuração de Aplicativos, conforme mostrado no tutorial para criar um repositório.
• 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 de chave JSON na Configuração de Aplicativos

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

Criar valores de chave JSON usando o portal do Azure

Adicione os seguintes valores-chave ao repositório de Configuração do Aplicativos. Deixe o Rótulo com seu valor 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	Tipo de conteúdo
Settings:BackgroundColor	"Verde"	application/json
Configurações:FontSize	24	application/json
Configurações:UsarRoteamentoPadrão	falso	application/json
Settings:BlockedUsers	zero	application/json
Settings:ReleaseDate	"2020-08-04T12:34:56.789Z"	application/json
Settings:RolloutPercentage	[25,50,75,100]	application/json
Configurações:Registro	{"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}}	application/json

1. Selecione Aplicar.

Criar valores de chave JSON usando a CLI do Azure

Os comandos a seguir criarão valores de chave JSON em seu repositório de Configuração de Aplicativos. Substitua <appconfig_name> pelo nome do repositório 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 de 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 chave-valores para a Configuração de Aplicativos:

{
  "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

Observação

O --depth argumento é usado para achatar 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 de Aplicativos. Se a profundidade não for especificada, os objetos JSON serão achatados para o nível mais profundo por padrão.

Os valores de chave JSON que você criou devem ser semelhantes a este na Configuração de Aplicativos:

Para verificar isso, abra o recurso configuração de aplicativo no portal do Azure e vá para o Configuration Explorer.

Exportar valores de 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 de Aplicativo não tiver tipo de conteúdo JSON, seu valor será tratado como uma cadeia de caracteres.

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

Chave	Valor	Tipo de conteúdo
Settings:FontSize	24
Configurações:UsarRoteamentoPadrão	falso

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 de chave JSON para um arquivo, todos os valores preservarão seu tipo de dados original. Para verificar esse processo, exporte valores-chave de sua Configuração de 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 :

Observação

Se o repositório de Configuração de Aplicativos tiver alguns valores-chave sem tipo de conteúdo JSON, eles também serão exportados para o mesmo arquivo no formato de cadeia de caracteres.

Consumindo valores de 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 Aplicativos. Com as bibliotecas de provedor, você não precisa implementar o tratamento especial de valores de 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 de Aplicativos:

Chave	Valor	Tipo de conteúdo
Configurações	{"FontSize":24,"UseDefaultRouting":false}	aplicativo/json

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

Chave	Valor
Settings:FontSize	24
Configurações:UsarRoteamentoPadrão	falso

Você pode acessar as novas chaves diretamente ou pode optar por associar 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 do .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 de Aplicativos, com base no tipo de conteúdo, seu aplicativo será responsável por analisar o valor de um valor de chave JSON.

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. Certifique-se de não excluir o grupo de recursos ou os recursos incorretos acidentalmente. 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

Agora que você sabe como trabalhar com valores de chave JSON no repositório de Configuração de Aplicativos, crie um aplicativo para consumir esses valores de chave:

Início rápido do ASP.NET Core

Início rápido do .NET Core