xml – Manage bits and pieces of XML files or strings
xml – Manage bits and pieces of XML files or strings
New in version 2.4.
Synopsis
- A CRUD-like interface to managing bits of XML files.
Requirements
The below requirements are needed on the host that executes this module.
- lxml >= 2.3.0
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
add_children list |
Add additional child-element(s) to a selected element for a given Child elements must be given in a list and each item may be either a string (eg. This parameter requires | |
attribute raw |
The attribute to select when using parameter This is a string, not prepended with | |
backup boolean |
|
Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. |
content string |
|
Search for a given This parameter requires |
count boolean |
|
Search for a given This parameter requires |
input_type string |
|
Type of input for |
insertafter boolean added in 2.8 |
|
Add additional child-element(s) after the last selected element for a given Child elements must be given in a list and each item may be either a string (eg. This parameter requires |
insertbefore boolean added in 2.8 |
|
Add additional child-element(s) before the first selected element for a given Child elements must be given in a list and each item may be either a string (eg. This parameter requires |
namespaces dictionary |
The namespace Needs to be a | |
path path / required |
Path to the file to operate on. This file must exist ahead of time. This parameter is required, unless
| |
pretty_print boolean |
|
Pretty print XML output. |
print_match boolean |
|
Search for a given This parameter requires |
set_children list |
Set the child-element(s) of a selected element for a given Removes any existing children. Child elements must be specified as in This parameter requires | |
state string |
|
Set or remove an xpath selection (node(s), attribute(s)).
|
strip_cdata_tags boolean added in 2.7 |
|
Remove CDATA tags surrounding text values. Note that this might break your XML file if text values contain characters that could be interpreted as XML. |
value raw |
Desired state of the selected attribute. Either a string, or to unset a value, the Python Elements default to no value (but present). Attributes default to an empty string. | |
xmlstring string / required |
A string containing XML on which to operate. This parameter is required, unless | |
xpath string |
A valid XPath expression describing the item(s) you want to manipulate. Operates on the document root, |
Notes
Note
- Use the
--check
and--diff
options when testing your expressions. - The diff output is automatically pretty-printed, so may not reflect the actual file content, only the file structure.
- This module does not handle complicated xpath expressions, so limit xpath selectors to simple expressions.
- Beware that in case your XML elements are namespaced, you need to use the
namespaces
parameter, see the examples. - Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
See Also
See also
- Xml module development community wiki
- More information related to the development of this xml module.
- Introduction to XPath
- A brief tutorial on XPath (w3schools.com).
- XPath Reference document
- The reference documentation on XSLT/XPath (developer.mozilla.org).
Examples
# 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
xml:
path: /foo/bar.xml
xpath: /business/rating/@subjective
state: absent
- name: Set the rating to '11'
xml:
path: /foo/bar.xml
xpath: /business/rating
value: 11
# Retrieve and display the number of nodes
- name: Get count of 'beers' nodes
xml:
path: /foo/bar.xml
xpath: /business/beers/beer
count: yes
register: hits
- debug:
var: hits.count
# Example where parent XML nodes are created automatically
- name: Add a 'phonenumber' element to the 'business' element
xml:
path: /foo/bar.xml
xpath: /business/phonenumber
value: 555-555-1234
- name: Add several more beers to the 'beers' element
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
xml:
path: /foo/bar.xml
xpath: '/business/beers/beer[text()=\"Rochefort 10\"]'
insertbefore: yes
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
xml:
path: /foo/bar.xml
xpath: /business/website/validxhtml
- name: Add an empty 'validatedon' attribute to the 'validxhtml' element
xml:
path: /foo/bar.xml
xpath: /business/website/validxhtml/@validatedon
- name: Add or modify an attribute, add element if needed
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
xml:
path: /foo/bar.xml
xpath: /business/website/validxhtml
content: attribute
register: xmlresp
- name: Show an attribute value
debug:
var: xmlresp.matches[0].validxhtml.validatedon
- name: Remove all children from the 'website' element (option 1)
xml:
path: /foo/bar.xml
xpath: /business/website/*
state: absent
- name: Remove all children from the 'website' element (option 2)
xml:
path: /foo/bar.xml
xpath: /business/website
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'
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'
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
actions dictionary |
success |
A dictionary with the original xpath, namespaces and state.
Sample: {'xpath': 'xpath', 'namespaces': ['namespace1', 'namespace2'], 'state=present': None} |
backup_file string |
when backup=yes |
The name of the backup file that was created
Sample: /path/to/file.xml.1942.2017-08-24@14:16:01~ |
count integer |
when parameter 'count' is set |
The count of xpath matches.
Sample: 2 |
matches list |
when parameter 'print_match' is set |
The xpath matches found.
|
msg string |
always |
A message related to the performed action(s).
|
xmlstring string |
when parameter 'xmlstring' is set |
An XML string of the resulting output.
|
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Tim Bielawa (@tbielawa)
- Magnus Hedemark (@magnus919)
- Dag Wieers (@dagwieers)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/xml_module.html