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

注意

此模块是 ansible.windows 集合（版本 2.5.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了这个集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install ansible.windows。

要在 playbook 中使用它，请指定：ansible.windows.win_get_url。

概要

• 从 HTTP、HTTPS 或 FTP 下载文件到远程服务器。

• 远程服务器必须可以直接访问远程资源。

• 对于非 Windows 目标，请改用 ansible.builtin.get_url 模块。

参数

参数	注释
checksum 字符串	如果将校验和传递给此参数，则在下载目标文件后将计算其摘要，以确保其完整性并验证传输是否成功完成。 此选项不能与checksum_url一起设置。
checksum_algorithm 字符串	指定在计算远程文件和目标文件的校验和时使用的哈希算法。 选项 "md5" "sha1" ←（默认） "sha256" "sha384" "sha512"
checksum_url 字符串	指定一个 URL，其中包含 url 处资源的校验和值。 与 checksum 类似，它用于验证远程传输的完整性。 此选项不能与checksum一起设置。
client_cert 字符串	用于 X509 身份验证的客户端证书 (.pfx) 的路径。此路径可以是文件系统上 pfx 的路径，也可以是 PowerShell 证书路径 Cert:\CurrentUser\My\<thumbprint>。 如果证书文件未受密码保护，则 WinRM 连接必须使用 CredSSP 进行身份验证，或者在任务上使用 become。 当证书受密码保护时，其他身份验证类型可以设置client_cert_password。
client_cert_password 字符串	如果证书受密码保护，则为client_cert的密码。
dest 路径 / 必需	保存 URL 处文件的位置。 请务必包括适当的文件名和扩展名。
follow_redirects 字符串	模块是否应遵循重定向。 all 将遵循所有重定向。 none 将不遵循任何重定向。 safe 将仅遵循“安全”重定向，“安全”意味着客户端仅对要重定向到的 URI 执行 GET 或 HEAD 操作。 当遵循重定向 URL 时，Authorization 标头和任何设置的凭据都将被删除，并且不会重定向。 选项 "all" "none" "safe" ←（默认）
force 布尔值	如果 true，将每次下载文件，并在内容更改时替换该文件。如果 false，则仅在文件不存在或远程文件比本地文件更新时下载该文件。 这是通过发送 http HEAD 请求来检索所请求资源的最后修改时间来实现的，因此要使此操作正常工作，远程 Web 服务器必须支持 HEAD 请求。 选项 false true ←（默认）
force_basic_auth 布尔值	默认情况下，仅当 Web 服务使用 401 状态响应初始请求时，才会发送身份验证标头。由于某些基本身份验证服务不会正确发送 401，因此登录将失败。 此选项强制在原始请求时发送基本身份验证标头。 选项 false ←（默认） true
headers 字典	要在请求上设置的额外标头。 这应该是一个字典，其中键是标头名称，值是该标头的值。
http_agent 字符串	要标识为的标头，通常出现在 Web 服务器日志中。 这将在 HTTP 请求上设置为 User-Agent 标头。 默认值： "ansible-httpget"
maximum_redirection 整数	指定模块将连接重定向到备用 URI 的次数，之后连接将失败。 如果设置为 0 或 follow_redirects 设置为 none，或者在不执行 GET 或 HEAD 时设置为 safe，则会阻止所有重定向。 默认值： 50
proxy_password 字符串	proxy_username 的密码。
proxy_url 字符串	用于请求的显式代理。 默认情况下，请求将使用 IE 定义的代理，除非 use_proxy 设置为 no。
proxy_use_default_credential 布尔值	当使用 NTLM、Kerberos 或 Negotiate 身份验证保护的代理主机进行身份验证时，使用当前用户的凭据。 使用 Basic 身份验证的代理仍然需要通过 proxy_username 和 proxy_password 选项提供显式凭据。 如果使用带密码的 become，使用密码通过 SSH 连接，或使用 CredSSP 或 Kerberos with delegation 通过 WinRM 连接，则该模块只能访问用户的凭据。 如果不使用 become 或上述其他身份验证方法，则不会有可用的默认凭据，并且不会进行代理身份验证。 选项 false ←（默认） true
proxy_username 字符串	用于代理身份验证的用户名。
url 字符串 / 必需	要下载的文件的完整 URL。
url_method 别名: method 字符串	请求的 HTTP 方法。
url_password 字符串	url_username 的密码。
url_timeout 别名: timeout 整数	指定请求在超时之前可以挂起多长时间（以秒为单位）。 设置为 0 以指定无限超时。 默认值: 30
url_username 字符串	用于身份验证的用户名。
use_default_credential 布尔值	当使用 NTLM、Kerberos 或 Negotiate 身份验证保护的服务器进行身份验证时，使用当前用户的凭据。 使用 Basic 身份验证的站点仍然需要通过 url_username 和 url_password 选项提供显式凭据。 如果使用带密码的 become，使用密码通过 SSH 连接，或使用 CredSSP 或 Kerberos with delegation 通过 WinRM 连接，则该模块只能访问用户的凭据。 如果不使用 become 或上述其他身份验证方法，则不会有可用的默认凭据，并且不会进行身份验证。 选项 false ←（默认） true
use_proxy 布尔值	如果为 no，则不会使用 IE 中为当前用户定义的代理。 选项 false true ←（默认）
validate_certs 布尔值	如果为 no，则不会验证 SSL 证书。 这只应在个人控制的使用自签名证书的站点上使用。 选项 false true ←（默认）

注释

注意

• 如果你的 URL 包括转义的斜杠字符 (%2F)，此模块会将其转换为实际的斜杠。这是 System.Uri 类的行为结果，如文档中所述。

另请参阅

另请参阅

ansible.builtin.get_url

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

ansible.builtin.uri

与 Web 服务交互。

ansible.windows.win_uri

与 Web 服务交互。

community.windows.win_inet_proxy

管理 WinINet 和 Internet Explorer 的代理设置。

示例

- name: Download earthrise.jpg to specified path
  ansible.windows.win_get_url:
    url: http://www.example.com/earthrise.jpg
    dest: C:\Users\RandomUser\earthrise.jpg

- name: Download earthrise.jpg to specified path only if modified
  ansible.windows.win_get_url:
    url: http://www.example.com/earthrise.jpg
    dest: C:\Users\RandomUser\earthrise.jpg
    force: false

- name: Download earthrise.jpg to specified path through a proxy server.
  ansible.windows.win_get_url:
    url: http://www.example.com/earthrise.jpg
    dest: C:\Users\RandomUser\earthrise.jpg
    proxy_url: http://10.0.0.1:8080
    proxy_username: username
    proxy_password: password

- name: Download file from FTP with authentication
  ansible.windows.win_get_url:
    url: ftp://server/file.txt
    dest: '%TEMP%\ftp-file.txt'
    url_username: ftp-user
    url_password: ftp-password

- name: Download src with sha256 checksum url
  ansible.windows.win_get_url:
    url: http://www.example.com/earthrise.jpg
    dest: C:\temp\earthrise.jpg
    checksum_url: http://www.example.com/sha256sum.txt
    checksum_algorithm: sha256
    force: true

- name: Download src with sha256 checksum url
  ansible.windows.win_get_url:
    url: http://www.example.com/earthrise.jpg
    dest: C:\temp\earthrise.jpg
    checksum: a97e6837f60cec6da4491bab387296bbcd72bdba
    checksum_algorithm: sha1
    force: true

返回值

通用返回值记录在这里，以下是此模块独有的字段

键	描述
checksum_dest 字符串	下载后文件的 <算法> 校验和 返回: 成功并且已下载目标 示例: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
checksum_src 字符串	远程资源的 <算法> 校验和 返回: force=true 或目标不存在 示例: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
dest 字符串	目标文件/路径 返回: 始终 示例: "C:\\Users\\RandomUser\\earthrise.jpg"
elapsed 浮点数	从轮询开始到模块结束之间经过的秒数。 返回: 始终 示例: 2.1406487
msg 字符串	错误消息，或来自 Web 服务器的 HTTP 状态消息 返回: 始终 示例: "OK"
size 整数	目标文件的大小 返回: 成功 示例: 1220
status_code 整数	HTTP 状态代码 返回: 始终 示例: 200
url 字符串	请求的 URL 返回: 始终 示例: "http://www.example.com/earthrise.jpg"

作者

• Paul Durivage (@angstwad)

• Takeshi Kuramochi (@tksarah)

集合链接

• 问题跟踪器
• 存储库 (源代码)
• 通信