win_uri – Interacts with webservices — Ansible Documentation

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

Documentation

# win_uri – Interacts with webservices

New in version 2.1.

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

## Synopsis

- Interacts with FTP, HTTP and HTTPS web services.
- Supports Digest, Basic and WSSE HTTP authentication mechanisms.
- For non-Windows targets, use the uri module instead.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
body raw |  | The body of the HTTP request/response to the web service.
client_cert path added in 2.4 |  | Specifies the client certificate (.pfx) that is used for a secure web request. The WinRM connection must be authenticated with `CredSSP` if the certificate file is not password protected. Other authentication types can set client_cert_password when the cert is password protected.
client_cert_password string added in 2.5 |  | The password for the client certificate (.pfx) file that is used for a secure web request.
content_type string |  | Sets the "Content-Type" header.
creates path added in 2.4 |  | A filename, when it already exists, this step will be skipped.
dest path added in 2.3 |  | Output the response body to a file.
follow_redirects string added in 2.4 | Choices: all none safe ← | Whether or not the `win_uri` module should follow redirects. `all` will follow all redirects. `none` will not follow any 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.
force_basic_auth boolean added in 2.5 | Choices: no ← yes | By default the authentication information is only sent 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 the initial request.
headers dictionary |  | Extra headers to set on the request, see the examples for more details on how to set this.
maximum_redirection integer added in 2.4 | Default: 50 | Specifies how many times `win_uri` redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. If `maximum_redirection` is set to 0 (zero) or `follow_redirects` is set to `none`, or set to `safe` when not doing `GET` or `HEAD` it prevents all redirection.
method string | Default: "GET" | The HTTP Method of the request or response.
password string added in 2.4 |  | Password to use for authentication.
removes path added in 2.4 |  | A filename, when it does not exist, this step will be skipped.
return_content boolean added in 2.4 | Choices: no ← yes | 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 `json` in the dictionary results.
status_code list added in 2.4 | Default: [200] | A valid, numeric, HTTP status code that signifies success of the request. Can also be comma separated list of status codes.
timeout integer added in 2.4 | Default: 30 | Specifies how long the request can be pending before it times out (in seconds). The value 0 (zero) specifies an indefinite time-out. A Domain Name System (DNS) query can take up to 15 seconds to return or time out. If your request contains a host name that requires resolution, and you set `timeout` to a value greater than zero, but less than 15 seconds, it can take 15 seconds or more before your request times out.
url string / required |  | Supports FTP, HTTP or HTTPS URLs in the form of (ftp|http|https)://host.domain:port/path.
user string added in 2.4 |  | Username to use for authentication.
validate_certs boolean added in 2.4 | 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.

## See Also

See also

uri – Interacts with webservices
  The official documentation on the uri module.
win_get_url – Downloads file from HTTP, HTTPS, or FTP to node
  The official documentation on the win_get_url module.

## Examples

    - name: Perform a GET and Store Output
      win_uri:
        url: http://example.com/endpoint
      register: http_output

    # Set a HOST header to hit an internal webserver:
    - name: Hit a Specific Host on the Server
      win_uri:
        url: http://example.com/
        method: GET
        headers:
          host: www.somesite.com

    - name: Perform a HEAD on an Endpoint
      win_uri:
        url: http://www.example.com/
        method: HEAD

    - name: POST a Body to an Endpoint
      win_uri:
        url: http://www.somesite.com/
        method: POST
        body: "{ 'some': 'json' }"

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
content string | success and return_content is True | The raw content of the HTTP response. Sample: {"foo": "bar"}
content_length integer | success | The byte size of the response. Sample: 54447
elapsed float | always | The number of seconds that elapsed while performing the download. Sample: 23.2
json dictionary | success and Content-Type is "application/json" or "application/javascript" and return_content is True | The json structure returned under content as a dictionary. Sample: {'this-is-dependent': 'on the actual return content'}
status_code integer | success | The HTTP Status Code of the response. Sample: 200
status_description string | success | A summary of the status. Sample: OK
url string | always | The Target URL. Sample: https://www.ansible.com

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Corwin Brown (@blakfeld)
- Dag Wieers (@dagwieers)

Hint

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