Recetas de escenarios clásicos
Combina conceptos y scripts en flujos de trabajo reales. Cada escenario ofrece: objetivo → flujo → scripts que puedes pegar directamente en la interfaz → resultado esperado. Toda la lógica de los scripts ha sido verificada de extremo a extremo en la app real.
- Escenario 1: login para el token, adjuntarlo automáticamente a todo el grupo
- Escenario 2: cifrar el cuerpo de la solicitud con AES y descifrar la respuesta (cadena de varios scripts)
- Escenario 3: extracción · aserciones · variables dinámicas · firma
- Escenario 4: reutilizar lógica compartida con scripts de biblioteca y
require()
Los ejemplos usan el servidor de pruebas local (
/oauth2/token,/protected,/echo,/json, etc.). Sustituye las rutas y Pre-URLs por las tuyas al apuntar a tus propias APIs.
Escenario 1: Login para el token, adjuntarlo automáticamente a todo el grupo
Objetivo: llamar a la API de login, almacenar el token y hacer que todas las solicitudes posteriores lo adjunten automáticamente — sin copiar a mano.
Solicitud A — login (el script de post-respuesta almacena el token)
POST /oauth2/token, cuerpo de formulario: grant_type=password&username=qruser&password=qrpass&client_id=qr-client&client_secret=qr-secret
Añade un paso de script a la cadena de post-respuesta:
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;
}
Solicitud B — adjuntar el token (el mismo script puede copiarse a todas las APIs que requieren autorización)
GET /protected, añade un paso de script a la cadena de envío previo:
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;
}
Resultado esperado
| Acción | Resultado |
|---|---|
| Enviar A primero (login) | 200, la respuesta contiene access_token, token almacenado |
| Después enviar B (adjuntar) | 200, respuesta {authorized:true, ...} |
| Desactivar scripts y enviar B de nuevo | 401 (la cadena de envío previo no se ejecuta → no se inyecta token — prueba de que el script es quien lo adjunta) |
Clave: A y B deben estar en el mismo grupo vinculado al mismo entorno (las variables de ejecución tienen ámbito por entorno), y los fragmentos de ruta se completan con la Pre-URL del entorno.
Escenario 2: Cifrar el cuerpo de la solicitud con AES y descifrar la respuesta (cadena de varios scripts)
Objetivo: cifrar el cuerpo con AES antes de enviarlo (por el cable solo viaja cifrado) y descifrar la respuesta al llegar; también demuestra encadenar varios scripts y compartir datos entre ellos.
¿Por qué se puede dividir en varios scripts? Los scripts de la misma cadena comparten
globalThis: el script ① guarda las claves/plaintext y los scripts ②③ los recogen. Cada script mantiene un único propósito y puede activarse o desactivarse de forma independiente.
Cadena de envío previo
Script ① (prepara contexto y claves):
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 ② (cifra el cuerpo):
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;
}
(Opcional) el script ③ añade la lógica de adjuntar el token del Escenario 1.
Cadena de post-respuesta (descifrar y reescribir la respuesta)
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;
}
Cuerpo de la solicitud (antes del cifrado): {"order":123,"note":"secret-payload","amount":99.5}
Resultado esperado
Tras el envío obtienes:
{"traceId":"...","decrypted":"{\"order\":123,\"note\":\"secret-payload\",\"amount\":99.5}","roundtripOk":true,"jsonValid":true}
roundtripOk:true: el resultado descifrado coincide byte a byte con el plaintext original- El cuerpo reescrito de la respuesta se ve en el resultado (prueba de que la reescritura de post-respuesta surtió efecto)
⚠️ Los argumentos de
$cryptoson cadenas posicionales; ante un fallo solo devuelve una cadena que empieza porError:— no lanza excepciones ni aborta (verificado: ciphertext inválido →Invalid ciphertext, clave/iv incorrectos →CryptoKit error). El plaintext con chino / no ASCII cifra y descifra correctamente (la antigua afirmación de que «lo no ASCII aborta» quedó desmentida). Si necesitas escribir un resultado descifrado en una cabecera HTTP, asegúrate de que el valor sea ASCII (los valores de cabecera rechazan el no ASCII; de lo contrario se lanza unTypeError); pon el contenido UTF-8 en el cuerpo o en los query params.
Escenario 3: Extracción · aserciones · variables dinámicas · firma
Un conjunto de automatizaciones ligeras — la mayoría no necesita JS en absoluto, usando pasos declarativos de extracción / aserción.
3.1 Pasar un campo de la respuesta a la siguiente solicitud (extract)
- Añade un paso de extract a la cadena de post-respuesta de la solicitud A: variable
author, fuenteresponse body JSON, expresión$.slideshow.author. - Añade un paso de script a la cadena de envío previo de la solicitud B:
var v=sdk.env.get('author'); if(v){ request.headers.set('X-Extracted', v); } return request;
Verificado: el /echo de la solicitud B devuelve una cabecera X-Extracted que coincide con el author de la respuesta de la solicitud A.
3.2 Aserciones
Añade pasos de assert a la cadena de post-respuesta: código de estado = 200, $.slideshow.title exists. Los resultados se listan uno a uno (éxito/fallo, esperado vs real).
3.3 Variables dinámicas
Escríbelas directamente en params / headers / URL:
GET /echo?ts={{$timestamp}}&r={{$randomInt}}&u={{$uuid}}
Verificado: cada envío devuelve ts como marca de tiempo actual, r como un entero aleatorio distinto y u como un UUID válido. Lista completa: conceptos, variables dinámicas.
3.4 Firma (MD5, estándar e interoperable)
Muchas APIs abiertas firman con MD5(param concatenation + secret). Usa el $hash.md5 de estándar verificado:
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;
}
Verificado: $hash.md5('abc') = 900150983cd24fb0d6963f7d28e17f72, coincide con el backend.
✅ El
$hmacnativo ($hmac.sha256(message, key)etc.) ha sido verificado vector a vector contra el HMAC estándar RFC (ojo al orden de los argumentos: primero los datos, después la clave) y puede usarse para firmas externas; la familia$hashtambién es estándar. Solo$jwtdegrada los payloads de tipo objeto a[object Object](haz primeroJSON.stringify, o firma en el servidor).
Escenario 4: Reutilizar lógica compartida con scripts de biblioteca y require()
Objetivo: extraer «inyectar token», «firma unificada» y «logging» como unidades reutilizables — se referencian en muchos sitios y se mantienen en uno.
Dos formas de reutilizar:
- Paso de script de biblioteca: un script completo con su propio
onRequest/onResponse— añádelo como paso y se ejecuta en orden, compartiendoglobalThiscon los demás pasos. require(): guarda funciones puras en una biblioteca de scripts conmodule.exportsy cárgalas desde cualquier script — ideal para helpers de firma, códecs y otras utilidades compartidas:
// 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;
}
Usa Copy require statement en el gestor de bibliotecas para obtener la forma de identificador estable. Las bibliotecas integradas (@libs/base64, @libs/hex) están disponibles en cualquier sitio sin configuración. Mecánica completa: scripts, Require de bibliotecas de scripts.
Chuleta de escenarios
| Quiero… | Qué pasos |
|---|---|
| Adjuntar automáticamente el token en cada API tras el login | El script de post-respuesta almacena + el script de envío previo lee e inyecta la cabecera |
| Cifrar el cuerpo de la solicitud / descifrar la respuesta | $crypto.encryptAES en envío previo + decryptAES en post-respuesta |
| Pasar un campo de la respuesta a la siguiente solicitud | Paso de extract + script que lee la variable |
| Validar códigos de estado / campos | Paso de assert |
| Generar valores aleatorios / marcas de tiempo en cada envío | Variables dinámicas como {{$uuid}} |
| Firmar una API abierta | $hash.md5(...) (estándar) |
| Reutilizar la misma lógica en muchos sitios | Script de biblioteca, o require('@libs/<key>') de una biblioteca de scripts |