community.general.dconf 模块 – 修改和读取 dconf 数据库

注意

此模块是 community.general 集合 (版本 10.1.0) 的一部分。

如果您使用的是 ansible 软件包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install community.general。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。

要在 playbook 中使用它，请指定： community.general.dconf。

概要

  • 此模块允许修改和读取 dconf 数据库。该模块作为 dconf 工具的包装器实现。有关更多详细信息，请参阅 dconf(1) 手册页。

  • 由于 dconf 需要运行的 D-Bus 会话才能更改值，因此该模块将尝试检测现有会话并重用它，或通过 dbus-run-session 运行该工具。

要求

执行此模块的主机需要以下要求。

  • 可选的 gi.repository Python 库（通常包含在具有 dconf 的主机的操作系统中）；这将在 community.general 的未来主要版本中成为非可选要求。

参数

参数

注释

key

字符串 / 必需

要修改或从中读取 dconf 数据库的 dconf 密钥。

state

字符串

对键/值执行的操作。

选项

  • "read"

  • "present" ← (默认)

  • "absent"

value

任意

为指定的 dconf 密钥设置的值。值应以 GVariant 格式指定。由于此格式的复杂性，最好查看 dconf 数据库中的现有值。

对于 state=present 是必需的。

尽管类型指定为“原始”，但它通常应指定为字符串。但是，特别是布尔值即使指定为布尔值而不是字符串也能正确处理（事实上，正确处理布尔值正是此参数类型为“原始”的原因）。

属性

属性

支持

描述

check_mode

支持：完全支持

可以在 check_mode 中运行，并在不修改目标的情况下返回更改状态预测。

diff_mode

支持：不支持

在差异模式下，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

备注

注意

  • 此模块依赖于 psutil Python 库（版本 4.0.0 及更高版本）、dconf、dbus-send 和 dbus-run-session 二进制文件。根据您使用的发行版，您可能需要安装其他软件包才能使用这些软件包。

  • 此模块在可用时使用 gi.repository Python 库来准确比较 dconf 中的值与 Ansible 代码中指定的值。gi.repository 可能会出现在大多数具有 dconf 的系统上，但并非所有地方都存在。当它不存在时，将使用值之间的简单字符串比较，并且可能存在误报，也就是说，Ansible 可能会认为值正在更改而实际上没有更改。此回退将在此模块的未来版本中删除，届时该模块将停止在没有 gi.repository 的主机上工作。

  • 由于 D-Bus 守护程序本身的实现细节，检测现有的运行 D-Bus 会话（需要通过 dconf 更改设置）并非 100% 可靠。如果通过 Ansible 和 dbus-run-session 更改选项，这可能会导致运行中的应用程序无法即时获取更改。

  • 请记住，此模块围绕其进行包装的 dconf CLI 工具使用不寻常的语法来表示值 (GVariant)。例如，如果您想提供字符串值，正确的语法将是 value="'myvalue'" — Ansible 参数值的一部分带有单引号。

  • 当将循环与 "[('xkb', 'us'), ('xkb', 'se')]" 等值结合使用时，您需要注意可能的类型转换。将过滤器 {{ item.value | string }} 应用于参数变量可以避免潜在的转换问题。

  • 确定需要为密钥提供的确切语法/值的最简单方法是更改受密钥影响的应用程序中的配置，然后通过命令 dconf dump /path/to/dir/ 或 dconf read /path/to/key 查看设置的值。

示例

- name: Configure available keyboard layouts in Gnome
  community.general.dconf:
    key: "/org/gnome/desktop/input-sources/sources"
    value: "[('xkb', 'us'), ('xkb', 'se')]"
    state: present

- name: Read currently available keyboard layouts in Gnome
  community.general.dconf:
    key: "/org/gnome/desktop/input-sources/sources"
    state: read
  register: keyboard_layouts

- name: Reset the available keyboard layouts in Gnome
  community.general.dconf:
    key: "/org/gnome/desktop/input-sources/sources"
    state: absent

- name: Configure available keyboard layouts in Cinnamon
  community.general.dconf:
    key: "/org/gnome/libgnomekbd/keyboard/layouts"
    value: "['us', 'se']"
    state: present

- name: Read currently available keyboard layouts in Cinnamon
  community.general.dconf:
    key: "/org/gnome/libgnomekbd/keyboard/layouts"
    state: read
  register: keyboard_layouts

- name: Reset the available keyboard layouts in Cinnamon
  community.general.dconf:
    key: "/org/gnome/libgnomekbd/keyboard/layouts"
    state: absent

- name: Disable desktop effects in Cinnamon
  community.general.dconf:
    key: "/org/cinnamon/desktop-effects"
    value: "false"
    state: present

返回值

常见的返回值已在 此处 记录，以下是此模块独有的字段

键

描述

value

字符串

与请求键关联的值

返回：成功，状态为“读取”

示例： "'Default'"

作者

  • Branko Majic (@azaghal)