Passa al contenuto principale

Ricette per scenari classici

Combina concepts e scripting in flussi di lavoro reali. Ogni scenario fornisce: obiettivo → flusso → script da incollare direttamente nella UI → risultato atteso. Tutta la logica degli script è stata verificata end-to-end nell'app reale.

Gli esempi usano il server di test locale (/oauth2/token, /protected, /echo, /json, ecc.). Sostituisci con i tuoi percorsi e Pre-URL quando punta alle tue API.


Scenario 1: Login per il token, allega automaticamente per tutto il gruppo​

Obiettivo: chiamare l'API di login, salvare il token e fare in modo che ogni richiesta successiva lo allegi automaticamente — senza copie manuali.

Richiesta A — login (lo script post-risposta salva il token)​

POST /oauth2/token, corpo form: grant_type=password&username=qruser&password=qrpass&client_id=qr-client&client_secret=qr-secret

Aggiungi uno step di tipo script alla catena post-risposta:

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;
}

Richiesta B — allega il token (lo stesso script si può copiare in ogni API autorizzata)​

GET /protected: aggiungi uno step di tipo script alla catena di pre-invio:

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;
}

Risultato atteso​

AzioneRisultato
Invia prima A (login)200, la risposta contiene access_token, token salvato
Poi invia B (allega)200, risposta {authorized:true, ...}
Disattiva gli script e reinvia B401 (la catena di pre-invio non gira → nessun token iniettato — prova che è lo script ad allegarlo)

Punto chiave: A e B devono trovarsi nello stesso gruppo associato allo stesso ambiente (le variabili di runtime hanno ambito per ambiente), e i frammenti di percorso vengono completati dal Pre-URL dell'ambiente.


Scenario 2: Cifra il corpo della richiesta con AES, decifra la risposta (catena multi-script)​

Obiettivo: cifrare con AES il corpo prima dell'invio (in rete gira solo testo cifrato), decifrare la risposta al suo arrivo; la ricetta mostra anche come concatenare più script e condividere dati tra loro.

Perché si può spezzare in più script? Gli script nella stessa catena condividono globalThis: lo script ① ripone chiavi/testo in chiaro, gli script ②③ li riprendono. Ogni script resta focalizzato su un solo compito e può essere attivato/disattivato singolarmente.

Catena di pre-invio​

Script ① (prepara contesto e chiavi):

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 il corpo):

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;
}

(Facoltativo) lo script ③ aggiunge la logica di allega-token dello Scenario 1.

Catena post-risposta (decifratura + riscrittura della risposta)​

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;
}

Corpo della richiesta (prima della cifratura): {"order":123,"note":"secret-payload","amount":99.5}

Risultato atteso​

Dopo l'invio si ottiene:

{"traceId":"...","decrypted":"{\"order\":123,\"note\":\"secret-payload\",\"amount\":99.5}","roundtripOk":true,"jsonValid":true}
  • roundtripOk:true: il risultato decifrato coincide byte per byte con il testo in chiaro originale
  • Il corpo della risposta riscritto è visibile nel risultato (prova che la riscrittura post-risposta ha avuto effetto)

⚠️ Gli argomenti di $crypto sono stringhe posizionali; in caso di fallimento restituisce solo una stringa che inizia con Error: — non lancia eccezioni né abortisce (verificato: ciphertext sbagliato → Invalid ciphertext, chiave/iv errati → CryptoKit error). Il testo in chiaro cinese / non-ASCII si cifra e decifra correttamente (la vecchia affermazione che «il non-ASCII abortisce» è stata smentita). Se devi scrivere un risultato decifrato in un header HTTP, assicurati che il valore sia ASCII (i valori header rifiutano il non-ASCII, altrimenti viene lanciato un TypeError); metti invece il contenuto UTF-8 nel corpo o nei parametri di query.


Scenario 3: Estrazione · asserzioni · variabili dinamiche · firma​

Un insieme di automazioni leggere — la maggior parte non richiede alcun JS, grazie agli step dichiarativi di estrazione / asserzione.

3.1 Passare un campo della risposta alla richiesta successiva (estrazione)​

  • Aggiungi uno step di estrazione alla catena post-risposta della richiesta A: variabile author, sorgente response body JSON, espressione $.slideshow.author.
  • Aggiungi uno step di tipo script alla catena di pre-invio della richiesta B: var v=sdk.env.get('author'); if(v){ request.headers.set('X-Extracted', v); } return request;

Verificato: la /echo della richiesta B restituisce un header X-Extracted che corrisponde all'autore presente nella risposta della richiesta A.

3.2 Asserzioni​

Aggiungi step di asserzione alla catena post-risposta: codice di stato = 200, $.slideshow.title exists. I risultati vengono elencati uno per uno (superato/fallito, atteso vs effettivo).

3.3 Variabili dinamiche​

Scrivile direttamente in parametri / header / URL:

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

Verificato: a ogni invio l'eco restituisce ts come timestamp corrente, r come intero casuale diverso e u come UUID valido. Lista completa: concepts, variabili dinamiche.

3.4 Firma (MD5, standard e interoperabile)​

Molte API pubbliche firmano con MD5(param concatenation + secret). Usa $hash.md5, verificato come standard:

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;
}

Verificato: $hash.md5('abc') = 900150983cd24fb0d6963f7d28e17f72, coincide con il backend.

✅ Il $hmac nativo ($hmac.sha256(message, key) ecc.) è stato verificato vettore per vettore come conforme all'HMAC RFC standard (attenzione all'ordine degli argomenti: prima i dati, poi la chiave) e può essere usato per firme esterne; anche la famiglia $hash è standard. Solo $jwt degrada i payload oggetto in [object Object] (prima esegui lo stringify con JSON.stringify, oppure firma sul server).


Scenario 4: Riutilizzo della logica condivisa con script di libreria e require()​

Obiettivo: estrarre «allega token», «firma unificata» e «logging» in unità riutilizzabili — referenziate in molti punti, mantenute in uno solo.

Due modi per riutilizzare:

  • Step script di libreria: uno script completo con i propri onRequest/onResponse — aggiungilo come step e viene eseguito in ordine, condividendo globalThis con gli altri step.
  • require(): salva funzioni pure in una libreria di script con module.exports, poi caricale da qualunque script — ideale per helper di firma, codec e altre utilità condivise:
// 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 Copia istruzione require nel gestore delle librerie per la forma a identificatore stabile. Le librerie integrate (@libs/base64, @libs/hex) sono disponibili ovunque senza configurazione. Meccanica completa: scripting, Importare librerie di script.


Promemoria degli scenari​

Voglio…Quali step
Allega automaticamente il token a ogni API dopo il loginLo script post-risposta salva + lo script pre-invio legge e inietta l'header
Cifrare il corpo della richiesta / decifrare la risposta$crypto.encryptAES in pre-invio + decryptAES post-risposta
Passare un campo della risposta alla richiesta successivaStep di estrazione + script che legge la variabile
Validare codici di stato / campiStep di asserzione
Generare valori casuali / timestamp a ogni invioVariabili dinamiche come {{$uuid}}
Firmare un'API pubblica$hash.md5(...) (standard)
Riutilizzare la stessa logica in molti puntiScript di libreria, oppure require('@libs/<key>') di una libreria di script