ansible.builtin.first_found 查找 - 从列表中返回第一个找到的文件

注意

此查找插件是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，您可以使用简短的插件名称 first_found。但是，我们建议您使用 完全限定的集合名称 (FQCN) ansible.builtin.first_found 以便轻松链接到插件文档并避免与可能具有相同查找插件名称的其他集合发生冲突。

概要

  • 此查找检查文件和路径列表，并返回找到的第一个组合的完整路径。

  • 与所有查找一样，当提供相对路径时，它会首先尝试使用当前任务的位置，然后向上链遍历角色/剧本/包含的位置，依此类推。

  • 文件列表优先于搜索的路径。例如，角色中的一个任务在剧本的相对路径中有一个“file1”，这将被使用，“file2”在角色的相对路径中将不会被使用。

  • 此插件需要文件列表 _terms 或具有文件列表的键 files 才能运行。

术语

参数

注释

术语

字符串

文件名列表。

关键字参数

这描述了查找的关键字参数。这些是以下示例中的值 key1=value1、key2=value2 等等：lookup('ansible.builtin.first_found', key1=value1, key2=value2, ...) 和 query('ansible.builtin.first_found', key1=value1, key2=value2, ...)

参数

注释

文件

列表 / 元素=字符串

文件名列表。

默认值： []

路径

列表 / 元素=字符串

要查找文件的路径列表。

默认值： []

跳过

布尔值

当 True 时，如果未匹配任何文件，则返回空列表。

这在与 with_first_found 一起使用时很有用，因为对 with_ 调用返回的空列表会导致调用任务被跳过。

当通过 lookup 或 query 作为模板使用时，设置 skip=True *不会* 导致任务跳过。任务必须处理模板返回的空列表。

当 False 并且 lookup 或 query 指定 errors='ignore' 时，所有错误（包括未找到文件，但可能还有其他错误）分别返回空字符串或空列表。

当 True 并且 lookup 或 query 指定 errors='ignore' 时，未找到文件将返回空列表，其他潜在错误将返回空字符串或空列表，具体取决于模板调用（换句话说，返回 lookup 与 query 的返回值）。

选项

  • false ← (默认)

  • 真的

备注

注意

  • 当关键字参数和位置参数一起使用时，位置参数必须列在关键字参数之前：lookup('ansible.builtin.first_found', term1, term2, key1=value1, key2=value2) 和 query('ansible.builtin.first_found', term1, term2, key1=value1, key2=value2)

  • 此查找可以用于“双重模式”，既可以传递文件名列表，也可以传递包含 files 和 paths 的字典。

另请参见

另请参见

任务路径

用于相对路径/文件的搜索路径。

示例

- name: Set _found_file to the first existing file, raising an error if a file is not found
  ansible.builtin.set_fact:
    _found_file: "{{ lookup('ansible.builtin.first_found', findme) }}"
  vars:
    findme:
      - /path/to/foo.txt
      - bar.txt  # will be looked in files/ dir relative to role and/or play
      - /path/to/biz.txt

- name: Set _found_file to the first existing file, or an empty list if no files found
  ansible.builtin.set_fact:
    _found_file: "{{ lookup('ansible.builtin.first_found', files, paths=['/extra/path'], skip=True) }}"
  vars:
    files:
      - /path/to/foo.txt
      - /path/to/bar.txt

- name: Include tasks only if one of the files exist, otherwise skip the task
  ansible.builtin.include_tasks:
    file: "{{ item }}"
  with_first_found:
    - files:
      - path/tasks.yaml
      - path/other_tasks.yaml
      skip: True

- name: Include tasks only if one of the files exists, otherwise skip
  ansible.builtin.include_tasks: '{{ tasks_file }}'
  when: tasks_file != ""
  vars:
    tasks_file: "{{ lookup('ansible.builtin.first_found', files=['tasks.yaml', 'other_tasks.yaml'], errors='ignore') }}"

- name: |
        copy first existing file found to /some/file,
        looking in relative directories from where the task is defined and
        including any play objects that contain it
  ansible.builtin.copy:
    src: "{{ lookup('ansible.builtin.first_found', findme) }}"
    dest: /some/file
  vars:
    findme:
      - foo
      - "{{ inventory_hostname }}"
      - bar

- name: same copy but specific paths
  ansible.builtin.copy:
    src: "{{ lookup('ansible.builtin.first_found', params) }}"
    dest: /some/file
  vars:
    params:
      files:
        - foo
        - "{{ inventory_hostname }}"
        - bar
      paths:
        - /tmp/production
        - /tmp/staging

- name: INTERFACES | Create Ansible header for /etc/network/interfaces
  ansible.builtin.template:
    src: "{{ lookup('ansible.builtin.first_found', findme)}}"
    dest: "/etc/foo.conf"
  vars:
    findme:
      - "{{ ansible_virtualization_type }}_foo.conf"
      - "default_foo.conf"

- name: read vars from first file found, use 'vars/' relative subdir
  ansible.builtin.include_vars: "{{lookup('ansible.builtin.first_found', params)}}"
  vars:
    params:
      files:
        - '{{ ansible_distribution }}.yml'
        - '{{ ansible_os_family }}.yml'
        - default.yml
      paths:
        - 'vars'

返回值

键

描述

返回值

列表 / 元素=路径

找到文件的路径

返回：成功

作者

  • Seth Vidal

提示

每种条目类型的配置条目具有从低到高的优先级顺序。例如，列表中较低的变量将覆盖列表中较高的变量。