community.general.xml 模块 – 管理 XML 文件或字符串的片段

注意

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

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

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

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

概要 

一个类似 CRUD 的界面，用于管理 XML 文件的片段。

要求 

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

lxml >= 2.3.0

参数 

参数	注释
add_children 列表 / elements=any	为给定的 `xpath` 向选定的元素添加额外的子元素。子元素必须在列表中给出，每个项目可以是字符串（例如，`children=ansible` 添加一个空的 `<ansible/>` 子元素），也可以是哈希，其中键是元素名称，值是元素值。此参数要求设置 `xpath`。
attribute any	在使用参数 `value` 时要选择的属性。这是一个字符串，而不是以 `@` 开头的字符串。
backup boolean	创建一个包含时间戳信息的备份文件，以便您在以某种方式错误地覆盖它时可以恢复原始文件。选项 `false` ← (默认) `true`
content string	搜索给定的 `xpath` 并获取内容。此参数要求设置 `xpath`。选项 `"attribute"` `"text"`
count boolean	搜索给定的 `xpath` 并提供任何匹配项的计数。此参数要求设置 `xpath`。选项 `false` ← (默认) `true`
input_type string	`add_children` 和 `set_children` 的输入类型。选项 `"xml"` `"yaml"` ← (默认)
insertafter boolean	在给定 `xpath` 的最后一个选定元素之后添加额外的子元素。子元素必须在列表中给出，每个项目可以是字符串（例如，`children=ansible` 添加一个空的 `<ansible/>` 子元素），也可以是哈希，其中键是元素名称，值是元素值。此参数要求设置 `xpath`。选项 `false` ← (默认) `true`
insertbefore boolean	在给定 `xpath` 的第一个选定元素之前添加额外的子元素。子元素必须在列表中给出，每个项目可以是字符串（例如，`children=ansible` 添加一个空的 `<ansible/>` 子元素），也可以是哈希，其中键是元素名称，值是元素值。此参数要求设置 `xpath`。选项 `false` ← (默认) `true`
namespaces dictionary	XPath 表达式的命名空间 `prefix:uri` 映射。需要是一个 `dict`，而不是一个 `list` 项目。默认值： `{}`
path 别名：dest, file path	要操作的文件的路径。此文件必须提前存在。除非给定 `xmlstring`，否则此参数是必需的。
pretty_print boolean	漂亮打印 XML 输出。选项 `false` ← (默认) `true`
print_match boolean	搜索给定的 `xpath` 并打印出任何匹配项。此参数要求设置 `xpath`。选项 `false` ← (默认) `true`
set_children 列表 / elements=any	为给定的 `xpath` 设置选定元素的子元素。移除所有现有的子元素。子元素必须按照 `add_children` 中的方式指定。此参数要求设置 `xpath`。
state 别名: ensure string	设置或移除 XPath 选择（节点、属性）。选项 `"absent"（不存在）` `"present"` ← (默认)
strip_cdata_tags boolean	移除文本值周围的 CDATA 标签。请注意，如果文本值包含可能被解释为 XML 的字符，这可能会破坏您的 XML 文件。选项 `false` ← (默认) `true`
value any	所选属性的期望状态。可以是字符串，或者要取消设置值，则使用 Python `None` 关键字（YAML 等效项，`null`）。元素默认没有值（但存在）。属性默认为空字符串。
xmlstring string	包含要操作的 XML 的字符串。除非提供了 `path` 参数，否则此参数是必需的。
xpath string	一个有效的 XPath 表达式，描述您要操作的项目。默认情况下，操作在文档根目录 `/` 上执行。

属性 

属性	支持	描述
check_mode	支持：完全	可以在 `check_mode` 中运行，并返回更改状态预测，而无需修改目标。
diff_mode	支持：完全	在差异模式下，将返回有关已更改内容（或在 `check_mode` 中可能需要更改的内容）的详细信息。

备注 

注意

测试表达式时，请使用 --check 和 --diff 选项。
差异输出会自动进行美化打印，因此可能无法反映实际文件内容，而仅反映文件结构。
此模块不处理复杂的 XPath 表达式，因此请将 XPath 选择器限制为简单的表达式。
请注意，如果您的 XML 元素是命名空间的，则需要使用 namespaces 参数，请参阅示例。
命名空间前缀应该用于定义命名空间的元素的所有子元素，除非为它们定义了另一个命名空间。

另请参阅 

另请参阅

Xml 模块开发社区 Wiki: 有关此 XML 模块开发的更多信息。
XPath 简介: 关于 XPath 的简要教程 (w3schools.com)。
XPath 参考文档: 关于 XSLT/XPath 的参考文档 (developer.mozilla.org)。

示例 

# Consider the following XML file:
#
# <business type="bar">
#   <name>Tasty Beverage Co.</name>
#     <beers>
#       <beer>Rochefort 10</beer>
#       <beer>St. Bernardus Abbot 12</beer>
#       <beer>Schlitz</beer>
#    </beers>
#   <rating subjective="true">10</rating>
#   <website>
#     <mobilefriendly/>
#     <address>http://tastybeverageco.com</address>
#   </website>
# </business>

- name: Remove the 'subjective' attribute of the 'rating' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/rating/@subjective
    state: absent

- name: Set the rating to '11'
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/rating
    value: 11

# Retrieve and display the number of nodes
- name: Get count of 'beers' nodes
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/beers/beer
    count: true
  register: hits

- ansible.builtin.debug:
    var: hits.count

# Example where parent XML nodes are created automatically
- name: Add a 'phonenumber' element to the 'business' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/phonenumber
    value: 555-555-1234

- name: Add several more beers to the 'beers' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/beers
    add_children:
    - beer: Old Rasputin
    - beer: Old Motor Oil
    - beer: Old Curmudgeon

- name: Add several more beers to the 'beers' element and add them before the 'Rochefort 10' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: '/business/beers/beer[text()="Rochefort 10"]'
    insertbefore: true
    add_children:
    - beer: Old Rasputin
    - beer: Old Motor Oil
    - beer: Old Curmudgeon

# NOTE: The 'state' defaults to 'present' and 'value' defaults to 'null' for elements
- name: Add a 'validxhtml' element to the 'website' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml

- name: Add an empty 'validatedon' attribute to the 'validxhtml' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml/@validatedon

- name: Add or modify an attribute, add element if needed
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml
    attribute: validatedon
    value: 1976-08-05

# How to read an attribute value and access it in Ansible
- name: Read an element's attribute values
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml
    content: attribute
  register: xmlresp

- name: Show an attribute value
  ansible.builtin.debug:
    var: xmlresp.matches[0].validxhtml.validatedon

- name: Remove all children from the 'website' element (option 1)
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/*
    state: absent

- name: Remove all children from the 'website' element (option 2)
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website
    set_children: []

# In case of namespaces, like in below XML, they have to be explicitly stated.
#
# <foo xmlns="http://x.test" xmlns:attr="http://z.test">
#   <bar>
#     <baz xmlns="http://y.test" attr:my_namespaced_attribute="true" />
#   </bar>
# </foo>

# NOTE: There is the prefix 'x' in front of the 'bar' element, too.
- name: Set namespaced '/x:foo/x:bar/y:baz/@z:my_namespaced_attribute' to 'false'
  community.general.xml:
    path: foo.xml
    xpath: /x:foo/x:bar/y:baz
    namespaces:
      x: http://x.test
      y: http://y.test
      z: http://z.test
    attribute: z:my_namespaced_attribute
    value: 'false'

- name: Adding building nodes with floor subnodes from a YAML variable
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business
    add_children:
      - building:
          # Attributes
          name: Scumm bar
          location: Monkey island
          # Subnodes
          _:
            - floor: Pirate hall
            - floor: Grog storage
            - construction_date: "1990"  # Only strings are valid
      - building: Grog factory

# Consider this XML for following example -
#
# <config>
#   <element name="test1">
#     <text>part to remove</text>
#   </element>
#   <element name="test2">
#     <text>part to keep</text>
#   </element>
# </config>

- name: Delete element node based upon attribute
  community.general.xml:
    path: bar.xml
    xpath: /config/element[@name='test1']
    state: absent

返回值 

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

键	描述
actions dictionary	一个字典，包含原始的 XPath、命名空间和状态。返回：成功示例： `{"namespaces": ["namespace1", "namespace2"], "state=present": null, "xpath": "xpath"}`
backup_file string	已创建的备份文件的名称返回：当 `backup=true` 时示例： `"/path/to/file.xml.1942.2017-08-24@14:16:01~"`
count integer	XPath 匹配的数量。返回：当参数 ‘count’ 设置时示例： `2`
matches list / elements=string	找到的 XPath 匹配项。返回：当参数 ‘print_match’ 设置时
msg string	与执行的操作相关的消息。返回：始终
xmlstring string	结果输出的 XML 字符串。返回：当参数 ‘xmlstring’ 设置时

作者

Tim Bielawa (@tbielawa)
Magnus Hedemark (@magnus919)
Dag Wieers (@dagwieers)

community.general.xml 模块 – 管理 XML 文件或字符串的片段

作者

合集链接