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 pares chave-valor, em que os valores são tratados por padrão como um tipo de cadeia de caracteres. 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 dos dados ou faz com que o aplicativo se comporte de modo diferente com base no tipo de conteúdo.

Visão geral

Na Configuração de Aplicativos, é possível usar o tipo de mídia JSON como o tipo de conteúdo dos pares chave-valor para obter os seguintes benefícios:

• Gerenciamento de dados simplificado: o gerenciamento de pares chave-valor, 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 provedor da Configuração de Aplicativos: pares chave-valor com um tipo de conteúdo JSON funcionam bem quando consumidos por bibliotecas de provedores da Configuração de Aplicativos nos aplicativos.

Tipo de conteúdo JSON válido

Os tipos de mídia, definidos aqui, podem ser atribuídos ao tipo de conteúdo associado a cada chave-valor. Um tipo de mídia equivale a um tipo e um subtipo. Caso o tipo seja application e o subtipo (ou sufixo) seja 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 par chave-valor tem um tipo de conteúdo JSON, o respetivo valor precisa estar em um formato JSON válido para que os clientes possam 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"}}}

Neste tutorial, você aprenderá a:

Caso você não tenha uma assinatura 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, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções 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 estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com 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 extensões com a CLI do Azure.

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

• Um repositório de Configuração de Aplicativos. Criar um repositório.
• Este tutorial exige obter a CLI do Azure versão 2.10.0 ou posterior. Se você está usando o Azure Cloud Shell, a versão mais recente já está instalada.

Criar pares chave-valor JSON na Configuração de Aplicativos

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

Criar pares chave-valor JSON usando o portal do Azure

Adicione os seguintes valores-chave ao repositório de Configuração do Aplicativos. Deixe Rótulo com seu valor padrão. Para obter 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.

1. Escolha Aplicar.

Criar pares chave-valor JSON usando a CLI do Azure

Os comandos a seguir criarão pares chave-valor JSON em seu repositório da Configuração de Aplicativos. Substitua <appconfig_name> pelo nome do repositório da 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\"}}

Importar pares chave-valor JSON de um arquivo

Crie um arquivo JSON chamado Import.json com o seguinte conteúdo, depois importe-o como pares chave-valor na 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

Os pares chave-valor JSON criados deverão ter a seguinte aparência na Configuração de Aplicativos:

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

Exportar pares chave-valor JSON para um arquivo

Um dos principais benefícios de usar pares chave-valor JSON é a capacidade de preservar o tipo de dados original de seus valores durante a exportação. Caso um par chave-valor da Configuração de Aplicativos não tenha um tipo de conteúdo JSON, o valor será tratado como uma cadeia de caracteres.

Considere usar estes pares chave-valor sem o tipo de conteúdo JSON:

Ao exportar esses pares chave-valor para um arquivo JSON, os valores serão exportados como cadeias de caracteres:

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

No entanto, ao exportar pares chave-valor JSON para um arquivo, todos os valores preservarão o respectivo tipo de dados original. Para verificar esse processo, exporte os pares chave-valor da Configuração de Aplicativos para um arquivo JSON. Você verá que o arquivo exportado tem o mesmo conteúdo do arquivo Import.json importado anteriormente.

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

Como consumir pares chave-valor JSON em aplicativos

O modo mais fácil de consumir pares chave-valor JSON em seu aplicativo é por meio de bibliotecas de provedores da Configuração de Aplicativos. Com as bibliotecas de provedores, não é preciso implementar um tratamento especial de pares chave-valor JSON em seu aplicativo. Eles serão analisados e convertidos para corresponder à configuração nativa do aplicativo.

Por exemplo, caso tenha a seguinte chave-valor na Configuração de Aplicativos:

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

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

Caso você esteja usando o SDK ou a API REST para ler pares chave-valor da Configuração de Aplicativos com base no tipo de conteúdo, o aplicativo será responsável por analisar o valor de um par chave-valor 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.

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 pares chave-valor JSON em seu repositório da Configuração de Aplicativos, crie um aplicativo para consumir estes pares chave-valor: