利用内容类型在应用程序配置中存储 JSON 密钥值Leverage content-type to store JSON key-values in App Configuration

数据在“应用程序配置”中存储为键值,默认情况下,值被视为字符串类型。Data is stored in App Configuration as key-values, where values are treated as the string type by default. 但是,可以通过利用与每个键值关联的内容类型属性来指定自定义类型,以便保留数据的原始类型,或让应用程序能够根据内容类型改变自己的行为。However, you can specify a custom type by leveraging the content-type property associated with each key-value, so that you can preserve the original type of your data or have your application behave differently based on content-type.

概述Overview

在应用程序配置中,可将 JSON 媒体类型用作键值的内容类型,以获得如下好处:In App Configuration, you can use the JSON media type as the content-type of your key-values to avail benefits like:

  • 更简单的数据管理:在 Azure 门户中,管理键值(如数组)将变得更加容易。Simpler data management: Managing key-values, like arrays, will become a lot easier in the Azure portal.
  • 增强的数据导出:在数据导出过程中将保留基元类型、数组和 JSON 对象。Enhanced data export: Primitive types, arrays, and JSON objects will be preserved during data export.
  • 提供应用程序配置提供程序本机支持:当应用程序中的“应用程序配置提供程序库”使用具有 JSON 内容类型的键值时,这些键值能够正常运行。Native support with App Configuration provider: Key-values with JSON content-type will work fine when consumed by App Configuration provider libraries in your applications.

有效的 JSON 内容类型Valid JSON content-type

此处定义的媒体类型可分配给与每个键值关联的内容类型。Media types, as defined here, can be assigned to the content-type associated with each key-value. 媒体类型包括类型和子类型。A media type consists of a type and a subtype. 如果类型为 application 且子类型(或后缀)为 json,则媒体类型将被视为有效的 JSON 内容类型。If the type is application and the subtype (or suffix) is json, the media type will be considered a valid JSON content-type. 有效 JSON 内容类型的一些示例如下:Some examples of valid JSON content-types are:

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

有效的 JSON 值Valid JSON values

当键值具有 JSON 内容类型时,其值必须采用有效 JSON 格式,以便客户端正确处理它。When a key-value has JSON content-type, its value must be in valid JSON format for clients to process it correctly. 否则,客户端可能会失败或回退,并将其视为字符串格式。Otherwise, clients may fail or fall back and treat it as string format. 有效 JSON 值的一些示例如下:Some examples of valid JSON values are:

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

备注

在本文的其余部分中,应用程序配置中具有有效 JSON 内容类型和有效 JSON 值的任何键值都将称为 JSON 键值。For the rest of this article, any key-value in App Configuration that has a valid JSON content-type and a valid JSON value will be referred to as JSON key-value.

本教程介绍以下操作:In this tutorial, you'll learn how to:

  • 在应用程序配置中创建 JSON 键值。Create JSON key-values in App Configuration.
  • 从 JSON 文件中导入 JSON 键值。Import JSON key-values from a JSON file.
  • 将 JSON 键值导出到 JSON 文件。Export JSON key-values to a JSON file.
  • 在应用程序中使用 JSON 键值。Consume JSON key-values in your applications.

如果没有 Azure 试用版订阅,请在开始前创建一个试用版订阅If you don't have an Azure trail subscription, create a trial subscription before you begin.

先决条件Prerequisites

  • 如果需要,请安装 Azure CLI 来运行 CLI 参考命令。If you prefer, install the Azure CLI to run CLI reference commands.
    • 如果使用的是本地安装,请通过 Azure CLI 使用 az login 命令登录。If you're using a local install, sign in with Azure CLI by using the az login command. 若要完成身份验证过程,请遵循终端中显示的步骤。To finish the authentication process, follow the steps displayed in your terminal. 有关其他登录选项,请参阅使用 Azure CLI 登录See Sign in with Azure CLI for additional sign-in options.
    • 出现提示时,请在首次使用时安装 Azure CLI 扩展。When you're prompted, install Azure CLI extensions on first use. 有关扩展详细信息,请参阅使用 Azure CLI 的扩展For more information about extensions, see Use extensions with Azure CLI.
    • 运行 az version 以查找安装的版本和依赖库。Run az version to find the version and dependent libraries that are installed. 若要升级到最新版本,请运行 az upgradeTo upgrade to the latest version, run az upgrade.
  • 本教程需要 Azure CLI 2.10.0 或更高版本。This tutorial requires version 2.10.0 or later of the Azure CLI.

创建应用配置存储区Create an App Configuration store

  1. 若要创建新应用程序配置存储区,请登录 Azure 门户To create a new App Configuration store, sign in to the Azure portal. 在主页的左上角,选择“创建资源” 。In the upper-left corner of the home page, select Create a resource. 在“搜索市场”框中,输入“应用程序配置”并选择 Enter 。In the Search the Marketplace box, enter App Configuration and select Enter.

    搜索应用配置

  2. 在搜索结果中选择“应用程序配置”,然后选择“创建” 。Select App Configuration from the search results, and then select Create.

    选择“创建”

  3. 在“创建应用配置”窗格中,输入以下设置:On the Create App Configuration pane, enter the following settings:

    设置Setting 建议的值Suggested value 说明Description
    订阅Subscription 订阅Your subscription 选择要用来测试应用配置的 Azure 订阅。Select the Azure subscription that you want to use to test App Configuration. 如果帐户只有一个订阅,则会自动选择该订阅并且不显示“订阅”列表 。If your account has only one subscription, it's automatically selected and the Subscription list isn't displayed.
    资源组Resource group AppConfigTestResources AppConfigTestResources 为应用程序配置存储区资源选择或创建资源组。Select or create a resource group for your App Configuration store resource. 此组可用于组织多个资源,删除该资源组可以同时删除这些资源。This group is useful for organizing multiple resources that you might want to delete at the same time by deleting the resource group. 有关详细信息,请参阅使用资源组管理 Azure 资源For more information, see Use resource groups to manage your Azure resources.
    资源名称Resource name 全局唯一名称Globally unique name 输入要用于应用程序配置存储区资源的唯一资源名称。Enter a unique resource name to use for the App Configuration store resource. 该名称必须是包含 5 到 50 个字符的字符串,只能包含数字、字母和 - 字符。The name must be a string between 5 and 50 characters and contain only numbers, letters, and the - character. 该名称的开头或末尾不能是 - 字符。The name can't start or end with the - character.
    位置Location 中国东部 2China East 2 使用“位置”指定在其中托管应用配置存储区的地理位置 。Use Location to specify the geographic location in which your app configuration store is hosted. 为获得最佳性能,请在应用程序的其他组件所在的同一区域创建资源。For the best performance, create the resource in the same region as other components of your application.
    定价层Pricing tier 免费Free 选择所需的定价层。Select the desired pricing tier. 有关详细信息,请参阅应用配置定价页For more information, see the App Configuration pricing page.
  4. 选择“查看 + 创建”以验证自己的设置 。Select Review + create to validate your settings.

  5. 选择“创建”。Select Create. 部署可能需要几分钟。The deployment might take a few minutes.

  6. 部署完成后,导航到“应用程序配置”资源。After the deployment finishes, navigate to the App Configuration resource. 选择“设置” > “访问密钥”。Select Settings > Access keys. 记下只读主密钥连接字符串。Make a note of the primary read-only key connection string. 稍后将使用此连接字符串来配置应用程序,以与创建的应用程序配置存储区进行通信。You'll use this connection string later to configure your application to communicate with the App Configuration store that you created.

在应用程序配置中创建 JSON 键值Create JSON key-values in App Configuration

可以通过使用 Azure 门户、Azure CLI 或从 JSON 文件中导入来创建 JSON 键值。JSON key-values can be created using Azure portal, Azure CLI or by importing from a JSON file. 本节中将介绍如何使用这三种方法创建相同的 JSON 键值。In this section, you will find instructions on creating the same JSON key-values using all three methods.

使用 Azure 门户创建 JSON 键值Create JSON key-values using Azure portal

浏览到应用程序配置存储,选择“配置资源管理器” > “创建” > “键值”来添加以下键值对 :Browse to your App Configuration store, and select Configuration Explorer > Create > Key-value to add the following key-value pairs:

Key Value 内容类型Content Type
Settings:BackgroundColorSettings:BackgroundColor "Green""Green" application/jsonapplication/json
Settings:FontSizeSettings:FontSize 2424 application/jsonapplication/json
Settings:UseDefaultRoutingSettings:UseDefaultRouting falsefalse application/jsonapplication/json
Settings:BlockedUsersSettings:BlockedUsers nullnull application/jsonapplication/json
Settings:ReleaseDateSettings:ReleaseDate "2020-08-04T12:34:56.789Z""2020-08-04T12:34:56.789Z" application/jsonapplication/json
Settings:RolloutPercentageSettings:RolloutPercentage [25,50,75,100][25,50,75,100] application/jsonapplication/json
Settings:LoggingSettings:Logging {"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}}{"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}} application/jsonapplication/json

将“标签”留空,然后选择“应用” 。Leave Label empty and select Apply.

使用 Azure CLI 创建 JSON 键值Create JSON key-values using Azure CLI

以下命令将在应用程序配置存储中创建 JSON 键值。The following commands will create JSON key-values in your App Configuration store. <appconfig_name> 替换为应用程序配置存储的名称。Replace <appconfig_name> with the name of your App Configuration store.

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 字符串。If you are using Azure CLI to create JSON key-values, the value provided must be an escaped JSON string.

从文件导入 JSON 键值Import JSON key-values from a file

创建一个具有以下内容的名为 Import.json 的 JSON 文件,并将其作为键值导入到应用程序配置中:Create a JSON file called Import.json with the following content and import as key-values into App Configuration:

{
  "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 参数用于将文件中的分层数据合并为键值对。The --depth argument is used for flattening hierarchical data from a file into key-value pairs. 本教程指定了深度,目的是演示还可将 JSON 对象存储为应用程序配置中的值。In this tutorial, depth is specified for demonstrating that you can also store JSON objects as values in App Configuration. 如果未指定深度,则默认情况下,JSON 对象将合并到最深级别。If depth is not specified, JSON objects will be flattened to the deepest level by default.

在应用程序配置中,创建的 JSON 键值应如下所示:The JSON key-values you created should look like this in App Configuration:

包含 JSON 键值的配置存储

将 JSON 键值导出到文件Export JSON key-values to a file

使用 JSON 键值的一个主要好处是在导出时能够保留值的原始数据类型。One of the major benefits of using JSON key-values is the ability to preserve the original data type of your values while exporting. 如果应用程序配置中的键值不具有 JSON 内容类型,则其值将被视为字符串。If a key-value in App Configuration doesn't have JSON content-type, its value will be treated as string.

请考虑以下没有 JSON 内容类型的键值:Consider these key-values without JSON content-type:

Key Value 内容类型Content Type
Settings:FontSizeSettings:FontSize 2424
Settings:UseDefaultRoutingSettings:UseDefaultRouting falsefalse

将这些键值导出到 JSON 文件时,这些值将作为字符串导出:When you export these key-values to a JSON file, the values will be exported as strings:

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

而将 JSON 键值导出到文件时,所有值都将保留其原始数据类型。However, when you export JSON key-values to a file, all values will preserve their original data type. 若要验证这一点,可将键值从应用程序配置导出到 JSON 文件。To verify this, export key-values from your App Configuration to a JSON file. 你将看到导出的文件与先前导入的 Import.json 文件具有相同的内容。You'll see that the exported file has the same contents as the Import.json file you previously imported.

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

备注

如果你的应用程序配置存储具有没有 JSON 内容类型的某些键值,则这些值也将以字符串格式导出到相同的文件中。If your App Configuration store has some key-values without JSON content-type, they will also be exported to the same file in string format. 如果只想导出 JSON 键值,请为 JSON 键值分配唯一的标签或前缀,并在导出过程中使用标签或前缀筛选。If you want to export only the JSON key-values, assign a unique label or prefix to your JSON key-values and use label or prefix filtering during export.

在应用程序中使用 JSON 键值Consuming JSON key-values in applications

在应用程序中使用 JSON 键值的最简单方法是通过应用程序配置提供程序库来使用。The easiest way to consume JSON key-values in your application is through App Configuration provider libraries. 借助提供程序库,无需在应用程序中实现 JSON 键值的特殊处理。With the provider libraries, you don't need to implement special handling of JSON key-values in your application. 对于应用程序,它们反序列化的方式始终与其他 JSON 配置提供程序库相同。They're always deserialized for your application in the same way that other JSON configuration provider libraries do.

重要

.NET 配置提供程序版本 4.0.0(或更高版本)中提供了对 JSON 键值的本机支持。Native support for JSON key-values is available in .NET configuration provider version 4.0.0 (or later). 有关更多详细信息,请参阅后续步骤See Next steps section for more details.

如果使用 SDK 或 REST API 从应用程序配置中读取键值(基于内容类型),则由应用程序负责使用标准 JSON 反序列化程序对 JSON 键值的值进行反序列化。If you are using the SDK or REST API to read key-values from App Configuration, based on the content-type, your application is responsible for deserializing the value of a JSON key-value using any standard JSON deserializer.

清理资源Clean up resources

如果不想继续使用本文中创建的资源,请删除此处创建的资源组以避免产生费用。If you do not want to continue using the resources created in this article, delete the resource group you created here to avoid charges.

重要

删除资源组的操作不可逆。Deleting a resource group is irreversible. 将永久删除资源组以及其中的所有资源。The resource group and all the resources in it are permanently deleted. 请确保不要意外删除错误的资源组或资源。Make sure that you don't accidentally delete the wrong resource group or resources. 如果在包含要保留的其他资源的资源组中创建了本文的资源,请从相应的窗格中单独删除每个资源,而不是删除该资源组。If you created the resources for this article inside a resource group that contains other resources you want to keep, delete each resource individually from its respective pane instead of deleting the resource group.

  1. 登录到 Azure 门户,然后选择“资源组”。Sign in to the Azure portal, and select Resource groups.
  2. 在“按名称筛选”框中,输入资源组的名称。In the Filter by name box, enter the name of your resource group.
  3. 在结果列表中,选择资源组名称以查看概述。In the result list, select the resource group name to see an overview.
  4. 选择“删除资源组”。Select Delete resource group.
  5. 系统会要求确认是否删除资源组。You're asked to confirm the deletion of the resource group. 重新键入资源组的名称进行确认,然后选择“删除” 。Enter the name of your resource group to confirm, and select Delete.

片刻之后,将会删除该资源组及其所有资源。After a few moments, the resource group and all its resources are deleted.

后续步骤Next steps

现在,你已了解如何在应用程序配置存储中使用 JSON 键值,请创建一个应用程序来使用以下键值:Now that you know how to work with JSON key-values in your App Configuration store, create an application for consuming these key-values: