ansible.builtin.get_url 模块 – 从 HTTP、HTTPS 或 FTP 下载文件到节点

注意

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

概要

• 从 HTTP、HTTPS 或 FTP 下载文件到远程服务器。远程服务器必须可以直接访问远程资源。

• 默认情况下，如果目标主机上设置了环境变量 <protocol>_proxy，请求将通过该代理发送。可以通过为此任务设置变量（请参阅设置环境变量）或使用 use_proxy 选项来覆盖此行为。

• HTTP 重定向可以将 HTTP 重定向到 HTTPS，因此您应该确保两个协议的代理环境都正确。

• 从 Ansible 2.4 开始，当使用 --check 运行时，它将执行 HEAD 请求以验证 URL，但不会下载整个文件或根据哈希验证它，并且会报告不正确的更改状态。

• 对于 Windows 目标，请改用 ansible.windows.win_get_url 模块。

参数

参数	注释
attributes 别名：attr 字符串	生成的 文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上的 chattr 的手册页。 此字符串应包含与 lsattr 显示的顺序相同的属性。 默认情况下假定使用 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
backup 布尔值	创建一个包含时间戳信息的备份文件，以便您在以某种方式错误地覆盖文件时可以恢复原始文件。 选择 false ← (默认) true
checksum 字符串	如果将校验和传递给此参数，则会在下载目标文件后计算其摘要，以确保其完整性并验证传输是否成功完成。格式：<algorithm>:<checksum|url>，例如 checksum="sha256:D98291AC[…]B6DC7B97"，checksum="sha256:http://example.com/path/sha256sum.txt" 如果您担心可移植性，则只有 sha1 算法在所有平台和 Python 版本上都可用。 Python ``hashlib`` 模块负责提供可用的算法。这些选择因 Python 版本和 OpenSSL 版本而异。 在以符合 FIPS 模式运行的系统上，``md5`` 算法可能不可用。 此外，如果将校验和传递给此参数，并且文件存在于 dest 位置下，则将计算 destination_checksum，并且如果校验和等于 destination_checksum，则会跳过文件下载（除非 force 为 true）。如果校验和不等于 destination_checksum，则会删除目标文件。 默认值： ""
ciphers 列表 / 元素=字符串 在 ansible-core 2.14 中添加	用于请求的 SSL/TLS 密码 当提供列表时，所有密码都按顺序使用 : 连接 有关更多详细信息，请参阅OpenSSL 密码列表格式。 可用的密码取决于 Python 和 OpenSSL/LibreSSL 版本
client_cert 路径	用于 SSL 客户端身份验证的 PEM 格式的证书链文件。 此文件也可以包含密钥，如果包含密钥，则不需要 client_key。
client_key 路径	包含您的私钥的 PEM 格式文件，用于 SSL 客户端身份验证。 如果 client_cert 同时包含证书和密钥，则不需要此选项。
decompress 布尔值 在 ansible-core 2.14 中添加	是否尝试解压缩 gzip 内容编码的响应 选择 false true ← (默认)
dest 路径 / 必需	下载文件的绝对路径。 如果 dest 是一个目录，则将使用服务器提供的文件名，或者如果没有提供，则将使用远程服务器上 URL 的基本名称。如果是一个目录，force 将不起作用。 如果 dest 是一个目录，则始终会下载文件（无论 force 和 checksum 选项如何），但仅在内容更改时才会被替换。
force 布尔值	如果 true 且 dest 不是目录，则每次都会下载文件，并在内容更改时替换文件。 如果 false，则仅在目标不存在时才会下载文件。通常，仅对于小的本地文件才应为 true。 在 0.6 版本之前，此模块的行为就像默认值为 true 一样。 选择 false ← (默认) true
force_basic_auth 布尔值	强制在初始请求时发送 Basic 身份验证标头。 httplib2（uri 模块使用的库）仅在 Web 服务以 401 状态响应初始请求时才发送身份验证信息。由于某些基本身份验证服务无法正确发送 401，因此登录将会失败。 选择 false ← (默认) true
group 字符串	应该拥有文件系统对象的所有者的组的名称，就像传递给 chown 的那样。 如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下它可以保留以前的所有权。
headers 字典	以哈希/字典格式向请求添加自定义 HTTP 标头。 哈希/字典格式是在 Ansible 2.6 中添加的。 之前的版本使用 "key:value,key:value" 字符串格式。 "key:value,key:value" 字符串格式已被弃用，并在 2.10 版本中删除。
http_agent 字符串	要标识的标头，通常出现在 Web 服务器日志中。 默认值: "ansible-httpget"
mode 任意	生成的文件系统对象应具有的权限。 对于那些习惯使用 /usr/bin/chmod 的人，请记住，模式实际上是八进制数。您必须向 Ansible 提供足够的信息来正确解析它们。为了获得一致的结果，请引用八进制数（例如，'644' 或 '1777'），以便 Ansible 接收字符串并可以自行将字符串转换为数字。添加前导零（例如，0755）有时可以工作，但在循环和其他某些情况下可能会失败。 如果 Ansible 收到一个不遵循这些规则的数字，则最终会得到一个十进制数字，这将产生意外的结果。 从 Ansible 1.8 开始，模式可以指定为符号模式（例如，u+rwx 或 u=rw,g=r,o=r）。 如果未指定 mode 并且目标文件系统对象不存在，则在设置新创建的文件系统对象的模式时，将使用系统上的默认 umask。 如果未指定 mode 并且目标文件系统对象确实存在，则将使用现有文件系统对象的模式。 指定 mode 是确保使用正确权限创建文件系统对象的最佳方法。有关更多详细信息，请参见 CVE-2020-1736。
owner 字符串	应该拥有文件系统对象的所有者的用户名，就像传递给 chown 的那样。 如果未指定，它将使用当前用户，除非您是 root 用户，在这种情况下它可以保留以前的所有权。 指定数字用户名将被假定为用户 ID 而不是用户名。避免使用数字用户名以避免这种混淆。
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 range。 当设置为 _default 时，如果可用，它将使用策略的 level 部分。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 当设置为 _default 时，如果可用，它将使用策略的 role 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 当设置为 _default 时，如果可用，它将使用策略的 type 部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它会使用 system 策略（如果适用）。 当设置为 _default 时，如果可用，它将使用策略的 user 部分。
timeout 整数	URL 请求的超时时间（秒）。 默认值: 10
tmp_dest 路径	临时文件下载到的绝对路径。 在 Ansible 2.5 或更高版本上运行时，路径默认为 Ansible 的 remote_tmp 设置 在 Ansible 2.5 之前的版本上运行时，它默认为 TMPDIR、TEMP 或 TMP 环境变量或特定于平台的值。 https://docs.pythonlang.cn/3/library/tempfile.html#tempfile.tempdir
unredirected_headers 列表 / 元素=字符串 在 ansible-core 2.12 中添加	一个标头名称列表，这些标头名称不会在后续的重定向请求中发送。 此列表不区分大小写。默认情况下，所有标头都将被重定向。 在某些情况下，列出诸如 Authorization 之类的标头可能是有益的，以避免潜在的凭据泄露。 默认值: []
unsafe_writes 布尔值	影响何时使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统的配置方式或损坏方式会阻止这种情况。一个例子是 docker 挂载的文件系统对象，这些对象无法从容器内部以原子方式更新，并且只能以不安全的方式写入。 当原子操作失败时，此选项允许 Ansible 回退到更新文件系统对象的不安全方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要提示！不安全写入会受到竞争条件的影响，并可能导致数据损坏。 选择 false ← (默认) true
url 字符串 / 必需	HTTP、HTTPS 或 FTP URL，格式为 (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
url_password 别名: password 字符串	用于 HTTP 基本身份验证的密码。 如果未指定 url_username 参数，则不会使用 url_password 参数。 从 2.8 版本开始，您也可以使用此选项的 password 别名。
url_username 别名: username 字符串	用于 HTTP 基本身份验证的用户名。 对于允许空密码的站点，可以使用此参数而无需 url_password。 从 2.8 版本开始，您也可以使用此选项的 username 别名。
use_gssapi 布尔值 在 ansible-core 2.11 中添加	使用 GSSAPI 执行身份验证，通常用于 Kerberos 或通过协商身份验证的 Kerberos。 需要安装 Python 库 gssapi。 可以使用 url_username/url_password 或使用 GSSAPI 环境变量 KRB5CCNAME 来指定 GSSAPI 的凭据，该变量指定自定义 Kerberos 凭据缓存。 即使安装了 NTLM 的 GSSAPI 机制，也不支持 NTLM 身份验证。 选择 false ← (默认) true
use_netrc 布尔值 在 ansible-core 2.14 中添加	确定是否使用来自 ``~/.netrc`` 文件的凭据 默认情况下，.netrc 与基本身份验证标头一起使用 当设置为 False 时，将忽略 .netrc 凭据 选择 false true ← (默认)
use_proxy 布尔值	如果 false，则即使目标主机上的环境变量中定义了代理，也不会使用代理。 选择 false true ← (默认)
validate_certs 布尔值	如果 false，则不会验证 SSL 证书。 此功能仅应在个人控制的、使用自签名证书的站点上使用。 选择 false true ← (默认)

属性

属性	支持	描述
check_mode	支持: 部分支持 更改状态将反映与空源文件的比较结果	可以在 check_mode 下运行，并返回更改状态的预测结果，而无需修改目标。如果不支持，则会跳过该操作。
diff_mode	支持: 不支持	在 diff 模式下，将返回已更改（或在 check_mode 下可能需要更改）的详细信息
platform	平台: posix	可以操作的目标操作系统/系列

说明

注意

• 对于 Windows 目标，请改用 ansible.windows.win_get_url 模块。

参见

参见

ansible.builtin.uri

与 Web 服务交互。

ansible.windows.win_get_url

从 HTTP、HTTPS 或 FTP 下载文件到节点。

示例

- name: Download foo.conf
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    mode: '0440'

- name: Download file and force basic auth
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    force_basic_auth: yes

- name: Download file with custom HTTP headers
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    headers:
      key1: one
      key2: two

- name: Download file with check (sha256)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c

- name: Download file with check (md5)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: md5:66dffb5228a211e61d6d7ef4a86f5758

- name: Download file with checksum url (sha256)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: sha256:http://example.com/path/sha256sum.txt

- name: Download file from a file path
  ansible.builtin.get_url:
    url: file:///tmp/a_file.txt
    dest: /tmp/afilecopy.txt

- name: < Fetch file that requires authentication.
        username/password only available since 2.8, in older versions you need to use url_username/url_password
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    username: bar
    password: '{{ mysecret }}'

返回值

常用返回值已在此处记录 此处，以下是此模块独有的字段

键	描述
backup_file 字符串	下载后创建的备份文件名 返回: 已更改，如果 backup=yes 示例: "/path/to/file.txt.2015-02-12@22:09~"
checksum_dest 字符串	复制后文件的 sha1 校验和 返回: 成功 示例: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
checksum_src 字符串	文件的 sha1 校验和 返回: 成功 示例: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
dest 字符串	目标文件/路径 返回: 成功 示例: "/path/to/file.txt"
elapsed 整数	执行下载所经过的秒数 返回: 始终 示例: 23
gid 整数	文件的组 ID 返回: 成功 示例: 100
group 字符串	文件的组 返回: 成功 示例: "httpd"
md5sum 字符串	下载后文件的 md5 校验和 返回: 在支持时 示例: "2a5aeecc61dc98c4d780b14b330e3282"
mode 字符串	目标的权限 返回: 成功 示例: "0644"
msg 字符串	请求中的 HTTP 消息 返回: 始终 示例: "OK (未知 字节数)"
owner 字符串	文件的所有者 返回: 成功 示例: "httpd"
secontext 字符串	文件的 SELinux 安全上下文 返回: 成功 示例: "unconfined_u:object_r:user_tmp_t:s0"
size 整数	目标的大小 返回: 成功 示例: 1220
src 字符串	下载后使用的源文件 返回: 始终 示例: "/tmp/tmpAdFLdV"
state 字符串	目标的状态 返回: 成功 示例: "file"
status_code 整数	请求中的 HTTP 状态代码 返回: 始终 示例: 200
uid 整数	执行后文件的所有者 ID 返回: 成功 示例: 100
url 字符串	用于请求的实际 URL 返回: 始终 示例: "https://ansible.org.cn/"

作者

• Jan-Piet Mens (@jpmens)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 通信