/ home / ansible / ansible.builtin / v2.4.4.0-1 / module / win_uri

ansible.builtin.win_uri (v2.4.4.0-1) — module

Interacts with webservices

| "added in version" 2.1 of ansible.builtin"

Authors: Corwin Brown (@blakfeld), Dag Wieers (@dagwieers)

preview | supported by community

Install Ansible via `pip`

Install with pip install ansible==2.4.4.0.post1

Description

Interacts with FTP, HTTP and HTTPS web services.

Supports Digest, Basic and WSSE HTTP authentication mechanisms.

For non-Windows targets, use the M(uri) module instead.

Usage examples

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

# 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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Inputs

    
url:
    description:
    - Supports FTP, HTTP or HTTPS URLs in the form of (ftp|http|https)://host.domain:port/path.
    - Also supports file:/// URLs through Invoke-WebRequest.
    required: true

body:
    description:
    - The body of the HTTP request/response to the web service.

dest:
    description:
    - Output the response body to a file.
    version_added: '2.3'
    version_added_collection: ansible.builtin

user:
    description:
    - Username to use for authentication.
    version_added: '2.4'
    version_added_collection: ansible.builtin

method:
    choices:
    - CONNECT
    - DELETE
    - GET
    - HEAD
    - OPTIONS
    - PATCH
    - POST
    - PUT
    - REFRESH
    - TRACE
    default: GET
    description:
    - The HTTP Method of the request or response.

creates:
    description:
    - A filename, when it already exists, this step will be skipped.
    version_added: '2.4'
    version_added_collection: ansible.builtin

headers:
    description:
    - 'Key Value pairs for headers. Example "Host: www.somesite.com"'

removes:
    description:
    - A filename, when it does not exist, this step will be skipped.
    version_added: '2.4'
    version_added_collection: ansible.builtin

timeout:
    default: 30
    description:
    - 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 C(timeout)
      to a value greater than zero, but less than 15 seconds, it can take 15 seconds or
      more before your request times out.
    version_added: '2.4'
    version_added_collection: ansible.builtin

password:
    description:
    - Password to use for authentication.
    version_added: '2.4'
    version_added_collection: ansible.builtin

client_cert:
    description:
    - Specifies the client certificate(.pfx)  that is used for a secure web request.
    version_added: '2.4'
    version_added_collection: ansible.builtin

status_code:
    default: 200
    description:
    - A valid, numeric, HTTP status code that signifies success of the request.
    - Can also be comma separated list of status codes.
    version_added: '2.4'
    version_added_collection: ansible.builtin

content_type:
    description:
    - Sets the "Content-Type" header.

return_content:
    default: 'no'
    description:
    - 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 C(json) in the dictionary results.
    type: bool
    version_added: '2.4'
    version_added_collection: ansible.builtin

validate_certs:
    default: 'yes'
    description:
    - If C(no), SSL certificates will not be validated.  This should only set to C(no)
      used on personally controlled sites using self-signed certificates.
    type: bool
    version_added: '2.4'
    version_added_collection: ansible.builtin

follow_redirects:
    choices:
    - all
    - none
    - safe
    default: safe
    description:
    - Whether or not the C(win_uri) module should follow redirects.
    - C(all) will follow all redirects.
    - C(none) will not follow any redirects.
    - C(safe) will follow only "safe" redirects, where "safe" means that the client is
      only doing a C(GET) or C(HEAD) on the URI to which it is being redirected.
    version_added: '2.4'
    version_added_collection: ansible.builtin

use_basic_parsing:
    default: 'yes'
    description:
    - 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.
    type: bool

maximum_redirection:
    default: 5
    description:
    - Specifies how many times C(win_uri) redirects a connection to an alternate Uniform
      Resource Identifier (URI) before the connection fails.
    - If C(maximum_redirection) is set to 0 (zero) or C(follow_redirects) is set to C(none),
      or set to C(safe) when not doing C(GET) or C(HEAD) it prevents all redirection.
    version_added: '2.4'
    version_added_collection: ansible.builtin

Outputs

body:
  description: The content of the body used
  returned: when body is specified
  sample: '{"id":1}'
  type: string
content_type:
  description: The "content-type" header used.
  returned: always
  sample: application/json
  type: string
headers:
  description: The Headers of the response.
  returned: success
  sample:
    Content-Type: application/json
  type: dict
method:
  description: The HTTP method used.
  returned: always
  sample: GET
  type: string
raw_content:
  description: The raw content of the HTTP response.
  returned: success
  sample: 'HTTP/1.1 200 OK\nX-XSS-Protection: 1; mode=block\nAlternate-Protocol: 443:quic,p=1\nAlt-Svc:
    quic="www.google.com:443";'
  type: string
raw_content_length:
  description: The byte size of the response.
  returned: success
  sample: 54447
  type: int
status_code:
  description: The HTTP Status Code of the response.
  returned: success
  sample: 200
  type: int
status_description:
  description: A summery of the status.
  returned: success
  sample: OK
  type: string
url:
  description: The Target URL
  returned: always
  sample: https://www.ansible.com
  type: string
use_basic_parsing:
  description: The state of the "use_basic_parsing" flag.
  returned: always
  sample: true
  type: bool

Install Ansible via pip

Description

Usage examples

Inputs

Outputs

Install Ansible via `pip`