ansible / ansible.builtin / v2.9.27 / module / xml Manage 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 communityansible.builtin.xml (v2.9.27) — module
pip
Install 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