community.general.xml_info module – Query XML files or strings

Note

This module is part of the community.general collection (version 13.2.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.xml_info.

New in community.general 13.2.0

Synopsis 

A read-only interface to query XML files or strings using XPath expressions.
Supports counting matches, listing matched XPath paths, and retrieving element text or attributes.

Requirements 

The below requirements are needed on the host that executes this module.

lxml >= 2.3.0

Parameters 

Parameter	Comments
count_mode string	How to determine the count of XPath matches when `what=count`. `match` evaluates the XPath expression and counts the results with Python’s `len()`. This is always correct for any XPath expression. `xpath` uses the XPath `count()` function, which is more memory-efficient for large result sets since it does not build the full list of matches in memory. However, it may produce different results for XPath expressions that do not return node-sets. This option is only used when `what=count`. For other `what` values, the count is always derived from the number of returned items. Choices: `"match"` ← (default) `"xpath"`
huge_tree boolean	Disable libxml2 security restrictions on XML node size or document depth, allowing processing of very large XML files. This option should only be activated when needed, as it disables internal safety limits. Choices: `false` ← (default) `true`
namespaces dictionary	The namespace `prefix:uri` mapping for the XPath expression. Needs to be a `dict`, not a `list` of items. Default: `{}`
path aliases: dest, file path	Path to the file to operate on. This file must exist ahead of time. This parameter is required, unless `xmlstring` is given.
strip_cdata_tags boolean	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. Choices: `false` ← (default) `true`
what string / required	Select what kind of information to return for the given `xpath`. Choices: `"content_attributes"`: Return the attributes of the matched elements as `content_attributes`. `"content_text"`: Return the text content of the matched elements as `content_text`. `"count"`: Returns the number of matches as `count`. `"paths"`: Return the XPath paths for all matched elements as `matches`.
xmlstring string	A string containing XML on which to operate. This parameter is required, unless `path` is given.
xpath string / required	A valid XPath expression describing the item(s) you want to operate on. Operates on the document root, `/`, by default.

Attributes 

Attribute	Support	Description
check_mode	Support: full This action does not modify state.	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: N/A This action does not modify state.	Returns details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Notes 

Note

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.

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>https://tastybeverageco.com</address>
#   </website>
# </business>

# Retrieve and display the number of nodes
- name: Get count of 'beers' nodes
  community.general.xml_info:
    path: /foo/bar.xml
    xpath: /business/beers/beer
    what: count
  register: hits

- name: Show count
  ansible.builtin.debug:
    var: hits.count

# Retrieve and display the matching XPath paths
- name: Get matching paths for 'beer' nodes
  community.general.xml_info:
    path: /foo/bar.xml
    xpath: /business/beers/beer
    what: paths
  register: hits

- name: Show matching paths
  ansible.builtin.debug:
    var: hits.matches

# How to read attribute values and access them in Ansible
- name: Read an element's attribute values
  community.general.xml_info:
    path: /foo/bar.xml
    xpath: /business/rating
    what: content_attributes
  register: xmlresp

- name: Show an attribute value
  ansible.builtin.debug:
    var: xmlresp.content_attributes[0].attributes.subjective

# How to read text content
- name: Read an element's text content
  community.general.xml_info:
    path: /foo/bar.xml
    xpath: /business/rating
    what: content_text
  register: xmlresp

- name: Show text content
  ansible.builtin.debug:
    var: xmlresp.content_text[0].text

# Using an XML string instead of a file
- name: Count nodes in an XML string
  community.general.xml_info:
    xmlstring: "<config><item>1</item><item>2</item></config>"
    xpath: /config/item
    what: count
  register: hits

# Using namespaces
- name: Count nodes in a namespaced XML file
  community.general.xml_info:
    path: /foo/bar.xml
    xpath: /x:foo/x:bar/y:baz
    namespaces:
      x: http://x.test
      y: http://y.test
    what: count
  register: hits

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
content_attributes list / elements=dictionary	The attributes of matched elements. Returned: when `what=content_attributes` Sample: `[{"attributes": {"subjective": "true"}, "tag": "rating"}]`
attributes dictionary	The attributes of the matched element as key-value pairs. Returned: always
tag string	The tag name of the matched element. Returned: always
content_text list / elements=dictionary	The text content of matched elements. Returned: when `what=content_text` Sample: `[{"tag": "beer", "text": "Rochefort 10"}]`
tag string	The tag name of the matched element. Returned: always
text string	The text content of the matched element. Returned: always
count integer	The count of xpath matches. Returned: success Sample: `2`
matches list / elements=string	The XPath paths of matched nodes. Returned: when `what=paths` Sample: `["/business/beers/beer[1]", "/business/beers/beer[2]"]`

Authors

Tim Bielawa (@tbielawa)
Magnus Hedemark (@magnus919)
Dag Wieers (@dagwieers)
Shreyash Bhosale (@Shreyashxredhat)

community.general.xml_info module – Query XML files or strings

Synopsis 

Requirements 

Parameters 

Attributes 

Notes 

See Also 

Examples 

Return Values 

Authors

Collection links