VarDict 指南

简介

ansible_collections.community.general.plugins.module_utils.vardict 模块实用程序提供 VarDict 类来帮助管理模块变量。该类是模块变量的容器，特别是那些模块必须跟踪状态变化的变量，以及那些应该作为返回值发布的变量。

每个变量都有由关联元数据控制的额外行为，从而简化了从模块生成输出值的过程。

快速入门

使用 VarDict 的最简单方法是

from ansible_collections.community.general.plugins.module_utils.vardict import VarDict

然后在 main() 或从那里调用的任何其他函数中

vars = VarDict()

# Next 3 statements are equivalent
vars.abc = 123
vars["abc"] = 123
vars.set("abc", 123)

vars.xyz = "bananas"
vars.ghi = False

到模块即将退出时

results = vars.output()
module.exit_json(**results)

这将使模块的返回值为

{
    "abc": 123,
    "xyz": "bananas",
    "ghi": false
}

元数据

与每个变量关联的元数据值如下

  • output: bool - 将变量标记为模块输出，作为模块返回值。

  • fact: bool - 将变量标记为模块输出，作为 Ansible 事实。

  • verbosity: int - 设置变量包含在输出中的最低详细级别。

  • change: bool - 控制变量值中更改的检测。

  • initial_value: any - 当使用 change 并且需要强制将变量设置为初始值时。

  • diff: bool - 与 change 一起使用，这将生成 Ansible 样式的 diff dict。

有关如何使用元数据的更多详细信息，请参阅以下部分。

使用 VarDict

基本用法

如上所示，可以使用 [] 运算符（如 dict 对象中）访问变量，也可以作为对象属性访问，如 vars.abc。使用 set() 方法的形式是特殊的，因为您可以使用它来设置元数据值

vars.set("abc", 123, output=False)
vars.set("abc", 123, output=True, change=True)

在创建变量后设置元数据的另一种方法是

vars.set_meta("abc", output=False)
vars.set_meta("abc", output=True, change=True, diff=True)

您可以使用运算符和属性形式来访问变量的值。访问其值及其元数据的其他方法是

print("abc value = {0}".format(vars.var("abc")["value"]))        # get the value
print("abc output? {0}".format(vars.get_meta("abc")["output"]))  # get the metadata like this

方法名称（如 set、get_meta 和 output 等）是保留的，不能用作变量名。如果您尝试使用保留名称，则会引发 ValueError 异常，并显示消息“名称 已保留”。

生成输出

默认情况下，每次创建变量时都会启用输出，并将最低详细程度设置为零，换句话说，默认情况下它们将始终位于输出中。

您可以在首次创建变量时或稍后在代码中控制这一点

vars.set("internal", x + 4, output=False)
vars.set_meta("internal", output=False)

您还可以设置某些变量的详细程度，例如

vars.set("abc", x + 4)
vars.set("debug_x", x, verbosity=3)

results = vars.output(module._verbosity)
module.exit_json(**results)

如果模块的调用详细程度低于 3，则输出将仅包含变量 abc。如果在更高的详细程度下运行，如 ansible-playbook -vvv，则输出还将包含 debug_x。

生成事实与常规输出非常相似，但默认情况下变量不会标记为事实。

vars.set("modulefact", x + 4, fact=True)
vars.set("debugfact", x, fact=True, verbosity=3)

results = vars.output(module._verbosity)
results["ansible_facts"] = {"module_name": vars.facts(module._verbosity)}
module.exit_json(**results)

处理更改

您可以使用 VarDict 来确定变量的值是否已更改。

vars.set("abc", 42, change=True)
vars.abc = 90

results = vars.output()
results["changed"] = vars.has_changed
module.exit_json(**results)

如果跟踪变量中的更改，您可能希望显示其初始值和最终值之间的差异。为此，您需要使用

vars.set("abc", 42, change=True, diff=True)
vars.abc = 90

results = vars.output()
results["changed"] = vars.has_changed
results["diff"] = vars.diff()
module.exit_json(**results)

7.1.0 版本中的新增功能。