Passa al contenuto principale

Riferimento API degli script

Hodor esegue i tuoi script in un motore JavaScript integrato. A seconda del tipo di script, Hodor chiama una delle funzioni di ingresso qui sotto al momento giusto — implementi solo la logica che ti serve. Se non modifichi nulla, elimina la funzione di ingresso inutilizzata per evitare chiamate superflue.

Oggetti globali e classi disponibili:

CategoriaNomi
Funzioni di ingressoonRequest, onResponse, onSessionCompleted, onSchedule, abort()
Moduli nativi $$codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log
API standard Webfetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console
Classi HTTPRequest, Response, Body, Headers, URLSearchParams
StorageSharedPreferences, variabili sdk
ContestiRewriteContext, CompletedContext, ScheduleContext
suggerimento

Usa console.log(...) ovunque in uno script per ispezionare i valori — l'output appare nella vista log dello script.

Funzioni di ingresso​

Gli script vengono rilevati scandendo le dichiarazioni async function — il numero di parametri di ciascuna funzione di ingresso è fisso (onRequest/onResponse ne prendono 3, onSessionCompleted 4, onSchedule 1). Le assegnazioni a arrow function (let onRequest = async (...) => {}) non vengono rilevate. I nomi dei parametri sono liberi.

onRequest(context, url, request)​

Progettata per Rewrite Script e per gli script pre-request di Quick Request. Questa funzione viene chiamata prima che la richiesta HTTP venga inviata al server. Restituisci la request (eventualmente modificata).

ParametroTipoDescrizione
contextRewriteContextL'oggetto contesto.
urlstringL'URL della richiesta HTTP.
requestRequestL'oggetto richiesta HTTP.
// modify request body
async function onRequest(context, url, request) {
// parse to Text
var text = request.body.parseText()
console.log(text)
request.body = "this is a replaced request text"

// parse to JSON
var json = request.body.parseJSON()
json["script_json"] = "JSONValue"
request.body = json

// parse to URLSearchParams
var urlencoded = request.body.parseURLSearchParams()
urlencoded.append("script", "parseURLSearchParams")
request.body = urlencoded
// Done
return request;
}
// redirect, modify path / queries / headers
async function onRequest(context, url, request) {
console.log(url);
// set a parameter, you can get it in onResponse
context.parameters["custom"] = "custom parameter on request"

// redirect
request.scheme = "http"
request.path = "/upload/json"
request.host = "192.168.3.30"
request.port = 6000
// change method
request.method = "POST"

// queries operation
request.queries.append("name", "value1") // add query
request.queries.set("name", "value2") // replace or add query
request.queries.get("name") // get query by name
request.queries.delete("name") // delete query by name

// headers operation
request.headers.delete("accept") // delete header by name
request.headers.append("hodor", "custom value") // add name-value pair
request.headers.forEach((value, name) => {
console.log(name + ":" + value)
});
// Done
return request;
}

onResponse(context, url, response)​

Progettata per Rewrite Script e per gli script post-response di Quick Request. Questa funzione viene chiamata prima che la risposta HTTP venga inviata al client. Restituisci la response (eventualmente modificata).

ParametroTipoDescrizione
contextRewriteContextL'oggetto contesto.
urlstringL'URL della risposta HTTP.
responseResponseL'oggetto risposta HTTP.
// response body
async function onResponse(context, url, response) {
// parse to Text
var text = response.body.parseText()
console.log(text)
response.body = "this is a replaced response text"

// parse to JSON
var json = response.body.parseJSON()
json["script_json"] = "JSONValue"
response.body = json

// parse to URLSearchParams
var urlencoded = response.body.parseURLSearchParams()
urlencoded.append("script", "parseURLSearchParams")
response.body = urlencoded
// Done
return response;
}
// change status code and headers
async function onResponse(context, url, response) {
// get parameters set in onRequest
console.log(context.parameters["custom"]) // Output "custom parameter on request"

response.statusCode = 200 // change status code
response.statusPhrase = "OK" // change status phrase

response.headers.delete("accept")
response.headers.append("hodor", "custom value")
response.headers.forEach((value, name) => {
console.log(name + ":" + value)
});
// Done
return response
}

onSessionCompleted(context, url, request, response)​

Progettata per HTTP Completed Script. Chiamata in modo asincrono dopo che la risposta HTTP è stata restituita, senza influire sulla trasmissione dei dati tra l'app e il server. Utile per la raccolta e l'inoltro dei dati.

ParametroTipoDescrizione
contextCompletedContextL'oggetto contesto.
urlstringL'URL della richiesta HTTP.
requestRequestL'oggetto richiesta HTTP.
responseResponseL'oggetto risposta HTTP.
// sample: pass session data to your own server
async function onSessionCompleted(context, url, request, response) {
try {
var reqText = request.body.parseText();
var rspText = response.body.parseText()
var params = {
"body": { // HTTPClient post body data
"url": url, // request url
"reqHeader": request.headers.encode(), // request headers
"reqText": reqText, // request body
"rspHeader": response.headers.encode(), // response headers
"rspText": rspText, // response body
},
"headers": { // HTTPClient headers
"from": "onSessionCompleted"
},
}
const rsp = await HTTPClient.post("http://192.168.3.30:8000/upload", params)
let text = rsp.body.parseText()
console.log(text)
} catch(error) {
console.log(error)
}
}

onSchedule(context)​

Progettata per Schedule Script. Chiamata all'ora di attivazione pianificata (sono supportate espressioni cron a 5 o 6 parti). Usa abort() per fermare il ciclo pianificato.

ParametroTipoDescrizione
contextScheduleContextL'oggetto contesto.
async function onSchedule(context) {
// set custom parameters for next runloop
context.parameters["custom"] = "custom parameters for next runloop";
// repeated count
console.log(`repeatedCount ${context.repeatedCount}`);
// if repeatedCount is 2, abort schedule
if (context.repeatedCount == 2) {
abort()
}
// you can also use HTTPClient to send requests
const rsp = await HTTPClient.get("https://www.apple.com")
let text = rsp.body.parseText()
console.log(text)
}

abort()​

Dentro gli script di canale (onRequest / onResponse / onSchedule), chiama abort() per fermare lo script e abortire immediatamente l'esecuzione corrente — lancia un AbortError che Hodor ti segnala.

// ✅ correct — abort() is injected into the script scope
async function onRequest(context, url, request) {
if (url.includes("/tracking")) abort();
return request;
}
warning

Non dichiarare onRequest(context, url, request, aborter) con un quarto parametro. Il numero di parametri delle funzioni di ingresso è fisso — un quarto parametro rende l'ingresso non rilevabile.

Moduli nativi​

Tutti i moduli con prefisso $ vengono iniettati quando il runtime si attiva. Sono implementati nativamente, ritornano in modo sincrono (se non indicato diversamente) e trattano gli input stringa come UTF-8.

$codec — Codifica e decodifica​

Base64 / Hex / codifica percentuale URL per la conversione di protocollo e il trasferimento dati.

MetodoRestituisce
$codec.base64Encode(str)Stringa Base64.
$codec.base64Decode(str)Stringa decodificata; input non valido restituisce "" (non lancia).
$codec.hexEncode(str)Stringa hex minuscola.
$codec.hexDecode(str)Stringa decodificata; i caratteri non validi vengono saltati.
$codec.urlEncode(str)Stringa codificata in percentuale.
$codec.urlDecode(str)Stringa decodificata; le sequenze non valide vengono restituite così come sono.
$codec.base64Encode("Hello, World!"); // "SGVsbG8sIFdvcmxkIQ=="
$codec.base64Decode("SGVsbG8sIFdvcmxkIQ=="); // "Hello, World!"
$codec.hexEncode("ABC"); // "414243"
$codec.hexDecode("414243"); // "ABC"
$codec.urlEncode("hello world&foo=bar"); // "hello%20world%26foo%3Dbar"

$hash — Hashing​

Calcolo di digest per controlli di integrità, content addressing e anonimizzazione. Restituisce hex minuscolo.

MetodoLunghezza output
$hash.md5(str)32 caratteri hex
$hash.sha1(str)40 caratteri hex
$hash.sha256(str)64 caratteri hex
$hash.sha384(str)96 caratteri hex
$hash.sha512(str)128 caratteri hex
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

// integrity check
const checksum = $hash.sha256(JSON.stringify({user: "admin"}));

$hmac — Message Authentication Code​

Hashing con chiave per la firma di API e il rilevamento di manomissioni. Sia (data, key) sono codificati UTF-8; restituisce hex minuscolo.

MetodoAlgoritmo
$hmac.md5(data, key)HMAC-MD5
$hmac.sha1(data, key)HMAC-SHA1
$hmac.sha256(data, key)HMAC-SHA256
$hmac.sha384(data, key)HMAC-SHA384
$hmac.sha512(data, key)HMAC-SHA512
const signature = $hmac.sha256("important data", "my-secret-key");
const isValid = (signature === $hmac.sha256("important data", "my-secret-key")); // true

$crypto — Cifratura simmetrica​

AES-GCM con autenticazione (consigliata) e DES (compatibilità legacy).

MetodoRestituisce
$crypto.encryptAES(plaintext, password, options?)Ciphertext Base64; i fallimenti restituiscono una stringa "Error: <reason>".
$crypto.decryptAES(ciphertext, password, options?)Testo in chiaro; ciphertext non valido restituisce "Error: Invalid ciphertext".
$crypto.encryptDES(plaintext, key)DES-ECB + PKCS7, chiave troncata a 8 byte → Base64.
$crypto.decryptDES(ciphertext, key)Testo in chiaro; input non-Base64 restituisce "".

options: { keySize: 128 \| 192 \| 256 } (predefinito 256). Il formato del testo cifrato AES è base64(nonce[12] + ciphertext + tag[16]) — va in coppia con decryptAES; quando interoperi con altri linguaggi devi spacchettare tu stesso questo formato.

const encrypted = $crypto.encryptAES("sensitive data", "my-password");
$crypto.decryptAES(encrypted, "my-password"); // "sensitive data"

// 128-bit key
const e128 = $crypto.encryptAES("data", "pass", { keySize: 128 });

// errors are returned as strings, not thrown — check the prefix
const out = $crypto.decryptAES("not-base64!!", "p");
if (out.startsWith("Error:")) { /* handle error */ }

$jwt — JSON Web Token​

Creazione, parsing e verifica di firma JWT (famiglia HMAC) per gli script dei flussi di autenticazione.

MetodoRestituisce
$jwt.sign(payload, secret, algorithm?)Stringa JWT; predefinito HS256.
$jwt.decode(token)Oggetto {header, payload} (la firma non viene verificata); restituisce null per token malformati.
$jwt.verify(token, secret, algorithm?)boolean — risultato della verifica della firma.

algorithm: "HS256" | "HS384" | "HS512".

// sign
const payload = JSON.stringify({ sub: "user123", exp: Math.floor(Date.now() / 1000) + 3600 });
const token = $jwt.sign(payload, "my-secret", "HS256");

// decode — returns an object directly, no JSON.parse needed
const decoded = $jwt.decode(token);
decoded.header.alg; // "HS256"
decoded.payload.sub; // "user123"

// verify
$jwt.verify(token, "my-secret", "HS256"); // true
$jwt.verify(token, "wrong-secret", "HS256"); // false

// expiry check
const exp = $jwt.decode(token).payload.exp;
const expired = exp * 1000 < Date.now();

$format — Formattazione dati​

Pretty-print e minificazione JSON/XML per logging e debug. Le chiavi JSON vengono ordinate alfabeticamente nell'output.

MetodoRestituisce
$format.json(str, indent?)JSON pretty-printed; indent limitato a 1–8 (predefinito 2); input non valido restituisce "Error: Invalid JSON".
$format.minify(str)JSON minimizzato (chiavi ordinate, senza spazi); input non valido restituisce "Error: Invalid JSON".
$format.xml(str)XML indentato semplice.
$format.json('{"b":1,"a":2}');
// {
// "a": 2,
// "b": 1
// }
$format.json('{"a":2}', 4); // 4-space indent
$format.minify('{ "a": 2 }'); // '{"a":2}'
$format.xml('<root><child>t</child></root>');
// <root>
// <child>t</child>
// </root>

$fs — File System​

Lettura/scrittura file leggera dentro gli script (config, cache, esportazione). I percorsi supportano l'espansione ~; write crea automaticamente le directory genitori mancanti.

MetodoRestituisce
$fs.read(path)Contenuto UTF-8; fallimento restituisce "Error: Cannot read file at <path>".
$fs.readBinary(path)Byte come Base64; fallimento restituisce "".
$fs.write(path, content)boolean — successo.
$fs.exists(path)boolean.
$fs.delete(path)boolean; i file mancanti restituiscono false.
$fs.list(path)string[] delle voci della directory; fallimento restituisce [].
$fs.info(path)Stringa JSON {size, modified, isDirectory, path}; i percorsi mancanti restituiscono undefined.
const file = $env.tmpDir() + "/hodor-test.txt";
$fs.write(file, "Hello from Hodor!");
$fs.read(file); // "Hello from Hodor!"
$fs.exists(file); // true
$fs.list($env.tmpDir()); // ["hodor-test.txt", ...]

const info = JSON.parse($fs.info(file));
info.size; // byte count
info.isDirectory; // false

$fs.delete(file); // true
note

Le forme di fallimento differiscono per metodo: read restituisce una stringa "Error: ...", readBinary restituisce "", list restituisce [] e info restituisce undefined — gestiscile di conseguenza.

$env — Variabili d'ambiente​

Variabili d'ambiente del processo e percorsi di sistema. Nota: $env è l'ambiente del processo (condiviso tra le esecuzioni, vive con il processo). Per variabili persistenti rivolte all'utente usa invece sdk.setEnvVar o SharedPreferences.

MetodoRestituisce
$env.get(key)Valore; le chiavi mancanti restituiscono "".
$env.set(key, value)boolean — risultato di setenv.
$env.all()Stringa JSON di tutte le variabili d'ambiente.
$env.cwd()Directory di lavoro corrente.
$env.tmpDir()Directory temporanea.
$env.homeDir()Directory home dell'utente.
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());

$uuid — UUID​

Genera e valida UUID (ID di richiesta, chiavi di idempotenza).

MetodoRestituisce
$uuid.v4()UUID v4 standard (maiuscolo, con trattini), es. "550e8400-E29B-41D4-A716-446655440000".
$uuid.compact()Forma senza trattini, minuscola.
$uuid.validate(str)Se la stringa è un UUID valido.
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
note

validate accetta solo il formato con trattini — validate($uuid.compact()) restituisce false. Reinserisci i trattini prima di validare una stringa compatta.

$log — Log strutturato​

Righe di log con timestamp e livello instradate attraverso il sistema console del motore (raccolte nella vista log dello script).

MetodoRestituisce
$log.log(level, message, tag?)Riga di log formattata (anche stampata).
$log.debug / info / warn / error(message)Metodi di livello di comodità, solo output.

Formato riga di log: [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (il segmento [tag] viene omesso quando non viene fornito un tag).

$log.info("Server started on port 8080");
// [2025-07-24T01:11:45.548+0800] [INFO] Server started on port 8080
$log.log("info", "Request processed", "API");
// [2025-07-24T01:11:45.548+0800] [INFO] [API] Request processed

API Web​

fetch​

Invia vere richieste HTTP dagli script — il canale principale per i flussi di lavoro in stile Postman.

fetch(url: string, options?: object) → Promise<response>

options:

CampoTipoPredefinitoDescrizione
methodstring"GET"Case-insensitive; i valori sconosciuti ricadono su GET.
timeoutIntervalnumber30Secondi.
headers[[k, v]] o [{k: v}][]Entrambe le forme sono accettate.
textBodystring—Testo del corpo della richiesta.
encodingstring—"hex" significa che textBody è una stringa hex.

Il valore risolto è un oggetto semplice: statusCode (numero), headers (array di oggetti a chiave singola, con le chiavi duplicate conservate) e textBody() — una funzione che restituisce {text, encoding} con rilevamento automatico del set di caratteri (i corpi non decodificabili ricadono su {text: <hex>, encoding: "hex"}). Il valore di rigetto è una stringa di messaggio d'errore.

// GET
const rsp = await fetch("https://httpbin.org/get");
if (rsp.statusCode === 200) {
const body = rsp.textBody(); // {text: "...", encoding: "utf-8"}
const json = JSON.parse(body.text);
}

// POST JSON
const rsp2 = await fetch("https://httpbin.org/post", {
method: "POST",
headers: [["Content-Type", "application/json"]],
textBody: JSON.stringify({a: 1}),
timeoutInterval: 10,
});

HTTPClient​

La classe HTTPClient invia richieste HTTP da qualunque script (implementata sopra fetch). Tutti i metodi sono async e restituiscono un oggetto risposta con statusCode, headers e textBody().

MetodoDescrizione
HTTPClient.get(url, params?)Invia una richiesta GET.
HTTPClient.post(url, params?)Invia una richiesta POST.
HTTPClient.put(url, params?)Invia una richiesta PUT.
HTTPClient.update(url, params?)Invia una richiesta UPDATE.
HTTPClient.delete(url, params?)Invia una richiesta DELETE.
HTTPClient.request(url, method, params?)Invia una richiesta con un metodo personalizzato.

params è un oggetto facoltativo con:

  • headers: oggetto header della richiesta, es. {"key1": "value1"}
  • body: corpo della richiesta — una stringa, un oggetto JSON (serializzato automaticamente) o URLSearchParams
  • timeoutInterval: timeout in secondi (predefinito 60)
try {
var params = {
"headers": {"key1": "value1"},
"body": {"a": "a1", "b": "b1"},
};
const response = await HTTPClient.post("https://dummyjson.com/products/1", params);
console.log(response.textBody().text);
} catch(error) {
console.log(error);
}

Timers​

setTimeout / setInterval / clearTimeout / clearInterval funzionano come nei browser. I callback vengono inviati su una coda seriale del motore, quindi i timer scattano in modo affidabile indipendentemente dal thread ospite.

FunzioneRestituisce
setTimeout(callback, ms)ID timer (stringa), scatta una volta.
setInterval(callback, ms)ID timer, scatta ripetutamente.
clearTimeout(id) / clearInterval(id)Annulla (idempotente, gli id sconosciuti vengono ignorati).
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);

Funzioni globali​

NomeFirmaDescrizione
btoa(str)(string) → stringCodifica Base64 — semantica simmetrica UTF-8 (le stringhe non-Latin1 sono ammesse, a differenza dei browser).
atob(str)(string) → stringDecodifica Base64; input non valido restituisce "".
performance.now()() → numberMillisecondi dall'epoca (non dal caricamento pagina).
sleep(ms)(number) → PromiseSi risolve dopo ms; usa await sleep(1000).
require(id)(string) → anyCarica una libreria di script con semantica CommonJS (module.exports); la chiave è @libs/<key>, risolta come identificatore della libreria di script → nome della libreria di script (unico) → librerie integrate; lancia un errore se non trovata.
TextEncodernew TextEncoder().encode(str)Codifica UTF-8 in un Uint8Array (encoding è sempre "utf-8").
crypto.getRandomValues(n)(Array) → number[]Riempie con n valori UInt32 casuali.
crypto.randomUUID()() → stringUUID casuale (maiuscolo, con trattini).
btoa("Hello"); // "SGVsbG8="
atob("SGVsbG8="); // "Hello"
btoa("中文"); // works — UTF-8 bytes are encoded
performance.now(); // 1760000000000.123
await sleep(100);
const { encode } = require("@libs/base64"); // built-in lib
const { sign } = require("@libs/sign-lib"); // your script library
new TextEncoder().encode("hi"); // Uint8Array [104, 105]

Le librerie si gestiscono nel gestore dei moduli script. La chiave require è sempre @libs/<key>: le tue librerie di script si risolvono prima per identificatore (stabile attraverso i rinomini), poi per nome (corrispondenza unica), poi le librerie integrate @libs/base64 / @libs/hex. Le librerie esportano via module.exports, possono fare require di altre librerie, e una chiave mancante lancia un errore (i fallimenti in pre-invio abortiscono la richiesta, in post-risposta la risposta originale viene conservata). Vedi scripting di Quick Request, Importare librerie di script per la guida completa.

console​

console.log / info / warn / error stampa i valori nella vista log dello script. Più argomenti vengono serializzati, quindi puoi loggare direttamente oggetti e array:

console.log("headers", {Accept: "application/json"}, [1, 2, 3]);

$log offre output strutturato con livelli (vedi $log) — entrambi i canali sono visibili nella vista log degli script di Hodor.

Classi HTTP​

Request​

La classe Request è la richiesta HTTP impacchettata passata a onRequest / onSessionCompleted.

MembroTipoDescrizione
schemestring (get / set)Lo scheme della richiesta, es. https.
hoststring (get / set)L'host della richiesta.
portnumber (get / set)La porta della richiesta.
pathstring (get / set)Il path della richiesta.
methodstring (get / set)Il metodo HTTP, es. GET.
queriesURLSearchParams (get)I parametri di query della richiesta.
headersHeaders (get)Gli header della richiesta.
bodyBody (get) / string | Map | Array | URLSearchParams (set)Il corpo della richiesta.
note

Gli header vanno modificati con .set() / .append() — l'assegnazione per indice (es. headers["X-Key"] = v) viene ignorata.

Puoi anche costruire tu una richiesta:

const request = new Request({
scheme: 'https',
host: 'example.com',
port: 8080,
path: '/api',
method: 'GET',
queries: 'param1=value1&param2=value2',
headers: [
['Content-Type', 'application/json'],
['Authorization', 'Bearer token']
],
textBody: '{"key": "value"}'
});
console.log(request.encode());

Response​

La classe Response rappresenta la risposta HTTP passata a onResponse / onSessionCompleted.

MembroTipoDescrizione
statusCodenumber (get / set)Il codice di stato della risposta.
statusPhrasestring (get / set)La frase di stato della risposta, es. OK.
headersHeaders (get)Gli header della risposta.
bodyBody (get) / string | Map | Array | URLSearchParams (set)Il corpo della risposta.
const response = new Response({
statusCode: 404,
statusPhrase: 'Not Found',
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'no-cache'
},
textBody: '{"error": "Resource not found"}'
});
console.log(response.encode());

Body​

La classe Body rappresenta il corpo di una richiesta o risposta HTTP. Assegnare un nuovo valore a request.body / response.body sostituisce l'intero corpo.

MetodoRestituisceDescrizione
parseText()string | nullAnalizza il corpo come testo.
parseJSON()object | nullAnalizza il corpo come JSON.
parseURLSearchParams()URLSearchParams | nullAnalizza il corpo come parametri URL-encoded.
const bodyInstance = new Body('{"user": "alice"}');
const json = bodyInstance.parseJSON();
if (json) {
console.log('User:' + json.user);
} else {
console.error('Failed to parse JSON');
}

Headers​

La classe Headers rappresenta gli header HTTP.

MetodoRestituisceDescrizione
append(name, value)voidAggiunge in coda un valore all'header specificato.
set(name, value)voidImposta (sostituisce) il valore dell'header specificato.
get(name)string | nullRestituisce il valore dell'header specificato.
has(name)booleanVerifica se l'header specificato esiste.
delete(name)voidElimina l'header specificato.
forEach(callback, thisArg?)voidChiama una funzione per ogni header.
entries() / keys() / values()IteratorItera su voci / chiavi / valori.
encode()ArrayCodifica gli header in un formato serializzabile.
const headers = new Headers();
headers.append('Content-Type', 'application/json');
headers.set('Content-Length', '1024');
console.log(headers.get('Content-Type')); // 'application/json'
console.log(headers.has('Authorization')); // false
headers.forEach((value, name) => {
console.log(name + ' ' + value);
});

URLSearchParams​

La classe URLSearchParams rappresenta i parametri della query URL (o del corpo urlencoded).

MetodoRestituisceDescrizione
append(name, value)voidAggiunge in coda un valore al parametro specificato.
set(name, value)voidImposta (sostituisce) il valore del parametro specificato.
get(name)string | nullRestituisce il valore del parametro specificato.
has(name)booleanVerifica se il parametro specificato esiste.
delete(name)voidElimina il parametro specificato.
forEach(callback, thisArg?)voidChiama una funzione per ogni parametro.
entries() / keys() / values()IteratorItera su voci / chiavi / valori.
sort()voidOrdina i parametri.
toString()stringSerializza in una stringa urlencoded.
const params = new URLSearchParams({ key1: 'value1', key2: 'value2' });
console.log(params.get('key1')); // 'value1'
console.log(params.get('key3')); // null
params.forEach((value, key) => console.log(key + ' ' + value));

SharedPreferences​

La classe SharedPreferences fornisce un archivio chiave-valore locale persistente che sopravvive alle esecuzioni degli script e ai riavvii dell'app (basato sui system user defaults).

MetodoRestituisceDescrizione
SharedPreferences.write(key, value)voidScrive un valore (stringa / numero / booleano / oggetto / array). Scrivere null elimina la chiave.
SharedPreferences.read(key)anyLegge il valore associato alla chiave, o null se non esiste.
SharedPreferences.write("test_key", "test_value");
const value = SharedPreferences.read("test_key");
console.log(value);

SharedPreferences.write("cfg", {a: 1}); // objects are stored directly
SharedPreferences.write("cfg", null); // deletes "cfg"

sdk — Script di Quick Request​

sdk (alias pm) viene iniettato solo negli script pre/post di Quick Request. Fa da ponte verso l'archivio variabili dell'app (ambienti, variabili globali e di runtime) e raccoglie le asserzioni, con una forma API in stile Postman.

MembroDescrizione
sdk.env.get(key)Legge una variabile d'ambiente definita nell'app.
sdk.env.set(key, value)Imposta una variabile d'ambiente (come sdk.setEnvVar).
sdk.setEnvVar(key, value)Scrive una variabile d'ambiente — raccolta e persistita nell'app.
sdk.setVar(key, value)Scrive una variabile runtime (locale).
sdk.setGlobalVar(key, value)Scrive una variabile globale.
sdk.getVar(key)Legge una variabile runtime.
sdk.test(name, fn)Esegue un blocco di asserzioni nominato; i fallimenti vengono raccolti e riportati nell'app.
sdk.expect(value)Primitive di asserzione: toBe, toEqual, toBeTruthy.
sdk.jsonPath(object, path)Ricerca a percorso puntato, es. "$.data.list[0].id".
sdk.utils.uuid()Come crypto.randomUUID().
sdk.utils.base64Encode(s) / base64Decode(s)Come btoa / atob.
sdk.utils.md5(s)Come $hash.md5.
// Quick Request pre-request script: sign the request
async function onRequest(context, url, request) {
// read variables defined in the app's environment
const secret = sdk.env.get("secret") || "test-key";
sdk.expect(secret).toBeTruthy();

const ts = String(Date.now());
const bodyText = request.body && request.body.text ? request.body.text : '';
const sig = $hmac.sha256(ts + bodyText, secret);

// headers must be set via .set / .append
request.headers.set("X-Signature", sig);
request.headers.set("X-Timestamp", ts);

// persist variables back to the app
sdk.setEnvVar("lastTs", ts);
sdk.test("signature is 64 hex", () => {
sdk.expect(sig.length).toBe(64);
});

console.log("signed request for", url);
return request;
}
note

I risultati delle asserzioni vengono riportati per gli script pre-request. Negli script post-response le asserzioni vengono eseguite ma i risultati non vengono raccolti.

Contesti​

RewriteContext​

L'oggetto contesto passato agli script di riscrittura (onRequest / onResponse).

MembroTipoDescrizione
isEnableOnRequestboolean (get)Se l'ingresso onRequest è abilitato.
isEnableOnResponseboolean (get)Se l'ingresso onResponse è abilitato.
parametersobject (get / set)Un dizionario di parametri condiviso tra onRequest e onResponse.
scriptNamestring (get)Il nome dello script.

CompletedContext​

L'oggetto contesto passato agli script HTTP completati.

MembroTipoDescrizione
sessionobject (get)L'oggetto sessione associato allo script completato.
scriptNamestring (get)Il nome dello script completato.

ScheduleContext​

L'oggetto contesto passato agli script pianificati.

MembroTipoDescrizione
parametersobject (get / set)Parametri passati al prossimo runloop quando impostati.
cronstring (get)L'espressione cron dello schedule.
repeatedCountnumber (get)Quante volte lo script è stato ripetuto.
scriptNamestring (get)Il nome dello script pianificato.

Note sul comportamento​

  • Le eccezioni non catturate fanno fallire lo script. Gli errori (incluso AbortError da abort()) propagano a Hodor e l'esecuzione viene riportata come fallita — le riscritture parziali fatte prima dell'errore vengono scartate, quindi proteggi i blocchi rischiosi con try / catch.
  • Custode del timeout. Ogni esecuzione di script ha un budget di tempo; uno script che non termina mai (es. un loop infinito o un await bloccato) viene interrotto forzatamente e riportato come timeout.
  • Errori come valori di ritorno. Alcune API non lanciano mai: $codec.base64Decode restituisce "", $crypto restituisce stringhe "Error: ...", $fs.read restituisce stringhe "Error: ..." e $fs.info restituisce undefined. Controlla questi valori di ritorno invece di affidarti a try / catch.
  • console.log vs $log. Entrambi sono visibili nella vista log degli script; $log aggiunge timestamp e livelli.
  • Persistenza del runtime degli script. Le variabili scritte con sdk.setVar e i file scritti con $fs restano disponibili alle esecuzioni successive dello stesso script; SharedPreferences persiste attraverso i riavvii dell'app.