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 - |
The body of the http request/response to the web service. If | |
body_format - added in 2.0 |
|
The serialization format of the body. When set to |
client_cert - 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 - 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 - |
A filename, when it already exists, this step will not be run. | |
dest - |
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 - |
|
Whether or not the URI module should follow redirects. |
force_basic_auth boolean |
|
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. This option forces the sending of the Basic authentication header upon initial request. |
HEADER_ - |
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 - added in 2.1 |
Add custom HTTP headers to a request in the format of a YAML hash. As of | |
method - |
|
The HTTP method of the request or response. It MUST be uppercase. |
others - |
All arguments accepted by the file module also work here | |
password - |
A password for the module to use for Digest, Basic or WSSE authentication. | |
remote_src boolean added in 2.7 |
|
If |
removes - |
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. If the reported Content-type is "application/json", then the JSON is additionally loaded into a key called |
src - added in 2.7 |
Path to file to be submitted to the remote server. Cannot be used with body. | |
status_code - |
Default: 200 |
A list of valid, numeric, HTTP status codes that signifies success of the request. |
timeout - |
Default: 30 |
The socket level timeout in seconds |
url - / required |
HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path | |
user - |
A username for the module to use for Digest, Basic or WSSE authentication. | |
validate_certs boolean added in 1.9.2 |
|
If |
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.
Examples
- name: Check that you can connect (GET) to a page and it returns a status 200
uri:
url: http://www.example.com
# 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/
method: POST
user: your_username
password: your_pass
body: "{{ lookup('file','issue.json') }}"
force_basic_auth: yes
status_code: 201
body_format: json
# 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
# Same, but now 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
- 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 }}
method: GET
user: "{{ jenkins.user }}"
password: "{{ jenkins.password }}"
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: true
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
msg string |
always |
The HTTP message from the request
Sample: OK (unknown bytes) |
redirected boolean |
always |
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.7/modules/uri_module.html