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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使没有指定 collections 关键字，也可以使用简短的模块名称 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 显示的相同顺序的属性。 默认情况下，假设 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
备份 布尔值	创建一个备份文件，其中包含时间戳信息，以便您可以在以某种方式错误地覆盖文件后恢复原始文件。 选择 false ← (默认) 真的
校验和 字符串	如果将校验和传递给此参数，则将在下载目标文件后计算其摘要，以确保其完整性并验证传输是否成功完成。格式：<算法>:<校验和|url>，例如 checksum="sha256:D98291AC[...]B6DC7B97", C(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，则将删除目标文件。 如果校验和 URL 需要用户名和密码，则使用 url_username 和 url_password 下载校验和文件。 默认： ""
密码 列表 / 元素=字符串 在 ansible-core 2.14 中添加	要用于请求的 SSL/TLS 密码。 提供列表时，所有密码将按顺序使用 : 连接。 有关详细信息，请参见 OpenSSL 密码列表格式。 可用的密码取决于 Python 和 OpenSSL/LibreSSL 版本。
client_cert 路径	要用于 SSL 客户端身份验证的 PEM 格式证书链文件。 此文件还可以包含密钥，如果包含密钥，则不需要 client_key。
client_key 路径	包含要用于 SSL 客户端身份验证的私钥的 PEM 格式文件。 如果 client_cert 包含证书和密钥，则不需要此选项。
解压缩 布尔值 在 ansible-core 2.14 中添加	是否尝试解压缩 gzip 内容编码的响应。 选择 错误的 true ← (默认)
目的地 路径 / 必需	下载文件的绝对路径。 如果 dest 是一个目录，则使用服务器提供的文件名或（如果没有提供）远程服务器上 URL 的基本名称。如果是目录，则 force 不会生效。 如果 dest 是一个目录，则始终下载该文件（无论 force 和 checksum 选项如何），但仅当内容更改时才会替换。
强制 布尔值	如果为 true 且 dest 不是目录，则始终下载该文件，如果内容更改，则替换该文件。如果为 false，则仅当目标不存在时才下载该文件。通常，仅针对较小的本地文件应为 true。 在 0.6 之前，此模块的行为就像 true 是默认值一样。 选择 false ← (默认) 真的
force_basic_auth 布尔值	强制在初始请求时发送基本身份验证标头。 uri 模块使用的库 httplib2 仅在 Web 服务对初始请求响应 401 状态时才发送身份验证信息。由于某些基本身份验证服务没有正确发送 401，因此登录将失败。 选择 false ← (默认) 真的
组 字符串	应拥有文件系统对象的组的名称，就像传递给 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 ← (默认) 真的
url 字符串 / 必需	以 (http|https|ftp://[user[:pass]]@host.domain[:port]/path) 格式的 HTTP、HTTPS 或 FTP URL。
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。 GSSAPI 的凭据可以使用 url_username/url_password 或使用指定自定义 Kerberos 凭据缓存的 GSSAPI 环境变量 KRB5CCNAME 指定。 即使已安装 NTLM 的 GSSAPI 机制，也不支持 NTLM 身份验证。 选择 false ← (默认) 真的
use_netrc 布尔值 在 ansible-core 2.14 中添加	确定是否使用来自 ~/.netrc 文件的凭据。 默认情况下，.netrc 与基本身份验证标头一起使用。 如果为 false，则忽略 .netrc 凭据。 选择 错误的 true ← (默认)
use_proxy 布尔值	如果为 false，它将不会使用代理，即使在目标主机上环境变量中定义了代理。 选择 错误的 true ← (默认)
validate_certs 布尔值	如果为 false，则不会验证 SSL 证书。 这仅应在使用自签名证书的个人控制的站点上使用。 选择 错误的 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

ansible.windows.win_get_url 模块的官方文档。

示例

- 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"
目的地 字符串	目标文件/路径 已返回：成功 示例： "/path/to/file.txt"
elapsed 整数	执行下载时经过的秒数 返回： 始终 示例： 23
gid 整数	文件的组 ID 已返回：成功 示例： 100
组 字符串	文件的组 已返回：成功 示例： "httpd"
md5sum 字符串	下载后文件的 md5 校验和 返回： 支持时 示例： "2a5aeecc61dc98c4d780b14b330e3282"
mode 字符串	目标的权限 已返回：成功 示例： "0644"
msg 字符串	请求的 HTTP 消息 返回： 始终 示例： "OK (unknown bytes)"
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)

集合链接

• 问题追踪器
• 仓库（源代码）
• 通信