Steampunk Ansible Documentation - ansible.builtin.uri (v2.4.4.0-1) - module

Install Ansible via `pip`

Install with pip install ansible==2.4.4.0.post1

Description

Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms.

For Windows targets, use the M(win_uri) module instead.

Usage examples

- name: Check that you can connect (GET) to a page and it returns a status 200
  uri:
    url: http://www.example.com

Scanned by Steampunk Spotter

# 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: webpage

Scanned by Steampunk Spotter

- name: Fail if AWESOME is not in the page content
  fail:
  when: "'AWESOME' not in webpage.content"

Scanned by Steampunk Spotter


- name: Create a JIRA issue
  uri:
    url: https://your.jira.example.com/rest/api/2/issue/
    method: POST
    user: your_username
    password: your_pass
    body: "{{ lookup('file','issue.json') }}"
    force_basic_auth: yes
    status_code: 201
    body_format: json

Scanned by Steampunk Spotter

# 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: "name=your_username&password=your_password&enter=Sign%20in"
    status_code: 302
    headers:
      Content-Type: "application/x-www-form-urlencoded"
  register: login

Scanned by Steampunk Spotter

- uri:
    url: https://your.form.based.auth.example.com/dashboard.php
    method: GET
    return_content: yes
    headers:
      Cookie: "{{login.set_cookie}}"

Scanned by Steampunk Spotter

- name: Queue build of a project in Jenkins
  uri:
    url: "http://{{ jenkins.host }}/job/{{ jenkins.job }}/build?token={{ jenkins.token }}"
    method: GET
    user: "{{ jenkins.user }}"
    password: "{{ jenkins.password }}"
    force_basic_auth: yes
    status_code: 201

Inputs

url:
description:
- HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path
required: true

body:
description:
- The body of the http request/response to the web service. If C(body_format) is set
to 'json' it will take an already formatted JSON string or convert a data structure
into JSON.

dest:
description:
- path of where to download the file to (if desired). If I(dest) is a directory, the
basename of the file on the remote server will be used.

user:
description:
- username for the module to use for Digest, Basic or WSSE authentication.

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

others:
description:
- all arguments accepted by the M(file) module also work here

HEADER_:
description:
- 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 C(2.1) and may be removed in a future release. Use I(headers) instead.

creates:
description:
- a filename, when it already exists, this step will not be run.

headers:
description:
- Add custom HTTP headers to a request in the format of a YAML hash. As of C(2.3)
supplying C(Content-Type) here will override the header generated by supplying C(json)
for I(body_format).
version_added: '2.1'
version_added_collection: ansible.builtin

removes:
description:
- a filename, when it does not exist, this step will not be run.

timeout:
default: 30
description:
- The socket level timeout in seconds

password:
description:
- password for the module to use for Digest, Basic or WSSE authentication.

client_key:
description:
- PEM formatted file that contains your private key to be used for SSL client authentication.
If I(client_cert) contains both the certificate and key, this option is not required.
version_added: '2.4'
version_added_collection: ansible.builtin

body_format:
choices:
- raw
- json
default: raw
description:
- The serialization format of the body. When set to json, encodes the body argument,
if needed, and automatically sets the Content-Type header accordingly. As of C(2.3)
it is possible to override the `Content-Type` header, when set to json via the I(headers)
option.
version_added: '2.0'
version_added_collection: ansible.builtin

client_cert:
description:
- 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, I(client_key)
is not required
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.

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

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. Prior to 1.9.2
the code defaulted to C(no).
type: bool
version_added: 1.9.2
version_added_collection: ansible.builtin

follow_redirects:
choices:
- all
- safe
- none
default: safe
description:
- Whether or not the URI module should follow redirects. C(all) will follow all redirects.
C(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. C(none) will
not follow any redirects. Note that C(yes) and C(no) choices are accepted for backwards
compatibility, where C(yes) is the equivalent of C(all) and C(no) is the equivalent
of C(safe). C(yes) and C(no) are deprecated and will be removed in some future version
of Ansible.

force_basic_auth:
default: 'no'
description:
- 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. This option forces the sending
of the Basic authentication header upon initial request.
type: bool

Outputs

msg:
  description: The HTTP message from the request
  returned: always
  sample: OK (unknown bytes)
  type: string
redirected:
  description: Whether the request was redirected
  returned: always
  sample: false
  type: bool
status:
  description: The HTTP status code from the request
  returned: always
  sample: 200
  type: int
url:
  description: The actual URL used for the request
  returned: always
  sample: https://www.ansible.com/
  type: string

Install Ansible via pip

Description

Usage examples

Inputs

Outputs

Install Ansible via `pip`