uri – Interacts with webservices — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# uri – Interacts with webservices

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Return Values
- Status

## 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` is set to 'json' it will take an already formatted JSON string or convert a data structure into JSON. If `body_format` is set to 'form-urlencoded' it will convert a dictionary or list of tuples into an 'application/x-www-form-urlencoded' string. (Added in v2.7)
body_format string added in 2.0 | Choices: form-urlencoded json raw ← | The serialization format of the body. When set to `json` or `form-urlencoded`, encodes the body argument, if needed, and automatically sets the Content-Type header accordingly. As of `2.3` it is possible to override the `Content-Type` header, when set to `json` or `form-urlencoded` via the headers option.
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 | Choices: all none safe ← | Whether or not the URI module should follow redirects. `all` will follow all redirects. `safe` will follow only "safe" redirects, where "safe" means that the client is only doing a GET or HEAD on the URI to which it is being redirected. `none` will not follow any redirects. Note that `yes` and `no` choices are accepted for backwards compatibility, where `yes` is the equivalent of `all` and `no` is the equivalent of `safe`. `yes` and `no` are deprecated and will be removed in some future version of Ansible.
force boolean | Choices: no ← yes | If `yes` do not get a cached copy. aliases: thirsty
force_basic_auth boolean | Choices: no ← yes | 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 `2.1` and will be removed in Ansible 2.9. Use headers instead.
headers dictionary added in 2.1 |  | Add custom HTTP headers to a request in the format of a YAML hash. As of `2.3` supplying `Content-Type` here will override the header generated by supplying `json` or `form-urlencoded` for body_format.
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 | Choices: no ← yes | If `no`, the module will search for src on originating/master machine. If `yes` the module will use the `src` path on the remote/target machine.
removes path |  | A filename, when it does not exist, this step will not be run.
return_content boolean | Choices: no ← yes | 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 `json` in the dictionary results.
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. aliases: password
url_username string |  | A username for the module to use for Digest, Basic or WSSE authentication. aliases: user
use_proxy boolean | Choices: no yes ← | If `no`, it will not use a proxy, even if one is defined in an environment variable on the target hosts.
validate_certs boolean | Choices: no yes ← | If `no`, SSL certificates will not be validated. This should only set to `no` used on personally controlled sites using self-signed certificates. Prior to 1.9.2 the code defaulted to `no`.

## 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: https://www.ansible.com/

## 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)

Hint

If you notice any issues in this documentation you can edit this document to improve it.