使用内容类型在应用程序配置中存储 JSON 密钥值

项目
02/05/2024

数据在“应用程序配置”中存储为键值，默认情况下，值被视为字符串类型。但是，可以使用与每个键值关联的内容类型属性来指定自定义类型。此过程保留数据的原始类型，或者使应用程序的行为因内容类型而异。

概述

在应用程序配置中，可将 JSON 媒体类型用作键值的内容类型，以获得以下好处：

更简单的数据管理：在 Azure 门户中，管理键值（如数组）将变得更加容易。
增强的数据导出：在数据导出过程中将保留基元类型、数组和 JSON 对象。
提供应用程序配置提供程序本机支持：当应用程序中的“应用程序配置提供程序库”使用具有 JSON 内容类型的键值时，这些键值能够正常运行。

有效的 JSON 内容类型

此处定义的媒体类型可分配给与每个键值关联的内容类型。媒体类型包括类型和子类型。如果类型为 application 且子类型（或后缀）为 json，则媒体类型将被视为有效的 JSON 内容类型。有效 JSON 内容类型的一些示例如下：

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

有效的 JSON 值

当键值具有 JSON 内容类型时，其值必须采用有效 JSON 格式，以便客户端正确处理它。否则，客户端可能会失败或回退，并将其视为字符串格式。有效 JSON 值的一些示例如下：

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

备注

在本文的其余部分中，应用程序配置中具有有效 JSON 内容类型和有效 JSON 值的任何键值都将称为 JSON 键值。

本教程介绍以下操作：

在应用程序配置中创建 JSON 键值。
从 JSON 文件中导入 JSON 键值。
将 JSON 键值导出到 JSON 文件。
在应用程序中使用 JSON 键值。

如果没有 Azure 试用版订阅，请在开始前创建一个试用版订阅。

先决条件

如需在本地运行 CLI 参考命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

应用程序配置存储区。创建存储区。
本教程需要 Azure CLI 2.10.0 或更高版本。

在应用程序配置中创建 JSON 键值

可以通过使用 Azure 门户、Azure CLI 或从 JSON 文件中导入来创建 JSON 键值。本节中将介绍如何使用这三种方法创建相同的 JSON 键值。

使用 Azure 门户创建 JSON 键值

将以下键值添加到应用程序配置存储区。让“标签”保留其默认值。有关如何使用 Azure 门户或 CLI 将键值添加到存储区的详细信息，请转到创建键值。

密钥	值	内容类型
Settings:BackgroundColor	“绿色”	application/json
Settings:FontSize	24	application/json
Settings:UseDefaultRouting	false	application/json
Settings:BlockedUsers	null	application/json
Settings:ReleaseDate	"2020-08-04T12:34:56.789Z"	application/json
Settings:RolloutPercentage	[25,50,75,100]	application/json
Settings:Logging	{"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}}	application/json

选择“应用”。

使用 Azure CLI 创建 JSON 键值

以下命令将在应用程序配置存储中创建 JSON 键值。将 <appconfig_name> 替换为应用程序配置存储的名称。

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\"}}

重要

如果使用 Azure CLI 创建 JSON 键值，则提供的值必须是转义的 JSON 字符串。

从文件导入 JSON 键值

创建一个具有以下内容的名为 Import.json 的 JSON 文件，并将其作为键值导入到应用程序配置中：

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

注意

--depth 参数用于将文件中的分层数据合并为键值。本教程指定了深度，目的是演示还可将 JSON 对象存储为应用程序配置中的值。如果未指定深度，则默认情况下，JSON 对象将合并到最深级别。

在应用程序配置中，创建的 JSON 键值应如下所示：

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

若要进行检查，请在 Azure 门户中打开应用程序配置资源，并转到“配置资源管理器”。

将 JSON 键值导出到文件

使用 JSON 键值的一个主要好处是在导出时能够保留值的原始数据类型。如果应用程序配置中的键值不具有 JSON 内容类型，则其值将被视为字符串。

请考虑以下没有 JSON 内容类型的键值：

密钥	值	内容类型
Settings:FontSize	24
Settings:UseDefaultRouting	false

将这些键值导出到 JSON 文件时，这些值将作为字符串导出：

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

而将 JSON 键值导出到文件时，所有值都将保留其原始数据类型。若要验证此过程，可将键值从应用程序配置导出到 JSON 文件。你将看到导出的文件与先前导入的 Import.json 文件具有相同的内容。

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

注意

如果你的应用程序配置存储具有没有 JSON 内容类型的某些键值，则这些值也将以字符串格式导出到相同的文件中。

在应用程序中使用 JSON 键值

在应用程序中使用 JSON 键值的最简单方法是通过应用程序配置提供程序库来使用。借助提供程序库，无需在应用程序中实现 JSON 键值的特殊处理。将对这些值进行分析和转换，使其与应用程序的原生配置匹配。

例如，如果在“应用配置”中有以下键/值：

密钥	值	内容类型
设置	{"FontSize":24,"UseDefaultRouting":false}	application/json

.NET 应用程序配置将包含以下键/值：

密钥	值
Settings:FontSize	24
Settings:UseDefaultRouting	false

你可以直接访问新键，也可以选择将配置值绑定到 .NET 对象的实例。

重要

.NET 配置提供程序版本 4.0.0（或更高版本）中提供了对 JSON 键值的本机支持。有关详细信息，请转到后续步骤部分。

如果使用 SDK 或 REST API 从应用程序配置中读取键/值（基于 content-type），则由应用程序负责分析 JSON 键/值的值。

清理资源

如果不想继续使用本文中创建的资源，请删除此处创建的资源组以避免产生费用。

重要

删除资源组的操作不可逆。将永久删除资源组以及其中的所有资源。请确保不要意外删除错误的资源组或资源。如果在包含要保留的其他资源的资源组中创建了本文的资源，请从相应的窗格中单独删除每个资源，而不是删除该资源组。

登录到 Azure 门户，然后选择“资源组”。
在“按名称筛选”框中，输入资源组的名称。
在结果列表中，选择资源组名称以查看概述。
选择“删除资源组”。
系统会要求确认是否删除资源组。重新键入资源组的名称进行确认，然后选择“删除” 。

片刻之后，将会删除该资源组及其所有资源。

后续步骤

现在，你已了解如何在应用程序配置存储中使用 JSON 键值，请创建一个应用程序来使用以下键值：

ASP.NET Core 快速入门

.NET Core 快速入门