Aller au contenu principal

Recettes de scénarios classiques

Combinez les concepts et les scripts en flux de travail réels. Chaque scénario fournit : objectif → déroulé → scripts à coller directement dans l'interface → résultat attendu. Toute la logique de script a été vérifiée de bout en bout dans l'app réelle.

Les exemples utilisent le serveur de test local (/oauth2/token, /protected, /echo, /json, etc.). Remplacez par vos propres chemins et Pre-URLs quand vous ciblez vos propres API.


Scénario 1 : login pour le token, attachement automatique pour tout le groupe​

Objectif : appeler l'API de login, stocker le token, et faire en sorte que toutes les requêtes suivantes l'attachent automatiquement — sans copier-coller manuel.

Requête A — login (le script de post-réponse stocke le token)​

POST /oauth2/token, body de formulaire : grant_type=password&username=qruser&password=qrpass&client_id=qr-client&client_secret=qr-secret

Ajoutez une étape script à la chaîne de post-réponse :

async function onResponse(context, url, response) {
var j = response.body.parseJSON();
if (j && j.access_token) {
sdk.env.set('authToken', j.access_token); // store on the runtime blackboard
sdk.env.set('tokenType', j.token_type || 'Bearer');
}
return response;
}

Requête B — attacher le token (le même script peut être copié dans chaque API autorisée)​

GET /protected, ajoutez une étape script à la chaîne de pré-envoi :

async function onRequest(context, url, request) {
var tok = sdk.env.get('authToken'); // take from the blackboard
var ty = sdk.env.get('tokenType') || 'Bearer';
if (tok) { request.headers.set('Authorization', ty + ' ' + tok); }
return request;
}

Résultat attendu​

ActionRésultat
Envoyer d'abord A (login)200, la réponse contient access_token, token stocké
Puis envoyer B (attach)200, réponse {authorized:true, ...}
Désactiver les scripts, renvoyer B401 (la chaîne de pré-envoi ne tourne pas → aucun token injecté — preuve que c'est bien le script qui l'attache)

Point clé : A et B doivent être dans le même groupe lié au même environnement (les variables d'exécution ont une portée par environnement), et les fragments de chemin sont complétés par la Pre-URL de l'environnement.


Scénario 2 : chiffrer le body en AES, déchiffrer la réponse (chaîne multi-scripts)​

Objectif : chiffrer le body en AES avant l'envoi (seulement du ciphertext sur le fil), déchiffrer la réponse à son arrivée ; démontre aussi l'enchaînement de plusieurs scripts et le partage de données entre eux.

Pourquoi peut-on le découper en plusieurs scripts ? Les scripts d'une même chaîne partagent globalThis : le script ① range les clés/le plaintext, les scripts ②③ les récupèrent. Chaque script garde une seule responsabilité et peut être activé/désactivé indépendamment.

Chaîne de pré-envoi​

Script ① (prépare le contexte et les clés) :

async function onRequest(context, url, request) {
globalThis.__traceId = $uuid.v4();
globalThis.__aesKey = '0123456789abcdef'; // 16 bytes → AES-128
globalThis.__aesIv = 'abcdef0123456789';
globalThis.__plain = request.body.parseText();
request.headers.set('X-Trace-Id', globalThis.__traceId);
return request;
}

Script ② (chiffre le body) :

async function onRequest(context, url, request) {
var cipher = $crypto.encryptAES(globalThis.__plain, globalThis.__aesKey, globalThis.__aesIv);
request.body = cipher; // only ciphertext on the wire
request.headers.set('X-Encrypt', 'AES-128-CBC');
return request;
}

(Optionnel) le script ③ ajoute la logique d'attachement du token du scénario 1.

Chaîne de post-réponse (déchiffrer + réécrire la réponse)​

async function onResponse(context, url, response) {
var j = response.body.parseJSON();
var cipher = j && j.body && j.body.utf8; // /echo echoes the request body in body.utf8
var recovered = cipher ? $crypto.decryptAES(cipher, globalThis.__aesKey, globalThis.__aesIv) : '';
var obj = null; try { obj = JSON.parse(recovered); } catch (e) {}
response.body = JSON.stringify({
traceId: globalThis.__traceId, decrypted: recovered,
roundtripOk: recovered === globalThis.__plain, jsonValid: !!obj,
});
return response;
}

Body de la requête (avant chiffrement) : {"order":123,"note":"secret-payload","amount":99.5}

Résultat attendu​

Après l'envoi vous obtenez :

{"traceId":"...","decrypted":"{\"order\":123,\"note\":\"secret-payload\",\"amount\":99.5}","roundtripOk":true,"jsonValid":true}
  • roundtripOk:true : le résultat déchiffré correspond octet pour octet au plaintext d'origine
  • Le body de réponse réécrit est visible dans le résultat (preuve que la réécriture de post-réponse a pris effet)

⚠️ Les arguments de $crypto sont des chaînes positionnelles ; en cas d'échec il renvoie seulement une chaîne commençant par Error: — il ne lance pas d'exception et n'interrompt rien (vérifié : ciphertext invalide → Invalid ciphertext, clé/iv erronés → CryptoKit error). Le plaintext chinois / non ASCII se chiffre et se déchiffre correctement (l'ancienne affirmation selon laquelle « non ASCII interrompt » a été démentie). Si vous devez écrire un résultat déchiffré dans un header HTTP, assurez-vous que la valeur est ASCII (les valeurs de header rejettent le non ASCII, sinon un TypeError est lancé) ; mettez plutôt le contenu UTF-8 dans le body ou les query params.


Scénario 3 : extraction · assertion · variables dynamiques · signature​

Un ensemble d'automatisations légères — la plupart n'exigent aucun JS, avec des étapes déclaratives extraction / assertion.

3.1 Passer un champ de réponse à la requête suivante (extraction)​

  • Ajoutez une étape extraction à la chaîne de post-réponse de la requête A : variable author, source response body JSON, expression $.slideshow.author.
  • Ajoutez une étape script à la chaîne de pré-envoi de la requête B : var v=sdk.env.get('author'); if(v){ request.headers.set('X-Extracted', v); } return request;

Vérifié : le /echo de la requête B renvoie bien un header X-Extracted correspondant à l'auteur de la réponse de la requête A.

3.2 Assertions​

Ajoutez des étapes assertion à la chaîne de post-réponse : code de statut = 200, $.slideshow.title exists. Les résultats sont listés un par un (réussite/échec, attendu vs réel).

3.3 Variables dynamiques​

Écrivez-les directement dans les params / headers / URL :

GET /echo?ts={{$timestamp}}&r={{$randomInt}}&u={{$uuid}}

Vérifié : chaque envoi renvoie ts comme horodatage courant, r comme un entier aléatoire différent, et u comme un UUID valide. Liste complète : concepts, variables dynamiques.

3.4 Signature (MD5, standard et interopérable)​

Beaucoup d'API ouvertes signent avec MD5(param concatenation + secret). Utilisez le $hash.md5 au standard vérifié :

async function onRequest(context, url, request) {
var appId = sdk.env.get('appId');
var secret = sdk.env.get('appSecret'); // keep secrets in environment variables
var ts = String(Math.floor(Date.now() / 1000));
var sign = $hash.md5(appId + ts + secret); // concatenation order per your backend's convention
request.queries.set('appId', appId);
request.queries.set('ts', ts);
request.queries.set('sign', sign);
return request;
}

Vérifié : $hash.md5('abc') = 900150983cd24fb0d6963f7d28e17f72, conforme au backend.

✅ Le $hmac natif ($hmac.sha256(message, key) etc.) a été vérifié vecteur par vecteur contre le HMAC RFC standard (attention à l'ordre des arguments : données d'abord, clé ensuite) et peut servir pour la signature externe ; la famille $hash est standard aussi. Seul $jwt dégrade les payloads objet en [object Object] (stringifiez d'abord avec JSON.stringify, ou signez côté serveur).


Scénario 4 : réutiliser la logique partagée avec les bibliothèques de scripts et require()​

Objectif : extraire « injection du token », « signature unifiée » et « journalisation » en unités réutilisables — référencées à de nombreux endroits, maintenues à un seul.

Deux façons de réutiliser :

  • Étape de script de bibliothèque : un script complet avec ses propres onRequest/onResponse — ajoutez-le comme étape et il s'exécute dans l'ordre, partageant globalThis avec les autres étapes.
  • require() : enregistrez des fonctions pures dans une bibliothèque de scripts avec module.exports, puis chargez-les depuis n'importe quel script — idéal pour les aides à la signature, les codecs et autres utilitaires partagés :
// script library "sign-lib" (no entry function needed)
function sign(method, path, body, secret) {
return $hmac.sha256(method + path + body, secret);
}
module.exports = { sign };
// any request script
async function onRequest(context, url, request) {
const { sign } = require('@libs/sign-lib');
request.headers.set('X-Sign', sign('POST', request.path, request.body.parseText(), sdk.env.get('appSecret')));
return request;
}

Utilisez Copier l'instruction require dans le gestionnaire de bibliothèques pour obtenir la forme à identifiant stable. Les bibliothèques intégrées (@libs/base64, @libs/hex) sont disponibles partout sans configuration. Mécanique complète : scripts, Require de bibliothèques de scripts.


Aide-mémoire des scénarios​

Je veux…Quelles étapes
Attacher automatiquement le token à chaque API après le loginScript de post-réponse qui stocke + script de pré-envoi qui lit et injecte le header
Chiffrer le body de la requête / déchiffrer la réponse$crypto.encryptAES en pré-envoi + decryptAES en post-réponse
Passer un champ de réponse à la requête suivanteÉtape d'extraction + script lisant la variable
Valider les codes de statut / champsÉtape d'assertion
Générer des valeurs aléatoires / horodatages à chaque envoiVariables dynamiques comme {{$uuid}}
Signer une API ouverte$hash.md5(...) (standard)
Réutiliser la même logique à de nombreux endroitsScript de bibliothèque, ou require('@libs/<key>') d'une bibliothèque de scripts