Introduction
Un site web peut mémoriser des choix d’affichage, comme un thème sombre ou une langue préférée. Ces paramètres sont souvent lus à chaque visite, mais rarement modifiés. Ils constituent donc un bon exemple d’utilisation de Workers KV. Au lieu de stocker un seul mot comme indicateur de fonctionnalité, vous allez stocker du JSON : un texte qui regroupe des champs nommés dans une même valeur. Votre Worker transformera ce texte en paramètres utilisables.
Dans cet atelier, Alice et Bob sont des identifiants de comptes fictifs, pas de vrais utilisateurs. Vous leur attribuerez des préférences différentes et ferez en sorte que les entrées manquantes ou endommagées renvoient une valeur par défaut cohérente. Vous ajouterez également des métadonnées, c’est-à-dire une petite description stockée avec une valeur, pour identifier la révision d’un paramètre. Les numéros de révision indiquent quelles données ont été lues ; ils ne garantissent pas que chaque emplacement voit immédiatement la valeur la plus récente.
Terminez d’abord l’atelier Create a Feature Flag Store. Cet atelier démarre dans une VM neuve, à l’emplacement /home/labex/project/account-preferences, avec Node.js 22.22.0 et Wrangler 4.131.1 installé localement dans le projet. Vous allez créer un nouveau Worker et un nouvel espace de noms dans votre compte d’apprentissage, avec les mêmes autorisations de lecture du compte, d’écriture des Workers et d’écriture dans KV. La démonstration publique n’expose que des paramètres d’affichage synthétiques ; l’identifiant de compte présent dans l’URL ne constitue pas une authentification. Aucun abonnement payant ni domaine acheté n’est nécessaire pour ce petit exercice. Effectuez le nettoyage des ressources avant de quitter la VM.
Connecter un espace de noms de préférences
Dans cette étape, vous allez connecter un espace de noms indépendant pour les préférences de comptes d’exemple. Un espace de noms regroupe les valeurs de ce service ; la liaison PREFERENCES fournit à votre Worker un nom stable pour y accéder. Cette VM neuve réutilise les informations de votre compte, mais pas l’espace de noms ni l’autorisation de l’atelier précédent.
Accédez au projet préparé :
cd /home/labex/project/account-preferences
Générez une fois un nom unique. openssl rand -hex 6 affiche un suffixe aléatoire ; $(...) l’insère dans le nom. La variable du shell conserve ce nom pour les commandes suivantes exécutées dans ce terminal.
WORKER_NAME="labex-prefs-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
Autorisez cette VM. En plus de lire l’identité de votre compte, l’autorisation Workers Scripts Write permet de déployer et de supprimer des Workers, tandis que Workers KV Write permet de gérer l’espace de noms et les clés de cet atelier.
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
Ouvrez dans votre navigateur le lien d’appareil affiché, saisissez le code actuel, vérifiez les autorisations demandées ainsi que le compte d’apprentissage, puis autorisez Wrangler. Un accès en arrière-plan peut également apparaître sur la page de consentement. Revenez au terminal et attendez la fin de la connexion.
Développez Developer Platform pour vérifier les autorisations Workers Scripts Write et Workers KV Storage Write. Il s’agit des mêmes autorisations de gestion des ressources que celles présentées dans Create a Feature Flag Store.
npx wrangler whoami --json
Vérifiez que loggedIn: true et que le compte d’apprentissage contient bien un champ name, même si un seul compte est répertorié. Copiez l’id de ce compte. Enregistrez-le dans la configuration ci-dessous en remplaçant YOUR_ACCOUNT_ID avant d’exécuter la commande. Le here-document de cat écrit dans un fichier tout ce qui se trouve entre les deux lignes JSON ; > remplace le fichier. Le délimiteur non placé entre guillemets permet au shell d’insérer $WORKER_NAME.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true
}
JSON
Créez un espace de noms dans ce compte. Son titre reprend le nom unique du Worker afin que vous puissiez reconnaître les deux ressources plus tard. --update-config=false laisse la modification de la liaison visible afin que vous l’effectuiez vous-même, au lieu de modifier automatiquement le fichier.
npx wrangler kv namespace create "$WORKER_NAME-preferences" --update-config=false
La sortie contient l’identifiant du nouvel espace de noms. Copiez-le, puis remplacez YOUR_ACCOUNT_ID et YOUR_NAMESPACE_ID dans cette configuration complète. Le nom de liaison PREFERENCES est celui que votre code utilisera ; l’ID identifie la ressource Cloudflare réelle.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"kv_namespaces": [
{ "binding": "PREFERENCES", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
Repérez le titre de l’espace de noms de cet atelier et comparez son ID avec celui du fichier. D’autres espaces de noms peuvent être présents : laissez-les inchangés. Cette configuration indique quel compte et quelle ressource les commandes suivantes doivent utiliser. Une liaison est une référence vers un espace de noms, pas une copie de ses données.
Stocker des valeurs JSON et des métadonnées de révision
Dans cette étape, vous allez préparer un petit jeu de données comprenant des paramètres ordinaires et deux erreurs réalistes. En JSON, les noms de champs et les chaînes utilisent des guillemets doubles. Les guillemets simples autour de l’argument de la commande empêchent le shell d’interpréter ces guillemets JSON.
Écrivez les entrées locales. Alice préfère le mode sombre et l’anglais ; Bob préfère le mode clair et le français. --metadata associe un objet JSON distinct à la clé. Ici, son numéro revision identifie la version enregistrée ; il ne s’agit ni d’une décision de sécurité ni d’un compteur de mise à jour automatique.
npx wrangler kv key put account:alice '{"theme":"dark","language":"en"}' --binding PREFERENCES --local --metadata '{"revision":7}'
npx wrangler kv key put account:bob '{"theme":"light","language":"fr"}' --binding PREFERENCES --local --metadata '{"revision":8}'
npx wrangler kv key put account:broken 'not-json' --binding PREFERENCES --local
npx wrangler kv key put account:invalid '{"theme":"neon","language":"en"}' --binding PREFERENCES --local
account:broken contient un texte qui ne peut pas être analysé comme du JSON. account:invalid contient un JSON valide, mais indique un thème que l’application ne prend pas en charge. Ces deux cas vous permettent de distinguer l’analyse syntaxique — la lecture de la structure du texte — de la validation — la vérification que les champs sont acceptables pour l’application. Ne créez pas d’entrée pour Charlie : elle servira à tester le chemin correspondant à une clé manquante.
npx wrangler kv key list --binding PREFERENCES --local
Repérez quatre noms de clés. Alice et Bob doivent avoir des métadonnées de révision égales à 7 et 8. Les deux autres entrées n’ont pas de métadonnées. La liste affiche les noms et les métadonnées ; elle n’affiche pas toutes les valeurs.
npx wrangler kv key get account:alice --binding PREFERENCES --local --text
Vous devez obtenir {"theme":"dark","language":"en"}. La commande lit uniquement la valeur ; la révision ne fait donc pas partie de ce texte JSON.
Écrivez maintenant les quatre mêmes données synthétiques dans l’espace de noms cloud de cet atelier. Ces commandes distantes explicites sont des opérations distinctes : les écritures locales ne sont jamais téléversées automatiquement vers Cloudflare.
npx wrangler kv key put account:alice '{"theme":"dark","language":"en"}' --binding PREFERENCES --remote --metadata '{"revision":7}'
npx wrangler kv key put account:bob '{"theme":"light","language":"fr"}' --binding PREFERENCES --remote --metadata '{"revision":8}'
npx wrangler kv key put account:broken 'not-json' --binding PREFERENCES --remote
npx wrangler kv key put account:invalid '{"theme":"neon","language":"en"}' --binding PREFERENCES --remote
npx wrangler kv key list --binding PREFERENCES --remote
Vérifiez que les quatre mêmes noms de clés et leurs métadonnées de révision sont présents. Il s’agit de données de démonstration que vous pouvez supprimer. Laissez les espaces de noms sans rapport avec cet atelier inchangés.
Lire les préférences avec des valeurs par défaut sûres
Dans cette étape, vous allez écrire un gestionnaire qui récupère simultanément la valeur et les métadonnées. getWithMetadata() renvoie un objet contenant les champs value et metadata. Une clé manquante possède une valeur null. Les métadonnées peuvent également être null, même lorsqu’une valeur existe.
Écrivez ce gestionnaire. Le here-document JS placé entre guillemets conserve exactement le code fourni. La route accepte un identifiant de compte court en minuscules et construit une clé distincte, comme account:alice ; elle ne stocke jamais le compte d’une requête précédente dans une variable globale.
cat > src/index.js <<'JS'
function fallback(account, source) {
return Response.json({
account, theme: "light", language: "en", source, revision: null
});
}
export default {
async fetch(request, env) {
const match = new URL(request.url).pathname.match(/^\/preferences\/([a-z]{1,20})$/);
if (!match) return new Response("Not found", { status: 404 });
const account = match[1];
let entry;
try {
entry = await env.PREFERENCES.getWithMetadata(`account:${account}`, "text");
} catch {
return Response.json({ error: "Preferences temporarily unavailable" }, { status: 503 });
}
if (entry.value === null) return fallback(account, "missing");
let preferences;
try {
preferences = JSON.parse(entry.value);
} catch {
return fallback(account, "invalid");
}
if (!preferences || typeof preferences !== "object" || Array.isArray(preferences) ||
!["light", "dark"].includes(preferences.theme) ||
!["en", "fr"].includes(preferences.language)) {
return fallback(account, "invalid");
}
const revision = Number.isInteger(entry.metadata?.revision) && entry.metadata.revision > 0
? entry.metadata.revision : null;
return Response.json({
account, theme: preferences.theme, language: preferences.language,
source: "stored", revision
});
}
};
JS
Le premier bloc try/catch gère une lecture KV indisponible avec HTTP 503, ce qui signifie que le service est temporairement indisponible. Il ne prétend pas que le compte est absent. La lecture au format "text", suivie d’une analyse dans un autre bloc try/catch, permet d’identifier un JSON endommagé sans le confondre avec une défaillance du stockage. L’option "json" peut analyser automatiquement le contenu, mais cette leçon sépare les deux opérations afin de rendre visibles leurs chemins d’erreur.
Les préférences manquantes et invalides utilisent toutes deux le mode clair et l’anglais comme valeurs de repli. Le champ source explique pourquoi cette valeur de repli a été utilisée. Pour une valeur valide, la réponse utilise uniquement les champs de thème et de langue pris en charge. entry.metadata?.revision gère sans erreur l’absence de métadonnées ; une révision entière positive est affichée, sinon la valeur est null. Ces valeurs par défaut permettent de conserver des choix d’affichage facultatifs utilisables ; elles ne remplacent pas un mécanisme d’authentification ou d’autorisation.
Démarrez le Worker local, enregistrez son ID de processus, puis attendez le message indiquant qu’il est prêt :
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
Le processus en arrière-plan vous permet de continuer à utiliser le terminal ; local.log contient sa sortie. Réexécutez la commande d’affichage du journal si le démarrage n’est pas terminé. Testez chaque cas :
curl -i http://127.0.0.1:8080/preferences/alice
curl -i http://127.0.0.1:8080/preferences/bob
curl -i http://127.0.0.1:8080/preferences/charlie
curl -i http://127.0.0.1:8080/preferences/broken
curl -i http://127.0.0.1:8080/preferences/invalid
Les cinq requêtes doivent renvoyer HTTP 200 avec du JSON. Vérifiez les différences :
| Compte | Thème | Langue | Source | Révision |
|---|---|---|---|---|
| alice | dark | en | stored | 7 |
| bob | light | fr | stored | 8 |
| charlie | light | en | missing | null |
| broken | light | en | invalid | null |
| invalid | light | en | invalid | null |
Par exemple, le corps de la réponse pour Alice est {"account":"alice","theme":"dark","language":"en","source":"stored","revision":7}. Demandez de nouveau les préférences d’Alice après celles de Bob : elles doivent toujours appartenir à Alice. Laissez le serveur local en fonctionnement jusqu’au nettoyage.
Vérifier le service de préférences déployé
Dans cette étape, vous allez exécuter les mêmes tests avec l’espace de noms cloud. Cette vérification indépendante confirme le compte sélectionné, la liaison de l’espace de noms déployée, les enregistrements stockés et les réponses HTTP réelles.
npx wrangler deploy
Vérifiez dans la sortie le nom du Worker généré et la liaison PREFERENCES. Copiez l’adresse publique déployée dans la variable ci-dessous en remplaçant l’exemple :
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/preferences/alice"
curl -i "$WORKER_URL/preferences/bob"
curl -i "$WORKER_URL/preferences/charlie"
curl -i "$WORKER_URL/preferences/broken"
curl -i "$WORKER_URL/preferences/invalid"
Comparez les cinq réponses avec le tableau local. Alice et Bob doivent conserver leurs propres préférences et métadonnées de révision ; Charlie ainsi que les deux enregistrements endommagés doivent utiliser les valeurs par défaut expliquées. Si une entrée récemment écrite n’est pas encore visible, attendez la propagation de KV, puis réessayez. Un nom d’hôte public peut également nécessiter un délai après son premier déploiement. Ne considérez pas une erreur de connexion comme une réponse de repli.
Dans le Dashboard, sélectionnez le compte d’apprentissage, ouvrez Storage & databases → Workers KV et recherchez l’espace de noms labex-prefs-...-preferences de cet atelier. Sélectionnez KV Pairs, examinez les quatre enregistrements et cliquez sur View à côté de account:alice pour comparer sa valeur JSON avec le terminal. Cette vue affiche les clés et les valeurs ; comparez les métadonnées de révision avec la liste de clés Wrangler précédente et la réponse de l’API. Le nom unique et les ID seront différents de ceux de l’exemple.
Le point de terminaison public est uniquement une démonstration de paramètres d’affichage synthétiques. Un véritable service privé de préférences identifierait son appelant avant de déterminer la clé de compte à laquelle celui-ci peut accéder.
Supprimer les ressources cloud temporaires
Dans cette étape, vous allez supprimer les deux ressources pendant que Wrangler est encore autorisé. Un espace de noms peut subsister après la suppression de son Worker ; supprimer uniquement l’application ne supprime donc pas ses données.
Arrêtez le processus de développement local démarré dans ce terminal :
kill "$DEV_PID"
Examinez les références aux ressources enregistrées avant toute suppression :
cat wrangler.jsonc
Vérifiez le nom du Worker labex-prefs-... et l’ID de l’espace de noms PREFERENCES. Supprimez le Worker sélectionné par cette configuration :
npx wrangler delete
Si une confirmation est demandée, vérifiez que le nom affiché correspond à cet atelier, puis répondez y. Supprimez ensuite uniquement l’espace de noms référencé par PREFERENCES :
npx wrangler kv namespace delete --binding PREFERENCES
Vérifiez l’espace de noms dans toute demande de confirmation avant d’accepter. Conservez wrangler.jsonc intact afin que la vérification indépendante puisse identifier les ressources qui doivent avoir disparu.
npx wrangler kv namespace list
L’espace de noms de cet atelier doit être absent ; les espaces de noms sans rapport doivent rester présents. Actualisez les listes du Dashboard pour confirmer que le Worker et l’espace de noms de l’atelier ont disparu. Une requête échouée ou une connexion expirée ne prouve pas la suppression. Effectuez la vérification de cette étape avant de vous déconnecter afin qu’elle puisse consulter un inventaire autorisé.
Mettre fin à l’autorisation de la VM
Dans cette étape, vous allez déconnecter Wrangler une fois la vérification du nettoyage terminée. La déconnexion supprime l’autorisation Wrangler enregistrée pour cette VM ; elle ne supprime pas les ressources cloud et ne vous déconnecte pas de votre session Dashboard habituelle dans le navigateur.
npx wrangler logout
npx wrangler whoami --json
Vérifiez que le résultat structuré indique "loggedIn": false. Cette commande non authentifiée peut se terminer avec un code de sortie différent de zéro, ce qui est attendu ici. Si elle renvoie uniquement une erreur de connexion sans état d’authentification explicite, réessayez lorsque la connexion fonctionnera.
Les fichiers locaux restants et l’état KV local appartiennent à cette VM temporaire. Ils sont distincts des ressources cloud que vous avez déjà supprimées. Vous pouvez maintenant terminer l’atelier.
Résumé
Vous avez stocké des préférences structurées et des métadonnées de révision dans Workers KV, puis vous les avez lues via une liaison Worker. Vous avez conservé séparément les paramètres d’Alice et de Bob et fait en sorte que les valeurs manquantes, malformées ou non prises en charge produisent des valeurs par défaut expliquées. Vous avez également distingué une défaillance du stockage d’un enregistrement absent, au lieu de masquer les deux situations derrière la même réponse.
Après avoir comparé les réponses locales et cloud, vous avez supprimé le Worker et l’espace de noms temporaires, puis vous vous êtes déconnecté. Ensuite, vous ajouterez une date d’expiration aux avis temporaires d’une application ainsi qu’une expiration KV.
