knowledge/technology/tools/Ansible/modules/ansible.builtin.uri.md

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 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

- 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'