win_uri - Interacts with webservices
New in version 2.1.
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 | The body of the HTTP request/response to the web service. | |
client_cert (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 (added in 2.5) | The password for the client certificate (.pfx) file that is used for a secure web request. | |
content_type | Sets the "Content-Type" header. | |
creates (added in 2.4) | A filename, when it already exists, this step will be skipped. | |
dest (added in 2.3) | Output the response body to a file. | |
follow_redirects (added in 2.4) |
| 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 (added in 2.5) |
| 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 | Extra headers to set on the request, see the examples for more details on how to set this. | |
maximum_redirection (added in 2.4) | Default: 5 | 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 |
| The HTTP Method of the request or response. |
password (added in 2.4) | Password to use for authentication. | |
removes (added in 2.4) | A filename, when it does not exist, this step will be skipped. | |
return_content (added in 2.4) |
| 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 (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 (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 required | Supports FTP, HTTP or HTTPS URLs in the form of (ftp|http|https)://host.domain:port/path. | |
use_basic_parsing |
| As of Ansible 2.5, this option is no longer valid and cannot be changed from yes , this option will be removed in Ansible 2.7.Before Ansible 2.5, this module relies upon 'Invoke-WebRequest', which by default uses the Internet Explorer Engine to parse a webpage. There's an edge-case where if a user hasn't run IE before, this will fail. The only advantage to using the Internet Explorer praser is that you can traverse the DOM in a powershell script. That isn't useful for Ansible, so by default we toggle 'UseBasicParsing'. However, you can toggle that off here. |
user (added in 2.4) | Username to use for authentication. | |
validate_certs (added in 2.4) |
| If no , SSL certificates will not be validated. This should only set to no used on personally controlled sites using self-signed certificates. |
Notes
Note
- For non-Windows targets, use the uri module instead.
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 int | success | The byte size of the response. Sample: 54447 |
json dict | 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 int | success | The HTTP Status Code of the response. Sample: 200 |
status_description string | success | A summery of the status. Sample: OK |
url string | always | The Target URL Sample: https://www.ansible.com |
Status
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Author
- Corwin Brown (@blakfeld)
- Dag Wieers (@dagwieers)
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.5/modules/win_uri_module.html