xml - Управление фрагментами XML-файлов или строк

Новая версия 2.4.

Описание
- Требования
Параметры
Примечания
Примеры
Возвращаемые значения
Статус
- Автор

Описание

Интерфейс типа CRUD для управления фрагментами XML-файлов.
Возможно, вас также заинтересует краткий учебник по https://www.w3schools.com/xml/xpath_intro.asp и https://developer.mozilla.org/en-US/docs/Web/XPath.

Требования

Ниже перечислены требования к хосту, на котором выполняется этот модуль.

lxml >= 2.3.0

Параметры

Параметр	Варианты/Значения по умолчанию	Комментарии
add_children		Добавить дополнительные дочерние элементы к выбранному элементу для заданного `xpath`. Дочерние элементы должны быть указаны в списке, и каждый элемент может быть либо строкой (например, `children=ansible`, чтобы добавить пустой `<ansible/>` дочерний элемент), либо словарем, где ключ — имя элемента, а значение — значение элемента. Этот параметр требует, чтобы был задан `xpath`.
attribute		Атрибут для выбора при использовании параметра `value`. Это строка, не начинающаяся с `@`.
backup	Варианты: нет ← да	Создать резервную копию файла, включая информацию о дате и времени, чтобы вы могли вернуть исходный файл, если вы неправильно его испортили.
content	Варианты: атрибут текст	Искать заданный `xpath` и получить содержимое. Этот параметр требует, чтобы был задан `xpath`.
count	Варианты: нет ← да	Искать заданный `xpath` и предоставить количество совпадений. Этот параметр требует, чтобы был задан `xpath`.
input_type	Варианты: xml yaml ←	Тип входных данных для `add_children` и `set_children`.
namespaces		Сопоставление `prefix:uri` пространства имен для выражения XPath. Должен быть `dict`, а не `list` элементов.
path обязательно		Путь к файлу, над которым нужно выполнить операцию. Файл должен существовать. Этот параметр является обязательным, если не задан `xmlstring`. псевдонимы: dest, file
pretty_print	Варианты: нет ← да	Форматированный вывод XML.
print_match	Варианты: нет ← да	Искать заданный `xpath` и выводить все совпадения. Этот параметр требует, чтобы был задан `xpath`.
set_children		Установить дочерние элементы выбранного элемента для заданного `xpath`. Удаляет все существующие дочерние элементы. Дочерние элементы должны быть заданы так же, как и в `add_children`. Этот параметр требует, чтобы был задан `xpath`.
state	Варианты: отсутствует присутствует ←	Установить или удалить выбор XPath (узел(ы), атрибут(ы)). псевдонимы: ensure
value		Желаемое состояние выбранного атрибута. Это может быть строка, или, чтобы удалить значение, ключевое слово Python `None` (эквивалент YAML, `null`). Элементы по умолчанию не имеют значения (но присутствуют). Атрибуты по умолчанию — пустая строка.
xmlstring обязательно		Строка, содержащая XML, над которым нужно выполнить операцию. Этот параметр является обязательным, если не задан `path`.
xpath	Значение по умолчанию: /	Действительное выражение XPath, описывающее элемент(ы), которые вы хотите изменить. По умолчанию работает с корнем документа, `/`.

Примечания

Примечание

Используйте параметры --check и --diff при тестировании выражений.
Вывод diff автоматически форматируется, поэтому может не отражать фактическое содержимое файла, а только его структуру.
Этот модуль не обрабатывает сложные выражения XPath, поэтому ограничьте выражения XPath простыми выражениями.
Обратите внимание, что в случае, если ваши XML-элементы имеют имена пространств имён, вам нужно использовать параметр namespaces.
Префикс пространства имён должен использоваться для всех дочерних элементов элемента, где определено пространство имён, если не определено другое пространство имён для них.
Дополнительную информацию об этом модуле можно найти в вики-проекте сообщества по адресу https://github.com/ansible/community/wiki/Module:-xml

Примеры

- 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 attrribute 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'

Возвращаемые значения

Общие возвращаемые значения описаны в этом разделе, а следующие поля уникальны для данного модуля:

Ключ	Возвращаемое значение	Описание
actions словарь	успех	Словарь с исходным XPath, пространствами имён и состоянием. Пример: {'xpath': 'xpath', 'state=present': None, 'namespaces': ['namespace1', 'namespace2']}
backup_file строка	при backup=да	Имя созданного резервного файла. Пример: /path/to/file.xml.1942.2017-08-24@14:16:01~
count целое число	при заданном параметре 'count'	Количество совпадений XPath. Пример: 2
matches список	при заданном параметре 'print_match'	Найденные совпадения XPath.
msg строка	всегда	Сообщение, связанное с выполненными действиями.
xmlstring строка	при заданном параметре 'xmlstring'	XML-строка результирующего вывода.

Статус

Этот модуль помечен как превью, что означает, что его интерфейс не гарантирует обратную совместимость.

Автор

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

Подсказка

Если вы обнаружите какие-либо проблемы в данной документации, вы можете отредактировать этот документ, чтобы улучшить его.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.5/modules/xml_module.html