/ home / ansible / ansible.builtin / v2.9.27 / module / win_uri

ansible.builtin.win_uri (v2.9.27) — 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.9.27

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.
    required: true
    type: str

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

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

method:
    default: GET
    description:
    - The HTTP Method of the request or response.
    type: str

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

headers:
    description:
    - Extra headers to set on the request.
    - This should be a dictionary where the key is the header name and the value is the
      value for that header.
    type: dict

removes:
    description:
    - A filename, when it does not exist, this step will be skipped.
    type: path
    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).
    - Set to V(0) to specify an infinite timeout.
    type: int

proxy_url:
    description:
    - An explicit proxy to use for the request.
    - By default, the request will use the IE defined proxy unless O(use_proxy) is set
      to V(no).
    type: str
    version_added: '2.9'
    version_added_collection: ansible.builtin

use_proxy:
    default: true
    description:
    - If V(no), it will not use the proxy defined in IE for the current user.
    type: bool
    version_added: '2.9'
    version_added_collection: ansible.builtin

http_agent:
    default: ansible-httpget
    description:
    - Header to identify as, generally appears in web server logs.
    - This is set to the C(User-Agent) header on a HTTP request.
    type: str

client_cert:
    description:
    - The path to the client certificate (.pfx) that is used for X509 authentication.
      This path can either be the path to the C(pfx) on the filesystem or the PowerShell
      certificate path C(Cert:\CurrentUser\My\<thumbprint>).
    - The WinRM connection must be authenticated with C(CredSSP) or C(become) is used
      on the task if the certificate file is not password protected.
    - Other authentication types can set O(client_cert_password) when the cert is password
      protected.
    type: str
    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.
    type: list
    version_added: '2.4'
    version_added_collection: ansible.builtin

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

url_password:
    description:
    - The password for I(url_username).
    - Was originally called I(password) but was changed to I(url_password) in Ansible
      2.9.
    type: str
    version_added: '2.4'
    version_added_collection: ansible.builtin

url_username:
    description:
    - The username to use for authentication.
    - Was originally called I(user) but was changed to I(url_username) in Ansible 2.9.
    type: str
    version_added: '2.4'
    version_added_collection: ansible.builtin

proxy_password:
    description:
    - The password for O(proxy_username).
    type: str
    version_added: '2.9'
    version_added_collection: ansible.builtin

proxy_username:
    description:
    - The username to use for proxy authentication.
    type: str
    version_added: '2.9'
    version_added_collection: ansible.builtin

return_content:
    default: false
    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: true
    description:
    - If V(no), SSL certificates will not be validated.
    - This should only be used on personally controlled sites using self-signed certificates.
    type: bool

follow_redirects:
    choices:
    - all
    - none
    - safe
    default: safe
    description:
    - Whether or the module should follow redirects.
    - V(all) will follow all redirect.
    - V(none) will not follow any redirect.
    - V(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.
    - When following a redirected URL, the C(Authorization) header and any credentials
      set will be dropped and not redirected.
    type: str
    version_added: '2.4'
    version_added_collection: ansible.builtin

force_basic_auth:
    default: false
    description:
    - By default the authentication header is only sent when a webservice responses 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 original
      request.
    type: bool

maximum_redirection:
    default: 50
    description:
    - Specify how many times the module will redirect a connection to an alternative URI
      before the connection fails.
    - If set to V(0) or O(follow_redirects) is set to V(none), or V(safe) when not doing
      a C(GET) or C(HEAD) it prevents all redirection.
    type: int
    version_added: '2.4'
    version_added_collection: ansible.builtin

client_cert_password:
    description:
    - The password for O(client_cert) if the cert is password protected.
    type: str
    version_added: '2.5'
    version_added_collection: ansible.builtin

use_default_credential:
    default: false
    description:
    - Uses the current user's credentials when authenticating with a server protected
      with C(NTLM), C(Kerberos), or C(Negotiate) authentication.
    - Sites that use C(Basic) auth will still require explicit credentials through the
      O(url_username) and O(url_password) options.
    - The module will only have access to the user's credentials if using C(become) with
      a password, you are connecting with SSH using a password, or connecting with WinRM
      using C(CredSSP) or C(Kerberos with delegation).
    - If not using C(become) or a different auth method to the ones stated above, there
      will be no default credentials available and no authentication will occur.
    type: bool

proxy_use_default_credential:
    default: false
    description:
    - Uses the current user's credentials when authenticating with a proxy host protected
      with C(NTLM), C(Kerberos), or C(Negotiate) authentication.
    - Proxies that use C(Basic) auth will still require explicit credentials through the
      O(proxy_username) and O(proxy_password) options.
    - The module will only have access to the user's credentials if using C(become) with
      a password, you are connecting with SSH using a password, or connecting with WinRM
      using C(CredSSP) or C(Kerberos with delegation).
    - If not using C(become) or a different auth method to the ones stated above, there
      will be no default credentials available and no proxy authentication will occur.
    type: bool

Outputs

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

Install Ansible via pip

Description

Usage examples

Inputs

Outputs

See also

Install Ansible via `pip`