New in version 2.4.
The below requirements are needed on the host that executes this module.
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 bool |
| 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 bool |
| 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 bool |
| Pretty print XML output. |
print_match bool |
| 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 bool (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. |
Note
--check
and --diff
options when testing your expressions.namespaces
parameter.- 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'
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
actions dict | success | A dictionary with the original xpath, namespaces and state. Sample: {'xpath': 'xpath', 'state=present': None, 'namespaces': ['namespace1', 'namespace2']} |
backup_file str | 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 int | 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. |
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.
For a list of other modules that are also maintained by the Ansible Community, see here.
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/xml_module.html