uri – Interacts with webservices
uri – Interacts with webservices
Synopsis
- Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms.
- For Windows targets, use the win_uri module instead.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
body raw |
The body of the http request/response to the web service. If | |
body_format string added in 2.0 |
|
The serialization format of the body. When set to |
client_cert path added in 2.4 |
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 | |
client_key path added in 2.4 |
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. | |
creates path |
A filename, when it already exists, this step will not be run. | |
dest path |
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. | |
follow_redirects string |
|
Whether or not the URI module should follow redirects. |
force boolean |
|
If
|
force_basic_auth boolean |
|
Force the sending of the Basic authentication header upon initial request. The library used by the uri module only sends authentication information when a webservice responds to an initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail. |
HEADER_ dictionary |
Any parameter starting with "HEADER_" is a sent with your request as a header. For example, HEADER_Content-Type="application/json" would send the header "Content-Type" along with your request with a value of "application/json". This option is deprecated as of | |
headers dictionary added in 2.1 |
Add custom HTTP headers to a request in the format of a YAML hash. As of | |
http_agent string |
Default: "ansible-httpget" |
Header to identify as, generally appears in web server logs. |
method string |
Default: "GET" |
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. |
others - |
All arguments accepted by the file module also work here | |
remote_src boolean added in 2.7 |
|
If If |
removes path |
A filename, when it does not exist, this step will not be run. | |
return_content boolean |
|
Whether or not to return the body of the response as a "content" key in the dictionary result. Independently of this option, if the reported Content-type is "application/json", then the JSON is always loaded into a key called |
src path added in 2.7 |
Path to file to be submitted to the remote server. Cannot be used with body. | |
status_code list |
Default: [200] |
A list of valid, numeric, HTTP status codes that signifies success of the request. |
timeout integer |
Default: 30 |
The socket level timeout in seconds |
unix_socket - added in 2.8 |
Path to Unix domain socket to use for connection | |
url string / required |
HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path | |
url_password string |
A password for the module to use for Digest, Basic or WSSE authentication.
| |
url_username string |
A username for the module to use for Digest, Basic or WSSE authentication.
| |
use_proxy boolean |
|
If |
validate_certs boolean |
|
If This should only set to Prior to 1.9.2 the code defaulted to |
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 win_uri module instead.
See Also
See also
- get_url – Downloads files from HTTP, HTTPS, or FTP to node
- The official documentation on the get_url module.
- win_uri – Interacts with webservices
- The official documentation on the win_uri module.
Examples
- name: Check that you can connect (GET) to a page and it returns a status 200
uri:
url: http://www.example.com
- name: Check that a page returns a status 200 and fail if the word AWESOME is not in the page contents
uri:
url: http://www.example.com
return_content: yes
register: this
failed_when: "'AWESOME' not in this.content"
- name: Create a JIRA issue
uri:
url: https://your.jira.example.com/rest/api/2/issue/
user: your_username
password: your_pass
method: POST
body: "{{ lookup('file','issue.json') }}"
force_basic_auth: yes
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
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
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: Connect to website using a previously stored cookie
uri:
url: https://your.form.based.auth.example.com/dashboard.php
method: GET
return_content: yes
headers:
Cookie: "{{ login.set_cookie }}"
- name: Queue build of a project in Jenkins
uri:
url: http://{{ jenkins.host }}/job/{{ jenkins.job }}/build?token={{ jenkins.token }}
user: "{{ jenkins.user }}"
password: "{{ jenkins.password }}"
method: GET
force_basic_auth: yes
status_code: 201
- name: POST from contents of local file
uri:
url: https://httpbin.org/post
method: POST
src: file.json
- name: POST from contents of remote file
uri:
url: https://httpbin.org/post
method: POST
src: /path/to/my/file.json
remote_src: yes
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
elapsed integer |
on success |
The number of seconds that elapsed while performing the download
Sample: 23 |
msg string |
always |
The HTTP message from the request
Sample: OK (unknown bytes) |
redirected boolean |
on success |
Whether the request was redirected
|
status integer |
always |
The HTTP status code from the request
Sample: 200 |
url string |
always |
The actual URL used for the request
Sample: |
Status
- This module is guaranteed to have no backward incompatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Romeo Theriault (@romeotheriault)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/uri_module.html