Try SpotterManage bits and pieces of XML files or strings
| "added in version" 2.4 of ansible.builtin"
Authors: Tim Bielawa (@tbielawa), Magnus Hedemark (@magnus919), Dag Wieers (@dagwieers)
preview | supported by community
pipInstall with pip install ansible==2.9.27
A CRUD-like interface to managing bits of XML files.
# 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'
path:
aliases:
- dest
- file
description:
- Path to the file to operate on.
- This file must exist ahead of time.
- This parameter is required, unless C(xmlstring) is given.
required: true
type: path
count:
default: false
description:
- Search for a given C(xpath) and provide the count of any matches.
- This parameter requires C(xpath) to be set.
type: bool
state:
aliases:
- ensure
choices:
- absent
- present
default: present
description:
- Set or remove an xpath selection (node(s), attribute(s)).
type: str
value:
description:
- Desired state of the selected attribute.
- Either a string, or to unset a value, the Python C(None) keyword (YAML Equivalent,
C(null)).
- Elements default to no value (but present).
- Attributes default to an empty string.
type: raw
xpath:
description:
- A valid XPath expression describing the item(s) you want to manipulate.
- Operates on the document root, C(/), by default.
type: str
backup:
default: false
description:
- Create a backup file including the timestamp information so you can get the original
file back if you somehow clobbered it incorrectly.
type: bool
content:
choices:
- attribute
- text
description:
- Search for a given C(xpath) and get content.
- This parameter requires C(xpath) to be set.
type: str
attribute:
description:
- The attribute to select when using parameter C(value).
- This is a string, not prepended with C(@).
type: raw
xmlstring:
description:
- A string containing XML on which to operate.
- This parameter is required, unless C(path) is given.
required: true
type: str
input_type:
choices:
- xml
- yaml
default: yaml
description:
- Type of input for C(add_children) and C(set_children).
type: str
namespaces:
description:
- The namespace C(prefix:uri) mapping for the XPath expression.
- Needs to be a C(dict), not a C(list) of items.
type: dict
insertafter:
default: false
description:
- Add additional child-element(s) after the last selected element for a given C(xpath).
- Child elements must be given in a list and each item may be either a string (eg.
C(children=ansible) to add an empty C(<ansible/>) child element), or a hash where
the key is an element name and the value is the element value.
- This parameter requires C(xpath) to be set.
type: bool
version_added: '2.8'
version_added_collection: ansible.builtin
print_match:
default: false
description:
- Search for a given C(xpath) and print out any matches.
- This parameter requires C(xpath) to be set.
type: bool
add_children:
description:
- Add additional child-element(s) to a selected element for a given C(xpath).
- Child elements must be given in a list and each item may be either a string (eg.
C(children=ansible) to add an empty C(<ansible/>) child element), or a hash where
the key is an element name and the value is the element value.
- This parameter requires C(xpath) to be set.
type: list
insertbefore:
default: false
description:
- Add additional child-element(s) before the first selected element for a given C(xpath).
- Child elements must be given in a list and each item may be either a string (eg.
C(children=ansible) to add an empty C(<ansible/>) child element), or a hash where
the key is an element name and the value is the element value.
- This parameter requires C(xpath) to be set.
type: bool
version_added: '2.8'
version_added_collection: ansible.builtin
pretty_print:
default: false
description:
- Pretty print XML output.
type: bool
set_children:
description:
- Set the child-element(s) of a selected element for a given C(xpath).
- Removes any existing children.
- Child elements must be specified as in C(add_children).
- This parameter requires C(xpath) to be set.
type: list
strip_cdata_tags:
default: false
description:
- 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.
type: bool
version_added: '2.7'
version_added_collection: ansible.builtin
actions:
description: A dictionary with the original xpath, namespaces and state.
returned: success
sample:
namespaces:
- namespace1
- namespace2
state=present: null
xpath: xpath
type: dict
backup_file:
description: The name of the backup file that was created
returned: when backup=yes
sample: /path/to/file.xml.1942.2017-08-24@14:16:01~
type: str
count:
description: The count of xpath matches.
returned: when parameter 'count' is set
sample: 2
type: int
matches:
description: The xpath matches found.
returned: when parameter 'print_match' is set
type: list
msg:
description: A message related to the performed action(s).
returned: always
type: str
xmlstring:
description: An XML string of the resulting output.
returned: when parameter 'xmlstring' is set
type: str