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 字符串	生成的 filesystem 对象应具有的属性。 要获取支持的标志，请查看目标系统上 chattr 的 man 手册。 此字符串应包含与 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 设置为 form-multipart，选项 “multipart_encoding” 允许更改 multipart 文件编码。（在 v2.19 中添加）
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 中添加	PEM 格式的文件，其中包含要用于验证的 CA 证书。
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 布尔值	强制在初始请求时发送 Basic 身份验证标头。 当此设置设置为 false 时，此模块将首先尝试未经身份验证的请求，当服务器回复 HTTP 401 错误时，它将提交 Basic 身份验证标头。 当此设置设置为 true 时，此模块将立即在第一个请求中发送 Basic 身份验证标头。 在以下任何情况下使用此设置 您知道 Web 服务端点始终需要 HTTP Basic 身份验证，并且您希望通过消除第一次往返来加快请求速度。 Web 服务没有正确地向您的客户端发送 HTTP 401 错误，因此 Ansible 的 HTTP 库不会正确地使用 HTTP 凭据响应，并且登录将失败。 Web 服务禁止或限制导致任何 HTTP 401 错误的客户端。 选项 false ← (默认) true
group 字符串	应该拥有文件系统对象的用户组的名称，就像传递给 chown 的一样。 如果未指定，则使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留先前的所有权。
headers 字典	以 YAML 哈希格式向请求添加自定义 HTTP 标头。从 Ansible 2.3 开始，在此处提供 Content-Type 将覆盖通过为 body_format 提供 json 或 form-urlencoded 生成的标头。 默认值： {}
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 文件系统对象上下文的角色部分。 当设置为 _default 时，如果可用，它将使用策略的 role 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 当设置为 _default 时，如果可用，它将使用策略的 type 部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 system 策略（如果适用）。 当设置为 _default 时，如果可用，它将使用策略的 user 部分。
src 路径 在 Ansible 2.7 中添加	要提交到远程服务器的文件的路径。 不能与 body 一起使用。 应与 force_basic_auth 一起使用，以确保在远程端发送 401 时成功。
status_code 列表 / 元素=整数	表示请求成功的有效数字 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 URL，格式为 (http|https)://host.domain[:port]/path。
url_password 别名: password 字符串	模块用于摘要式、基本式或 WSSE 身份验证的密码。
url_username 别名: user 字符串	模块用于摘要式、基本式或 WSSE 身份验证的用户名。
use_gssapi 布尔值 在 ansible-core 2.11 中添加	使用 GSSAPI 执行身份验证，通常用于 Kerberos 或通过协商机制的 Kerberos 身份验证。 需要安装 Python 库 gssapi。 GSSAPI 的凭据可以使用 url_username/url_password 指定，或者使用 GSSAPI 环境变量 KRB5CCNAME 指定自定义的 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	支持: 无	在 diff 模式下，将返回已更改内容（或在 check_mode 下可能需要更改的内容）的详细信息
platform	平台: 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
        multipart_encoding: base64
      file2:
        content: text based file content
        filename: fake.txt
        mime_type: text/plain
        multipart_encoding: 7or8bit
      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 字符串	响应正文内容。 返回: 状态不在 status_code 中或 return_content 为 true 示例: "{}"
cookies 字典	放置在 cookie jar 中的 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://ansible.org.cn/"

作者

• Romeo Theriault (@romeotheriault)

集合链接

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