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 异常，并显示消息“名称 <var> 已被保留”。

生成输出

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

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

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 版本新增。