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.
- You might also be interested in a brief tutorial from https://www.w3schools.com/xml/xpath_intro.asp and https://developer.mozilla.org/en-US/docs/Web/XPath.
Requirements
The below requirements are needed on the host that executes this module.
- lxml >= 2.3.0
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
add_children
-
|
Add additional child-element(s) to a selected element for a given
xpath .
Child elements must be given in a list and each item may be either a string (eg.
children=ansible to add an empty
<ansible/> child element), or a hash where the key is an element name and the value is the element value.
This parameter requires
xpath to be set.
|
|
attribute
-
|
The attribute to select when using parameter
value .
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
-
|
|
Search for a given
xpath and get content.
This parameter requires
xpath to be set.
|
count
boolean
|
|
Search for a given
xpath and provide the count of any matches.
This parameter requires
xpath to be set.
|
input_type
-
|
|
Type of input for
add_children and
set_children .
|
namespaces
-
|
The namespace
prefix:uri mapping for the XPath expression.
Needs to be a
dict , not a
list of items.
|
|
path
- /
required
|
Path to the file to operate on. File must exist ahead of time.
This parameter is required, unless
xmlstring is given.
aliases: dest, file |
|
pretty_print
boolean
|
|
Pretty print XML output.
|
print_match
boolean
|
|
Search for a given
xpath and print out any matches.
This parameter requires
xpath to be set.
|
set_children
-
|
Set the child-element(s) of a selected element for a given
xpath .
Removes any existing children.
Child elements must be specified as in
add_children .
This parameter requires
xpath to be set.
|
|
state
-
|
|
Set or remove an xpath selection (node(s), attribute(s)).
aliases: ensure |
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
-
|
Desired state of the selected attribute.
Either a string, or to unset a value, the Python
None keyword (YAML Equivalent,
null ).
Elements default to no value (but present).
Attributes default to an empty string.
|
|
xmlstring
- /
required
|
A string containing XML on which to operate.
This parameter is required, unless
path is given.
|
|
xpath
-
|
A valid XPath expression describing the item(s) you want to manipulate.
Operates on the document root,
/ , by default.
|
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. - Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
- More information about this module is available from the community wiki at https://github.com/ansible/community/wiki/Module:-xml
Examples
- 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 - 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 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 attribute value xml: path: /foo/bar.xml xpath: /business/website/validxhtml content: attribute attribute: validatedon register: xmlresp - name: Show 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 explicitely stated # NOTE: there's the prefix "x" in front of the "bar", too #<?xml version='1.0' encoding='UTF-8'?> #<foo xmlns="http://x.test" xmlns:attr="http://z.test"> # <bar> # <baz xmlns="http://y.test" attr:my_namespaced_attribute="true" /> # </bar> #</foo> - 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)
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/xml_module.html