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

属性 

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

注意 

注意

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

另请参阅 

另请参阅

Xml 模块开发社区维基: 更多与此 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

返回值 

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

键	描述
actions 字典	包含原始 xpath、命名空间和状态的字典。返回: 成功示例: `{"namespaces": ["namespace1", "namespace2"], "state=present": null, "xpath": "xpath"}`
backup_file 字符串	已创建的备份文件的名称返回: 当 `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 字符串	与执行的操作相关的消息。返回: 始终
xmlstring 字符串	结果输出的 XML 字符串。返回: 当设置参数 ‘xmlstring’ 时

作者

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

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

作者

集合链接