键和值Keys and values

Azure 应用配置将配置数据存储为键值。Azure App Configuration stores configuration data as key-values. 键值是开发人员使用的“应用程序设置”的一种简单灵活的表示形式。Key-values are a simple and flexible representation of application settings used by developers.


键用作键值的标识符,用于存储和检索相应的值。Keys serve as identifiers for key-values and are used to store and retrieve corresponding values. 使用字符分隔符(如 /:)将键组织到分层命名空间中是一种常见做法。It's a common practice to organize keys into a hierarchical namespace by using a character delimiter, such as / or :. 可使用最适合应用程序的约定。Use a convention best suited to your application. 应用配置将密钥视为一个整体。App Configuration treats keys as a whole. 不会解析键以弄清楚其名字是如何构成的,也不会强制执行任何规则。It doesn't parse keys to figure out how their names are structured or enforce any rule on them.

下面是基于组件服务按层次结构组织的键名称的示例:Here is an example of key names structured into a hierarchy based on component services:


在应用程序框架内使用配置数据可以规定键值的特定命名方案。The use of configuration data within application frameworks might dictate specific naming schemes for key-values. 例如,Java 的 Spring Cloud 框架定义了 Environment 资源,这些资源为 Spring 应用程序提供设置。For example, Java's Spring Cloud framework defines Environment resources that supply settings to a Spring application. 这些资源通过包括应用程序名称和配置文件在内的变量进行了参数化 。These are parameterized by variables that include application name and profile. Spring Cloud 相关配置数据的键通常以这两个元素开头,由一个分隔符分开。Keys for Spring Cloud-related configuration data typically start with these two elements separated by a delimiter.

存储在应用配置中的密钥是区分大小写的、基于 unicode 的字符串。Keys stored in App Configuration are case-sensitive, unicode-based strings. “app1”和“App1”键在应用程序配置存储区中是有所区分的。The keys app1 and App1 are distinct in an App Configuration store. 在应用程序中使用配置设置时,请记住这一点,因为有些框架处理配置键时不区分大小写。Keep this in mind when you use configuration settings within an application because some frameworks handle configuration keys case-insensitively. 不建议使用大小写来区分键。We do not recommend using case to differentiate keys.

可以在键名称中使用任何 unicode 字符,除了 %You can use any unicode character in key names except for %. 键名称不能为 ...A key name cannot be . or .. either. 键值的组合大小限制为 10 KB。There's a combined size limit of 10 KB on a key-value. 此限制包括键中的所有字符、其值以及所有相关的可选属性。This limit includes all characters in the key, its value, and all associated optional attributes. 在此限制范围内,可以为密钥设置许多层次结构级别。Within this limit, you can have many hierarchical levels for keys.

设计键命名空间Design key namespaces

命名用于配置数据的密钥有两种通用方法:平面或分层。There are two general approaches to naming keys used for configuration data: flat or hierarchical. 从应用程序使用情况的角度来看,这些方法非常相似,但分层命名提供了许多优点:These methods are similar from an application usage standpoint, but hierarchical naming offers a number of advantages:

  • 更易于阅读。Easier to read. 分层键名称功能中的分隔符在句子中充当空格。Delimiters in a hierarchical key name function as spaces in a sentence. 它们还在单词之间提供自然的分隔。They also provide natural breaks between words.
  • 更易于管理。Easier to manage. 密钥名称层次结构表示配置数据的逻辑组。A key name hierarchy represents logical groups of configuration data.
  • 更易于使用。Easier to use. 更简单的方法是编写一个查询,该查询在层次结构中模式匹配密钥并仅检索部分配置数据。It's simpler to write a query that pattern-matches keys in a hierarchical structure and retrieves only a portion of configuration data. 此外,许多较新的编程框架对分层配置数据具有本机支持,因此应用程序可以使用特定的配置集。Also, many newer programming frameworks have native support for hierarchical configuration data such that your application can make use of specific sets of configuration.

可以通过多种方式按层次结构组织应用配置中的密钥。You can organize keys in App Configuration hierarchically in many ways. 将此类键视为 URI。Think of such keys as URIs. 每个分层键是由一个或多个组件组成的资源“路径”,由分隔符联接在一起。Each hierarchical key is a resource path composed of one or more components that are joined together by delimiters. 根据应用程序、编程语言或框架的需要选择要用作分隔符的字符。Choose what character to use as a delimiter based on what your application, programming language, or framework needs. 在应用配置中为不同的键使用多个分隔符。Use multiple delimiters for different keys in App Configuration.

标签键Label keys

应用配置中的键值可以选择具有“标签”属性。Key-values in App Configuration can optionally have a label attribute. 标签用于使用相同的键区分键值。Labels are used to differentiate key-values with the same key. 带有“A”标签和“B”标签的“app1”键会在应用程序配置存储区中形成两个单独的键 。A key app1 with labels A and B forms two separate keys in an App Configuration store. 默认情况下,键值没有标签。By default, a key-value has no label. 若要显式引用不带标签的键值,请使用 \0(编码为 %00 的 URL)。To explicitly reference a key-value without a label, use \0 (URL encoded as %00).

标签提供了一种方便的方式来创建键的变体。Label provides a convenient way to create variants of a key. 标签的常见用途是为同一个键指定多个环境:A common use of labels is to specify multiple environments for the same key:

    Key = AppName:DbEndpoint & Label = Test
    Key = AppName:DbEndpoint & Label = Staging
    Key = AppName:DbEndpoint & Label = Production

键值版本Version key-values

使用标签作为创建键值的多个版本的方法。Use labels as a way to create multiple versions of a key-value. 例如,可以在标签中输入应用程序版本号或 Git 提交 ID,以标识与特定软件版本关联的键值。For example, you can input an application version number or a Git commit ID in labels to identify key-values associated with a particular software build.


如果要查找“更改”的版本,应用程序配置会自动保留过去特定时间段内发生的所有键值更改。If you are looking for change versions, App Configuration keeps all changes of a key-value occurred in the past certain period of time automatically. 有关详细信息,请参阅时间点快照See point-in-time snapshot for more details.

查询键值Query key-values

每个键值通过其键以及可以为 \0 的标签进行唯一标识。Each key-value is uniquely identified by its key plus a label that can be \0. 可以通过指定模式来查询应用程序配置存储区中的键值。You query an App Configuration store for key-values by specifying a pattern. 应用程序配置存储区会返回与模式匹配的所有键值,包括对应的值和属性。The App Configuration store returns all key-values that match the pattern including their corresponding values and attributes. 在 REST API 调用应用配置时使用以下键模式:Use the following key patterns in REST API calls to App Configuration:

Key 说明Description
省略 keykey=*key is omitted or key=* 匹配所有密钥Matches all keys
key=abc 完全匹配键名称 abcMatches key name abc exactly
key=abc* 匹配以 abc 开头的密钥名称Matches key names that start with abc
key=abc,xyz 匹配密钥名称 abc 或 xyz 。Matches key names abc or xyz. 限制为 5 个 CSVLimited to five CSVs

还可以包含以下标签模式:You also can include the following label patterns:

LabelLabel 说明Description
省略 labellabel=*label is omitted or label=* 匹配任何标签,包括 \0Matches any label, which includes \0
label=%00 匹配 \0 标签Matches \0 label
label=1.0.0 完全匹配标签 1.0.0Matches label 1.0.0 exactly
label=1.0.* 匹配以 1.0. 开头的标签Matches labels that start with 1.0.
label=%00,1.0.0 匹配标签 \01.0.0,限制为五个 CSVMatches labels \0 or 1.0.0, limited to five CSVs


*,\ 是查询中的保留字符。*, ,, and \ are reserved characters in queries. 如果在键名称或标签中使用了保留字符,需要在查询中使用 \{Reserved Character} 来转义它。If a reserved character is used in your key names or labels, you must escape it by using \{Reserved Character} in queries.


分配给键的值也是 unicode 字符串。Values assigned to keys are also unicode strings. 可以将所有 unicode 字符用于值。You can use all unicode characters for values.

使用 Content-TypeUse Content-Type

应用程序配置中的每个键值都有一个内容类型属性。Each key-value in App Configuration has a content-type attribute. 可以选择使用此属性来存储关于键值中值类型的信息,其有助于应用程序正确处理该信息。You can optionally use this attribute to store information about the type of value in a key-value that helps your application to process it properly. 可为 content-type 使用任何格式。You can use any format for the content-type. 应用程序配置为内置数据类型(如功能标志、Key Vault 引用和 JSON 键值)使用媒体类型(也称为 MIME 类型)。App Configuration uses Media Types (also known as MIME types) for built-in data types such as feature flags, Key Vault references, and JSON key-values.

后续步骤Next steps