171 lines
No EOL
12 KiB
Markdown
171 lines
No EOL
12 KiB
Markdown
# 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"<br>"json"<br>"raw"<br>"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'
|
||
``` |