Module uri Ansible : appels API REST avec parsing JSON

ansible.builtin.uri: fait des appels HTTP/HTTPS depuis le managed node : GET, POST, PUT, DELETE. C'est l'équivalent d'un curl mais avec idempotence explicite, parsing JSON automatique, et gestion d'erreurs structurée.

Cas d'usage RHCE 2026 : healthchecks applicatifs, création de ressources via API (Kubernetes, Vault, Grafana), récupération de tokens OAuth, notifications webhook (Slack, Teams).

Options critiques : url:, method: (GET défaut), status_code: (liste de codes acceptés), return_content: true (capture la réponse), body: + body_format:, headers:.

Ce que vous allez apprendre

• Faire un GET simple et capturer la réponse JSON parsée.
• Faire un POST avec body JSON automatiquement sérialisé.
• Authentifier via Basic Auth ou Bearer token.
• Accepter plusieurs codes de retour (200, 201, 204).
• Faire un healthcheck avec until: + retries: + delay:.

Prérequis

• Connaître les méthodes HTTP (GET, POST, PUT, DELETE) et les codes de retour (2xx, 4xx, 5xx).
• Comprendre la structure d'un body JSON.

GET simple + parsing JSON

La lecture d'une API REST est le premier usage du module, et celui qui sert de socle à tous les autres : une requête, une capture du résultat, puis l'exploitation de la réponse dans les tâches suivantes. L'exemple ci-dessous interroge l'API publique de GitHub pour connaître la dernière version publiée d'Ansible, puis affiche le champ tag_name de la réponse JSON.

- name: Recuperer la derniere release Ansible
  ansible.builtin.uri:
    url: https://api.github.com/repos/ansible/ansible/releases/latest
    method: GET
    return_content: true
  register: api_response

- name: Afficher la version
  ansible.builtin.debug:
    msg: "Derniere release : {{ api_response.json.tag_name }}"

Comportement :

• return_content: true capture la réponse dans register.content (raw) ET register.json (parsé si Content-Type: application/json).
• Pas besoin de from_json, Ansible parse automatiquement.
• method: GET est le défaut, peut être omis.

POST avec body JSON

Créer une ressource par API demande deux choses de plus qu'une lecture : un corps de requête et une liste de codes de retour acceptés. Le corps s'écrit en YAML lisible dans le playbook, la sérialisation étant prise en charge par le module. La liste des codes évite l'écueil le plus courant, une création qui réussit côté serveur et une tâche qui échoue côté Ansible.

- name: Creer une ressource via POST
  ansible.builtin.uri:
    url: https://httpbin.org/post
    method: POST
    body_format: json
    body:
      name: myapp
      version: "1.0.0"
      env: prod
    status_code: [200, 201]
    return_content: true
  register: post_result

Détails :

• body_format: json sérialise automatiquement le dict Ansible en JSON pour le body HTTP.
• status_code: [200, 201] : la tâche réussit si le serveur retourne 200 OU 201. Sinon, failed.
• Sans status_code:, le défaut est [200], un 201 ferait failer la tâche.

Autres body_format: :

• json, sérialise dict → JSON (le plus courant).
• form-urlencoded, sérialise dict → key=value&key2=value2.
• raw, body brut, vous gérez la sérialisation.

Authentification

# Basic Auth (utilisateur/password)
- name: Appeler l'API
  ansible.builtin.uri:
    url: https://api.private.com/v1/resources
    method: GET
    url_username: "{{ vault_api_user }}"
    url_password: "{{ vault_api_password }}"
    force_basic_auth: true
    return_content: true

# Bearer Token (OAuth, JWT, GitHub, GitLab)
- name: Appeler l'API
  ansible.builtin.uri:
    url: https://api.github.com/user
    method: GET
    headers:
      Authorization: "Bearer {{ vault_github_token }}"
      Accept: application/vnd.github+json
    return_content: true

force_basic_auth: true envoie l'en-tête Authorization: Basic ... dès la première requête. Sans, Ansible attend un 401 du serveur avant de re-tenter avec auth (souvent OK, mais coûte un round-trip).

Secrets : toujours dans Ansible Vault.

Healthcheck applicatif (until: + retries: + delay:)

Pattern classique : après déploiement d'une app, vérifier qu'elle répond avant de continuer.

- name: Demarrer myapp
  ansible.builtin.systemd_service:
    name: myapp
    state: restarted

- name: Attendre que le port soit ouvert
  ansible.builtin.wait_for:
    port: 8080
    host: 127.0.0.1
    timeout: 30

- name: Verifier le healthcheck HTTP
  ansible.builtin.uri:
    url: http://localhost:8080/health
    method: GET
    status_code: 200
    return_content: true
  register: health
  until: health.json.status == "ok"
  retries: 5
  delay: 2

- name: Afficher la version deployee
  ansible.builtin.debug:
    msg: "myapp version : {{ health.json.version }}"

until: + retries: + delay: = polling. Ansible relance la tâche jusqu'à ce que la condition soit vraie (max retries fois, avec delay secondes entre chaque essai). Idéal pour des services qui mettent quelques secondes à démarrer.

Upload de fichier

- name: Upload de config
  ansible.builtin.uri:
    url: https://api.private.com/v1/configs
    method: POST
    src: /tmp/myapp.yml
    headers:
      Authorization: "Bearer {{ vault_token }}"
      Content-Type: application/yaml
    status_code: [200, 201]

src: envoie le contenu du fichier comme body HTTP. Pour multipart/form-data : body_format: form-multipart (Ansible 2.10+).

uri: vs get_url:

Cas	Module
Télécharger un fichier (binaire, archive)	get_url:
Télécharger avec checksum	get_url:
Appeler une API REST (GET, POST, PUT, DELETE)	uri:
Parser une réponse JSON	uri: + register.json
Healthcheck HTTP	uri: + until:
Upload de fichier vers API	uri: + src:

Glissez pour voir

Règle : get_url: pour le téléchargement de fichiers (idempotence par checksum/ETag/taille). uri: pour toute interaction HTTP où la réponse compte autant que le statut.

Pièges courants

Ces quatre symptômes viennent tous d'un défaut du module que l'on découvre en production plutôt qu'à l'écriture. Deux tiennent à ce que le serveur annonce, le code de retour et le type de contenu, et se corrigent dans la tâche qui appelle. Le troisième vient d'une condition de reprise qui ne peut pas aboutir, le quatrième d'une validation TLS désactivée pour « faire passer » un appel.

Symptôme	Cause	Fix
Tâche failed sur HTTP 201	Défaut status_code: [200]	Ajouter [200, 201]
register.json est null	Content-Type non JSON	Vérifier les headers ou parser manuellement avec from_json
Polling infini	Condition until: jamais vraie	Limiter retries: à un maximum raisonnable
MITM ne déclenche pas d'erreur	validate_certs: false	Ne jamais désactiver TLS sauf cas dev

Glissez pour voir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• uri: = appels HTTP REST (GET, POST, PUT, DELETE).
• return_content: true capture la réponse, JSON parsé automatiquement.
• status_code: liste les codes acceptés (défaut [200]).
• body_format: json sérialise un dict en JSON automatiquement.
• Auth : url_username/url_password (Basic) ou headers: (Bearer).
• until: + retries: + delay: = polling pour healthchecks.

Mettre en pratique

Piloter une API depuis un playbook demande de gérer trois choses que ce lab fait travailler ensemble. Vous enchaînez un GET dont la réponse JSON est parsée, un POST avec un body_format: json, puis vous élargissez les codes acceptés via status_code: pour qu'une création déjà faite ne casse pas le run. La dernière tâche boucle un healthcheck avec until / retries jusqu'à ce que le service réponde.

Lab pratique

Module uri : appels API REST

$ dsoxlab run modules-reseau-uri

Environnement : VM·Durée : ~50 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run modules-reseau-uri
dsoxlab check modules-reseau-uri

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Pour aller plus loin

• Modules assert et fail : Valider le contenu JSON renvoyé par l'API plutôt que de le supposer correct.
• Modules wait_for et pause : Attendre l'ouverture du port avant d'appeler l'API, en complément du polling until et retries.
• debug, setup, add_host, group_by : Afficher proprement la réponse enregistrée, et ajouter à l'inventaire un hôte découvert par API.

×

📖 Voir la documentation →