ansible.builtin.uri 模块 - 与 Web 服务交互

注意

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

概要 

与 HTTP 和 HTTPS Web 服务交互，并支持 Digest、Basic 和 WSSE HTTP 身份验证机制。
对于 Windows 目标，请改用 ansible.windows.win_uri 模块。

注意

此模块有一个对应的操作插件。

参数 

参数	注释
attributes 别名：attr 字符串	结果文件系统对象应具有的属性。要获得支持的标志，请查看目标系统上 `chattr` 的手册页。此字符串应包含与 `lsattr` 显示的顺序相同的属性。默认情况下假定使用 `=` 运算符，否则需要在字符串中包含 `+` 或 `-` 运算符。
body 任何	对 Web 服务的 HTTP 请求/响应的主体。如果 `body_format` 设置为 `json`，它将采用已格式化的 JSON 字符串，或将数据结构转换为 JSON。如果 `body_format` 设置为 `form-urlencoded`，它将把字典或元组列表转换为 `application/x-www-form-urlencoded` 字符串。（在 v2.7 中添加）如果 `body_format` 设置为 `form-multipart`，它将把字典转换为 `multipart/form-multipart` 主体。（在 v2.10 中添加）
body_format 字符串	主体的序列化格式。当设置为 `json`、`form-multipart` 或 `form-urlencoded` 时，会对 body 参数进行编码（如果需要），并自动设置 `Content-Type` 标头。从 v2.3 开始，可以通过 `headers` 选项覆盖 `Content-Type` 标头，当设置为 `json` 或 `form-urlencoded` 时。使用 `form-multipart` 时无法覆盖 `Content-Type` 标头。 `form-urlencoded` 添加在 v2.7 中。 `form-multipart` 添加在 v2.10 中。选项 `"form-urlencoded"` `"json"` `"raw"` ← (默认) `"form-multipart"`
ca_path 路径在 ansible-core 2.11 中添加	包含用于验证的 CA 证书的 PEM 格式文件。
ciphers 列表 / 元素=字符串在 ansible-core 2.14 中添加	用于请求的 SSL/TLS 密码。当提供列表时，所有密码将按顺序使用 `:` 连接。有关更多详细信息，请参见 OpenSSL 密码列表格式。可用的密码取决于 Python 和 OpenSSL/LibreSSL 版本。
client_cert 路径	用于 SSL 客户端身份验证的 PEM 格式证书链文件。此文件也可以包含密钥，如果包含密钥，则不需要 `client_key`。
client_key 路径	包含用于 SSL 客户端身份验证的私钥的 PEM 格式文件。如果 `client_cert` 包含证书和密钥，则不需要此选项。
creates 路径	文件名，当它已存在时，此步骤将不会运行。
decompress 布尔值在 ansible-core 2.14 中添加	是否尝试解压缩 gzip 压缩编码的响应。选项 `false` `true` ← (默认)
dest 路径	下载文件的路径（如果需要）。如果 `dest` 是目录，则将使用远程服务器上文件的基名。
follow_redirects 字符串	URI 模块是否应该跟随重定向。选项 `"all"`: 将跟随所有重定向。 `"no"`: (已弃用，在 2.22 中删除) `none` 的别名。 `"none"`: 不会跟随任何重定向。 `"safe"` (默认): 只会跟随执行 GET 或 HEAD 请求的重定向。 `"urllib2"`: 委托给 urllib2 行为（在编写本文时，它遵循 HTTP 重定向）。 `"yes"`: (已弃用，在 2.22 中删除) `all` 的别名。
force 布尔值	如果 `true` 则不获取缓存的副本。选项 `false` ← (默认) `true`
force_basic_auth 布尔值	强制在初始请求时发送基本身份验证标头。当此设置设置为 `false` 时，此模块将首先尝试进行未经身份验证的请求，如果服务器返回 `HTTP 401` 错误，它将提交基本身份验证标头。当此设置设置为 `true` 时，此模块将在第一个请求中立即发送基本身份验证标头。在以下任何情况下使用此设置您知道 Web 服务端点始终需要 HTTP 基本身份验证，并且您希望通过消除第一个往返来加快请求速度。 Web 服务没有正确地向您的客户端发送 HTTP 401 错误，因此 Ansible 的 HTTP 库不会正确地使用 HTTP 凭据进行响应，并且登录将失败。 Web 服务禁止或限制导致任何 HTTP 401 错误的客户端。选项 `false` ← (默认) `true`
group 字符串	应该拥有文件系统对象的组的名称，与传递给 `chown` 的名称相同。如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留以前的拥有权。
headers 字典	以 YAML 哈希格式向请求添加自定义 HTTP 标头。从 Ansible 2.3 开始，在此处提供 `Content-Type` 将覆盖通过提供 `json` 或 `form-urlencoded` 为 `body_format` 生成的标头。默认值： `{}`
http_agent 字符串	用于识别的标头，通常出现在 Web 服务器日志中。默认值： `"ansible-httpget"`
method 字符串	请求或响应的 HTTP 方法。在较新的版本中，我们不再在模块级别限制方法，但它仍然必须是处理请求的服务接受的有效方法。默认值： `"GET"`
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，而不是用户名。避免使用数字用户名以避免此混淆。
remote_src 布尔值在 Ansible 2.7 中添加	如果设置为 `false`，该模块将在控制器节点上搜索 `src`。如果设置为 `true`，该模块将在受管（远程）节点上搜索 `src`。选项 `false` ← (默认) `true`
removes 路径	文件名，如果它不存在，则不会运行此步骤。
return_content 布尔值	无论成功还是失败，是否将响应正文作为字典结果中的“content”键返回。独立于此选项，如果报告的 `Content-Type` 为 `application/json`，则 JSON 始终加载到字典结果中名为 `json` 的键中。选项 `false` ← (默认) `true`
selevel 字符串	SELinux 文件系统对象上下文的级别部分。这是 MLS/MCS 属性，有时称为 `range`。如果设置为 `_default`，它将使用策略的 `level` 部分（如果可用）。
serole 字符串	SELinux 文件系统对象上下文的 role 部分。如果设置为 `_default`，它将使用策略的 `role` 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的 type 部分。如果设置为 `_default`，它将使用策略的 `type` 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的 user 部分。默认情况下，它使用 `system` 策略（如果适用）。如果设置为 `_default`，它将使用策略的 `user` 部分（如果可用）。
src 路径在 Ansible 2.7 中添加	要提交到远程服务器的文件的路径。不能与 `body` 一起使用。应与 `force_basic_auth` 一起使用，以确保远程端发送 401 时成功。
status_code list / elements=integer	表示请求成功的有效数字 HTTP 状态码列表。默认值： `[200]`
timeout 整数	套接字级别超时（以秒为单位）默认值： `30`
unix_socket 路径在 Ansible 2.8 中添加	要用于连接的 Unix 域套接字的路径。
unredirected_headers 列表 / 元素=字符串在 ansible-core 2.12 中添加	不会在随后的重定向请求中发送的标头名称列表。此列表不区分大小写。默认情况下，所有标头都将被重定向。在某些情况下，将诸如 `Authorization` 之类的标头列在此处可能是有益的，以避免潜在的凭据泄露。默认值： `[]`
unsafe_writes 布尔值	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统会以阻止此操作的方式进行配置或只是出现故障。一个例子是 docker 挂载的文件系统对象，这些对象无法从容器内部以原子方式更新，只能以不安全的方式写入。此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。重要！不安全写入会受到竞争条件的影响，并可能导致数据损坏。选项 `false` ← (默认) `true`
url 字符串 / 必需	以 (http\|https)://host.domain[:port]/path 格式的 HTTP 或 HTTPS URL。
url_password 别名：password 字符串	模块用于摘要、基本或 WSSE 身份验证的密码。
url_username 别名：user 字符串	模块用于摘要、基本或 WSSE 身份验证的用户名。
use_gssapi 布尔值在 ansible-core 2.11 中添加	使用 GSSAPI 执行身份验证，通常用于 Kerberos 或通过 Negotiate 身份验证的 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`。在 1.9.2 之前，代码默认设置为 `false`。选项 `false` `true` ← (默认)

属性 

属性	支持	描述
check_mode	支持: 不支持	可以在 check_mode 下运行并返回更改状态预测，而无需修改目标，如果不支持，则操作将被跳过。
diff_mode	支持: 不支持	将在差异模式下返回有关已更改内容（或可能在 check_mode 中需要更改的内容）的详细信息
平台	平台: posix	可以针对其进行操作的目标操作系统/系列

备注 

注意

Ansible 2.1 中删除了对 httplib2 的依赖。
该模块以小写形式返回所有 HTTP 标头。
对于 Windows 目标，请改用 ansible.windows.win_uri 模块。

另请参阅 

另请参阅

ansible.builtin.get_url: 从 HTTP、HTTPS 或 FTP 下载文件到节点。
ansible.windows.win_uri: 有关 **ansible.windows.win_uri** 模块的官方文档。

示例 

- name: Check that you can connect (GET) to a page and it returns a status 200
  ansible.builtin.uri:
    url: http://www.example.com

- name: Check that a page returns successfully but fail if the word AWESOME is not in the page contents
  ansible.builtin.uri:
    url: http://www.example.com
    return_content: true
  register: this
  failed_when: this is failed or "'AWESOME' not in this.content"

- name: Create a JIRA issue
  ansible.builtin.uri:
    url: https://your.jira.example.com/rest/api/2/issue/
    user: your_username
    password: your_pass
    method: POST
    body: "{{ lookup('ansible.builtin.file','issue.json') }}"
    force_basic_auth: true
    status_code: 201
    body_format: json

- name: Login to a form based webpage, then use the returned cookie to access the app in later tasks
  ansible.builtin.uri:
    url: https://your.form.based.auth.example.com/index.php
    method: POST
    body_format: form-urlencoded
    body:
      name: your_username
      password: your_password
      enter: Sign in
    status_code: 302
  register: login

- name: Login to a form based webpage using a list of tuples
  ansible.builtin.uri:
    url: https://your.form.based.auth.example.com/index.php
    method: POST
    body_format: form-urlencoded
    body:
    - [ name, your_username ]
    - [ password, your_password ]
    - [ enter, Sign in ]
    status_code: 302
  register: login

- name: Upload a file via multipart/form-multipart
  ansible.builtin.uri:
    url: https://httpbin.org/post
    method: POST
    body_format: form-multipart
    body:
      file1:
        filename: /bin/true
        mime_type: application/octet-stream
      file2:
        content: text based file content
        filename: fake.txt
        mime_type: text/plain
      text_form_field: value

- name: Connect to website using a previously stored cookie
  ansible.builtin.uri:
    url: https://your.form.based.auth.example.com/dashboard.php
    method: GET
    return_content: true
    headers:
      Cookie: "{{ login.cookies_string }}"

- name: Queue build of a project in Jenkins
  ansible.builtin.uri:
    url: http://{{ jenkins.host }}/job/{{ jenkins.job }}/build?token={{ jenkins.token }}
    user: "{{ jenkins.user }}"
    password: "{{ jenkins.password }}"
    method: GET
    force_basic_auth: true
    status_code: 201

- name: POST from contents of local file
  ansible.builtin.uri:
    url: https://httpbin.org/post
    method: POST
    src: file.json

- name: POST from contents of remote file
  ansible.builtin.uri:
    url: https://httpbin.org/post
    method: POST
    src: /path/to/my/file.json
    remote_src: true

- name: Create workspaces in Log analytics Azure
  ansible.builtin.uri:
    url: https://www.mms.microsoft.com/Embedded/Api/ConfigDataSources/LogManagementData/Save
    method: POST
    body_format: json
    status_code: [200, 202]
    return_content: true
    headers:
      Content-Type: application/json
      x-ms-client-workspace-path: /subscriptions/{{ sub_id }}/resourcegroups/{{ res_group }}/providers/microsoft.operationalinsights/workspaces/{{ w_spaces }}
      x-ms-client-platform: ibiza
      x-ms-client-auth-token: "{{ token_az }}"
    body:

- name: Pause play until a URL is reachable from this host
  ansible.builtin.uri:
    url: "http://192.0.2.1/some/test"
    follow_redirects: none
    method: GET
  register: _result
  until: _result.status == 200
  retries: 720 # 720 * 5 seconds = 1hour (60*60/5)
  delay: 5 # Every 5 seconds

- name: Provide SSL/TLS ciphers as a list
  uri:
    url: https://example.org
    ciphers:
      - '@SECLEVEL=2'
      - ECDH+AESGCM
      - ECDH+CHACHA20
      - ECDH+AES
      - DHE+AES
      - '!aNULL'
      - '!eNULL'
      - '!aDSS'
      - '!SHA1'
      - '!AESCCM'

- name: Provide SSL/TLS ciphers as an OpenSSL formatted cipher list
  uri:
    url: https://example.org
    ciphers: '@SECLEVEL=2:ECDH+AESGCM:ECDH+CHACHA20:ECDH+AES:DHE+AES:!aNULL:!eNULL:!aDSS:!SHA1:!AESCCM'

返回值 

常见返回值记录在此处，以下是此模块特有的字段

键	描述
content 字符串	响应主体内容。返回: 状态不在状态代码中或 return_content 为真示例: `"{}"`
cookies 字典	放置在 cookie 罐中的 cookie 值。返回: 成功时示例: `{"SESSIONID": "[SESSIONID]"}`
cookies_string 字符串	未来请求 Cookie 标头的值。返回: 成功时示例: `"SESSIONID=[SESSIONID]"`
elapsed 整数	执行下载所花费的秒数。返回: 成功时示例: `23`
msg 字符串	来自请求的 HTTP 消息。返回: 始终示例: `"OK (unknown bytes)"`
路径字符串	目标文件/路径返回: dest 已定义示例: `"/path/to/file.txt"`
redirected 布尔值	请求是否被重定向。返回: 成功时示例: `false`
status 整数	来自请求的 HTTP 状态代码。返回: 始终示例: `200`
url 字符串	用于请求的实际 URL。返回: 始终示例: `"https://www.ansible.org.cn/"`

作者

Romeo Theriault (@romeotheriault)