# Un fournisseur oEmbed qui change son format : ce qui casse dans une Query Loop

> Des cartes d'article vides du jour au lendemain dans une Query Loop : le coupable n'était ni le thème ni WordPress, mais une réponse oEmbed qui avait changé de forme.

- Auteur : WordPress Développement
- Publié le : 2023-06-09
- Mis à jour le : 2023-06-09
- Catégorie : Éditeur de site (FSE)
- URL : https://www.wpmoderne.fr/fse/fournisseur-oembed-change-format-query-loop-casse/

## L’essentiel

- Un cache oEmbed obsolète peut masquer le vrai problème plusieurs jours
- Comparer la réponse actuelle du fournisseur à celle stockée en base
- Revalider les embeds existants plutôt que les supprimer à l'aveugle

« La vidéo ne s'affiche plus dans les articles de la rubrique Portraits » : c'est par ce genre de signalement, vague et difficile à reproduire à volonté, qu'a commencé cet incident. Sur le site concerné, une Query Loop affichait un aperçu vidéo intégré directement dans le contenu de chaque article via un simple collage d'URL, transformé automatiquement en lecteur grâce à l'API oEmbed de WordPress. Du jour au lendemain, certains aperçus se sont mis à afficher un cadre vide, sans message d'erreur visible côté visiteur.

## Symptôme : des blocs d'intégration vides, pas tous

Seuls les articles publiés avant une certaine date affichaient le problème ; les articles plus récents, avec la même URL de vidéo collée dans le contenu, s'affichaient normalement. Ce détail a orienté l'enquête vers un problème de cache plutôt que vers le bloc lui-même : WordPress stocke la réponse oEmbed dans une méta donnée `_oembed_ttl` et une entrée sérialisée associée au contenu, avec une durée de validité par défaut d'une journée avant revalidation.

## Diagnostic : une réponse oEmbed devenue incompatible

> L'essentiel à retenir : Un cache oEmbed obsolète peut masquer le vrai problème plusieurs jours ; Comparer la réponse actuelle du fournisseur à celle stockée en base ; Revalider les embeds existants plutôt que les supprimer à l'aveugle

En comparant une réponse fraîche du fournisseur à celle stockée en base pour un article ancien, la différence est apparue : le fournisseur avait changé la structure de son objet de réponse, en renommant le champ `html` historique en un champ imbriqué dans un objet `embed`. La fonction `wp_oembed_get()` de WordPress, qui s'appuie sur le format attendu par la spécification oEmbed, ne trouvait plus le contenu HTML à insérer et retournait une chaîne vide, silencieusement mise en cache pour la durée de validité restante.

```
// Ancienne forme attendue par WordPress
{
  "type": "video",
  "html": "<iframe src=\"...\"></iframe>"
}

// Nouvelle forme renvoyée par le fournisseur
{
  "type": "video",
  "embed": {
    "html": "<iframe src=\"...\"></iframe>"
  }
}
```

Aucun message d'erreur n'était journalisé côté WordPress : la requête HTTP vers le fournisseur réussissait, seule l'extraction du champ échouait silencieusement dans le traitement interne du cache oEmbed.

## Correctif : revalider plutôt que reconstruire

La première tentation — supprimer toutes les métadonnées `_oembed_*` pour forcer une nouvelle tentative — aurait fonctionné uniquement si le fournisseur corrigeait son format de son côté, ce qui n'était pas garanti à court terme. La correction retenue a consisté à filtrer la réponse brute avant qu'elle ne soit traitée par WordPress, via le filtre `oembed_remote_get_args` côté requête et `oembed_dataparse` côté traitement, pour ramener la nouvelle structure vers l'ancienne forme attendue :

```
add_filter( 'oembed_dataparse', function ( $return, $data, $url ) {
    if ( empty( $data->html ) && ! empty( $data->embed->html ) ) {
        $data->html = $data->embed->html;
    }
    return $return;
}, 10, 3 );
```

Ce filtre agit avant la mise en cache : une fois en place, une purge ciblée des métadonnées `_oembed_ttl` des articles concernés a suffi à déclencher une nouvelle récupération, cette fois correctement interprétée.

## Pourquoi le cache a retardé la découverte

Le mécanisme de cache oEmbed de WordPress est pensé pour éviter une requête HTTP à chaque affichage, ce qui est une bonne pratique de performance en temps normal. Il devient un piège de diagnostic quand le contenu mis en cache est justement celui qui a été mal interprété : les articles déjà en cache continuaient d'afficher une ancienne réponse valide, tandis que les articles dont le cache expirait naturellement basculaient un par un vers le nouveau format cassé, ce qui a donné l'impression trompeuse d'une panne progressive plutôt que d'un changement ponctuel.

## Prévention pour la suite

- surveiller les articles officiels ou les journaux de changement du fournisseur oEmbed utilisé, quand ils existent ;
- ajouter une alerte simple qui compare, une fois par semaine, la structure d'une réponse fraîche à un gabarit connu ;
- éviter de fixer une durée de cache trop longue pour les contenus embarqués sur des pages à fort trafic, pour limiter la fenêtre d'exposition en cas de nouveau changement.

> Nous conservons désormais, pour chaque fournisseur oEmbed utilisé sur un projet, un exemple de réponse brute archivé dans le dépôt du thème : c'est la seule référence fiable en cas de comportement inexpliqué.

## Notre verdict

Un service tiers qui change son format sans prévenir n'est pas rare, et WordPress ne peut pas s'en prémunir seul : la spécification oEmbed impose une forme, mais rien n'empêche un fournisseur de s'en écarter. Le vrai enseignement de cet incident tient moins au correctif, assez simple une fois le diagnostic posé, qu'au temps perdu à chercher du côté du thème et de la Query Loop avant de remonter jusqu'à la donnée réellement en cause.