快照引用

快照引用是指向应用配置存储中特定快照的特殊键值。通过它们，可以将不可变配置（快照）的安全性与动态更改应用程序在运行时使用哪个快照的灵活性结合起来。

使用直接快照，应用程序在代码中按名称选择快照。更改目标快照需要在生成配置的代码路径中更改新的部署或配置。快照引用将删除该约束：加载引用键值一次，如果其目标快照名称稍后更改，则配置提供程序会自动将配置重新加载到新的不可变集。

为何使用快照引用？

快照引用可以提供以下内容：

轻松更新：更新引用的快照，而无需触摸应用程序代码，即使在运行时也是如此。
不可变配置集：每个快照保持不变，保留可审核性和回滚保证。

工作原理

快照引用存储为键值，其值包含要消耗的快照的名称。当配置供应商加载键值时，所选项中的快照引用会被自动解析。引用的快照的键值合并到应用程序的配置中。如果引用更改为指向其他快照，则配置提供程序刷新将导致加载新的快照内容。

注释

无需调用专用 API 即可选择使用快照引用。如果选择作为快照引用的键值，则自动解析。

创建快照引用

在 Azure 门户中打开应用程序配置存储区。
选择“配置资源管理器”。
选择“创建”。
选择 快照引用。
输入一个引用键。（可选）设置标签。
从列表中选择目标快照名称（或输入它）。
选择创建。

创建后，快照引用将与其他键值一起显示在配置资源管理器中。

使用快照引用

无需新代码来使用快照引用。如果快照引用的键是生成配置时所选键值的一部分，提供程序会自动解析并加载引用的快照的键值。与直接使用快照进行比较，这需要您在启动时显式调用 API，例如 SelectSnapshot("SnapshotName")，以便于选择快照，从而当您以后需要更换快照时，可能需要更改代码或重新部署。

刷新行为

在配置刷新后，更改快照引用中的目标快照名称可以无缝地将应用程序切换到使用新快照。

应用程序启动。
配置提供程序获取包括快照引用在内的选定键值。
配置提供程序解析对快照 Snapshot_A 的引用并加载其键值。
快照引用已更新为指向Snapshot_B，它仍然不可变。
配置提供程序检测到快照引用键值已更改。
配置提供程序重新进行解析。 Snapshot_A 的键值已被卸载。配置重载将产生键和值 Snapshot_B。

注释

此序列假定你已为应用程序配置刷新。有关如何配置刷新的详细信息，请参阅动态配置。

示例快照参考

以下示例演示快照引用

{
    "key": "app1/snapshot-reference",
    "value": "{\"snapshot_name\":\"referenced-snapshot\"}",
    "content_type": "application/json; profile=\"https://azconfig.io/mime-profiles/snapshot-ref\"; charset=utf-8",
    "tags": {}
}

如前所述，快照引用是具有一些附加约束的常规键值。配置提供程序根据其特定的内容类型识别快照引用。快照引用的值是具有指向目标快照的名称属性的 json 对象。

快照引用内容类型：application/json; profile="https://azconfig.io/mime-profiles/snapshot-ref"; charset=utf-8

关键冲突解决

引用的快照可能包含与普通键值（快照外部的键值）冲突的键。配置提供程序通过使用最后一个被检索到的键的值来处理这些冲突。对于快照，由于它们在出现时会立即得到解决，因此，在出现冲突的情况下，快照键的字典顺序是考虑某个键最终值时的重要细节。

简化的示例

假设您的商店具有以下常规键值：

key: message
value: hello-world

key: request-limit
value: 100

以及包含以下内容的快照：

key: message
value: bye

key: request-limit
value: 8000

如果添加指向上述快照的快照引用，则最终的有效配置取决于快照引用键的字典位置：

快照引用密钥	字典位置对比 `message`，`request-limit`	最终 `message` 值	最终 `request-limit` 值	为什么
`a-snapshot-reference`	在两者之前	hello-world	100	首先解析快照引用；稍后的正常键会覆盖其重复项。
`my-snapshot-reference`	在 `message` 之后但在 `request-limit` 之前	再见	100	`message` 首先被看到。然后解析快照引用并覆盖 `message`。最后，默认 `request-limit` 值将覆盖快照 `request-limit` 值。
`some-snapshot-reference`	两者之后	再见	8,000	快照引用最后被解析，其值优先于先前重复项的值。

注意事项和极端情况

缺少目标快照：如果引用指向不存在或存档超出保留期的快照名称，提供程序将忽略该引用。
无传递性解析：如果引用的快照中包含一个键值，该键值本身是另一个快照引用，则该内部引用不会被解析。
访问控制：通过引用读取快照需要快照读取权限，类似于直接读取快照。
保留/存档：在引用存档快照时小心，因为快照过期后，应用将无法再访问包含的配置。

语言可用性

语言	最低版本/状态
.NET	8.4.0+
Java	正在进行的工作
JavaScript	正在进行的工作
Python	正在进行的工作
Go	正在进行的工作

后续步骤

创建和使用快照

有关更深入的背景信息，请参阅快照概述。

Last updated on 2026-01-26

通过