ansible.builtin.uri module – Interacts with webservices
Note
This module is part of ansible-core and included in all Ansible
installations. In most cases, you can use the short
module name
uri even without specifying the collections keyword.
However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.uri for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
Synopsis
Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms.
For Windows targets, use the ansible.windows.win_uri module instead.
Note
This module has a corresponding action plugin.
Parameters
Parameter |
Comments |
|---|---|
The attributes the resulting filesystem object should have. To get supported flags look at the man page for chattr on the target system. This string should contain the attributes in the same order as the one displayed by lsattr. The |
|
The body of the http request/response to the web service. If If If |
|
The serialization format of the body. When set to As of v2.3 it is possible to override the The ‘Content-Type’ header cannot be overridden when using
Choices:
|
|
PEM formatted file that contains a CA certificate to be used for validation |
|
SSL/TLS Ciphers to use for the request. When a list is provided, all ciphers are joined in order with See the OpenSSL Cipher List Format for more details. The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions |
|
PEM formatted certificate chain file to be used for SSL client authentication. This file can also include the key as well, and if the key is included, client_key is not required |
|
PEM formatted file that contains your private key to be used for SSL client authentication. If client_cert contains both the certificate and key, this option is not required. |
|
A filename, when it already exists, this step will not be run. |
|
Whether to attempt to decompress gzip content-encoded responses Choices:
|
|
A path of where to download the file to (if desired). If dest is a directory, the basename of the file on the remote server will be used. |
|
Whether or not the URI module should follow redirects. Choices:
|
|
If Choices:
|
|
Force the sending of the Basic authentication header upon initial request. When this setting is When this setting is Use this setting in any of the following scenarios: You know the webservice endpoint always requires HTTP Basic authentication, and you want to speed up your requests by eliminating the first roundtrip. The web service does not properly send an HTTP 401 error to your client, so Ansible’s HTTP library will not properly respond with HTTP credentials, and logins will fail. The webservice bans or rate-limits clients that cause any HTTP 401 errors. Choices:
|
|
Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
Add custom HTTP headers to a request in the format of a YAML hash. As of Default: |
|
Header to identify as, generally appears in web server logs. Default: |
|
The HTTP method of the request or response. In more recent versions we do not restrict the method at the module level anymore but it still must be a valid method accepted by the service handling the request. Default: |
|
The permissions the resulting filesystem object should have. For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
|
Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
If If Choices:
|
|
A filename, when it does not exist, this step will not be run. |
|
Whether or not to return the body of the response as a “content” key in the dictionary result no matter it succeeded or failed. Independently of this option, if the reported Content-type is “application/json”, then the JSON is always loaded into a key called Choices:
|
|
The level part of the SELinux filesystem object context. This is the MLS/MCS attribute, sometimes known as the When set to |
|
The role part of the SELinux filesystem object context. When set to |
|
The type part of the SELinux filesystem object context. When set to |
|
The user part of the SELinux filesystem object context. By default it uses the When set to |
|
Path to file to be submitted to the remote server. Cannot be used with body. Should be used with force_basic_auth to ensure success when the remote end sends a 401. |
|
A list of valid, numeric, HTTP status codes that signifies success of the request. Default: |
|
The socket level timeout in seconds Default: |
|
Path to Unix domain socket to use for connection |
|
A list of header names that will not be sent on subsequent redirected requests. This list is case insensitive. By default all headers will be redirected. In some cases it may be beneficial to list headers such as Default: |
|
Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. Choices:
|
|
HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path |
|
A password for the module to use for Digest, Basic or WSSE authentication. |
|
A username for the module to use for Digest, Basic or WSSE authentication. |
|
Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos through Negotiate authentication. Requires the Python library gssapi to be installed. Credentials for GSSAPI can be specified with url_username/url_password or with the GSSAPI env var NTLM authentication is Choices:
|
|
Determining whether to use credentials from ``~/.netrc`` file By default .netrc is used with Basic authentication headers When set to False, .netrc credentials are ignored Choices:
|
|
If Choices:
|
|
If This should only set to Prior to 1.9.2 the code defaulted to Choices:
|
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: none |
Can run in check_mode and return changed status prediction without modifying target |
|
Support: none |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platform: posix |
Target OS/families that can be operated against |
Notes
Note
The dependency on httplib2 was removed in Ansible 2.1.
The module returns all the HTTP headers in lower-case.
For Windows targets, use the ansible.windows.win_uri module instead.
See Also
See also
- ansible.builtin.get_url
Downloads files from HTTP, HTTPS, or FTP to node.
- ansible.windows.win_uri
Interacts with webservices.
Examples
- 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'
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
The response body content. Returned: status not in status_code or return_content is true Sample: |
|
The cookie values placed in cookie jar. Returned: on success Sample: |
|
The value for future request Cookie headers. Returned: on success Sample: |
|
The number of seconds that elapsed while performing the download. Returned: on success Sample: |
|
The HTTP message from the request. Returned: always Sample: |
|
destination file/path Returned: dest is defined Sample: |
|
Whether the request was redirected. Returned: on success Sample: |
|
The HTTP status code from the request. Returned: always Sample: |
|
The actual URL used for the request. Returned: always Sample: |