# ansible.builtin.uri
Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms.
## Parameter
| Parameter | Type | Default | Description |
| ------------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **attributes** | string | - | The attributes the resulting filesystem object should have. To get supported flags look at the man page for [chattr](../../../applications/cli/chattr.md) on the target system. The = operator is assumed as default, otherwise + or - operators need to be included in the string. |
| **body** | any | - | The body of the http request/response to the web service. If `body_format` is set to ‘json’ it will take an already formatted JSON string or convert a data structure into JSON. |
| **body_format** | "form-urlencoded"
"json"
"raw"
"form-multipart" | "raw" | The serialization format of the body. When set to `json`, `form-multipart`, or `form-urlencoded`, encodes the body argument, if needed, and automatically sets the Content-Type header accordingly. |
| **creates** | path | - | A filename, when it already exists, this step will not be run. |
| **dest** | path | - | A path of where to download the file to (if desired). If dest is a directory, the basename of the file on the remote server will be used. |
| **headers** | dictionary | {} | Add custom HTTP headers to a request in the format of a YAML hash |
| **method** | string | "GET" | The HTTP method of the request or response. |
| **removes** | path | - | A filename, when it does not exist, this step will not be run. |
| **status_code** | list / elements=integer | \[200] | A list of valid, numeric, HTTP status codes that signifies success of the request. |
| **timeout** | integer | 30 | The socket level timeout in seconds |
| **url** | string / required | - | HTTP or HTTPS URL |
| **url_password** | string | - | A password for the module to use for Digest, Basic or WSSE authentication. |
| **url_username** | string | - | A username for the module to use for Digest, Basic or WSSE authentication. |
| **validate_certs** | boolean | true | If `false`, SSL certificates will not be validated. |
## Return Values
| Value | Type | When | Description |
| ------------------ | ---------- | --------------------------------------------------- | ----------------------------------------------------------------- |
| **content** | string | status not in status_code or return_content is true | The response body content. |
| **cookies** | dictionary | success | The cookie values placed in cookie jar. |
| **cookies_string** | string | success | The value for future request Cookie headers. |
| **elapsed** | integer | success | The number of seconds that elapsed while performing the download. |
| **msg** | string | always | The HTTP message from the request. |
| **path** | string | dest is defined | destination file/path |
| **redirected** | boolean | success | Whether the request was redirected. |
| **status** | integer | always | The HTTP status code from the request. |
| **url** | string | always | The actual URL used for the request. |
## Examples
```yaml
- name: Check that you can connect (GET) to a page and it returns a status 200
ansible.builtin.uri:
url: http://www.example.com
- name: Check that a page returns successfully but fail if the word AWESOME is not in the page contents
ansible.builtin.uri:
url: http://www.example.com
return_content: true
register: this
failed_when: this is failed or "'AWESOME' not in this.content"
- name: Create a JIRA issue
ansible.builtin.uri:
url: https://your.jira.example.com/rest/api/2/issue/
user: your_username
password: your_pass
method: POST
body: "{{ lookup('ansible.builtin.file','issue.json') }}"
force_basic_auth: true
status_code: 201
body_format: json
- name: Login to a form based webpage, then use the returned cookie to access the app in later tasks
ansible.builtin.uri:
url: https://your.form.based.auth.example.com/index.php
method: POST
body_format: form-urlencoded
body:
name: your_username
password: your_password
enter: Sign in
status_code: 302
register: login
- name: Login to a form based webpage using a list of tuples
ansible.builtin.uri:
url: https://your.form.based.auth.example.com/index.php
method: POST
body_format: form-urlencoded
body:
- [ name, your_username ]
- [ password, your_password ]
- [ enter, Sign in ]
status_code: 302
register: login
- name: Upload a file via multipart/form-multipart
ansible.builtin.uri:
url: https://httpbin.org/post
method: POST
body_format: form-multipart
body:
file1:
filename: /bin/true
mime_type: application/octet-stream
file2:
content: text based file content
filename: fake.txt
mime_type: text/plain
text_form_field: value
- name: Connect to website using a previously stored cookie
ansible.builtin.uri:
url: https://your.form.based.auth.example.com/dashboard.php
method: GET
return_content: true
headers:
Cookie: "{{ login.cookies_string }}"
- name: Queue build of a project in Jenkins
ansible.builtin.uri:
url: http://{{ jenkins.host }}/job/{{ jenkins.job }}/build?token={{ jenkins.token }}
user: "{{ jenkins.user }}"
password: "{{ jenkins.password }}"
method: GET
force_basic_auth: true
status_code: 201
- name: POST from contents of local file
ansible.builtin.uri:
url: https://httpbin.org/post
method: POST
src: file.json
- name: POST from contents of remote file
ansible.builtin.uri:
url: https://httpbin.org/post
method: POST
src: /path/to/my/file.json
remote_src: true
- name: Create workspaces in Log analytics Azure
ansible.builtin.uri:
url: https://www.mms.microsoft.com/Embedded/Api/ConfigDataSources/LogManagementData/Save
method: POST
body_format: json
status_code: [200, 202]
return_content: true
headers:
Content-Type: application/json
x-ms-client-workspace-path: /subscriptions/{{ sub_id }}/resourcegroups/{{ res_group }}/providers/microsoft.operationalinsights/workspaces/{{ w_spaces }}
x-ms-client-platform: ibiza
x-ms-client-auth-token: "{{ token_az }}"
body:
- name: Pause play until a URL is reachable from this host
ansible.builtin.uri:
url: "http://192.0.2.1/some/test"
follow_redirects: none
method: GET
register: _result
until: _result.status == 200
retries: 720 # 720 * 5 seconds = 1hour (60*60/5)
delay: 5 # Every 5 seconds
- name: Provide SSL/TLS ciphers as a list
uri:
url: https://example.org
ciphers:
- '@SECLEVEL=2'
- ECDH+AESGCM
- ECDH+CHACHA20
- ECDH+AES
- DHE+AES
- '!aNULL'
- '!eNULL'
- '!aDSS'
- '!SHA1'
- '!AESCCM'
- name: Provide SSL/TLS ciphers as an OpenSSL formatted cipher list
uri:
url: https://example.org
ciphers: '@SECLEVEL=2:ECDH+AESGCM:ECDH+CHACHA20:ECDH+AES:DHE+AES:!aNULL:!eNULL:!aDSS:!SHA1:!AESCCM'
```