Référence de l'API de scripts
Hodor exécute vos scripts dans un moteur JavaScript intégré. Selon le type de script, Hodor appelle l'une des fonctions d'entrée ci-dessous au bon moment — vous n'implémentez que la logique dont vous avez besoin. Si vous ne modifiez rien, supprimez la fonction d'entrée inutilisée pour éviter des appels inutiles.
Objets et classes globaux disponibles :
| Catégorie | Noms |
|---|---|
| Fonctions d'entrée | onRequest, onResponse, onSessionCompleted, onSchedule, abort() |
Modules natifs $ | $codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log |
| API standard du Web | fetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console |
| Classes HTTP | Request, Response, Body, Headers, URLSearchParams |
| Stockage | SharedPreferences, variables sdk |
| Contextes | RewriteContext, CompletedContext, ScheduleContext |
Utilisez console.log(...) n'importe où dans un script pour inspecter des valeurs — la sortie apparaît dans la vue de logs du script.
Fonctions d'entrée
Les scripts sont détectés en scannant les déclarations async function — le nombre de paramètres de chaque fonction d'entrée est fixe (onRequest/onResponse en prennent 3, onSessionCompleted en prend 4, onSchedule en prend 1). Les affectations de fonctions fléchées (let onRequest = async (...) => {}) ne sont pas détectées. Les noms de paramètres sont libres.
onRequest(context, url, request)
Conçue pour les scripts de réécriture et les scripts de pré-requête Quick Request. Cette fonction est appelée avant que la requête HTTP soit envoyée au serveur. Retournez la request (éventuellement modifiée).
| Paramètre | Type | Description |
|---|---|---|
context | RewriteContext | L'objet de contexte. |
url | string | L'URL de la requête HTTP. |
request | Request | L'objet de requête 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)
Conçue pour les scripts de réécriture et les scripts de post-réponse Quick Request. Cette fonction est appelée avant que la réponse HTTP soit renvoyée au client. Retournez la response (éventuellement modifiée).
| Paramètre | Type | Description |
|---|---|---|
context | RewriteContext | L'objet de contexte. |
url | string | L'URL de la réponse HTTP. |
response | Response | L'objet de réponse 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)
Conçue pour le script HTTP Completed. Appelée de façon asynchrone après le retour de la réponse HTTP, sans affecter la transmission des données entre l'app et le serveur. Utile pour la collecte et le transfert de données.
| Paramètre | Type | Description |
|---|---|---|
context | CompletedContext | L'objet de contexte. |
url | string | L'URL de la requête HTTP. |
request | Request | L'objet de requête HTTP. |
response | Response | L'objet de réponse 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)
Conçue pour le script planifié (Schedule Script). Appelée à l'heure de déclenchement planifiée (les expressions cron à 5 ou 6 champs sont prises en charge). Utilisez abort() pour arrêter la boucle planifiée.
| Paramètre | Type | Description |
|---|---|---|
context | ScheduleContext | L'objet de contexte. |
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()
Dans les scripts de canal (onRequest / onResponse / onSchedule), appelez abort() pour arrêter le script et interrompre immédiatement l'exécution en cours — il lève une AbortError que Hodor vous signale.
// ✅ correct — abort() is injected into the script scope
async function onRequest(context, url, request) {
if (url.includes("/tracking")) abort();
return request;
}
Ne déclarez surtout pas onRequest(context, url, request, aborter) avec un 4e paramètre. Le nombre de paramètres des fonctions d'entrée est fixe — un 4e paramètre rend le point d'entrée indétectable.
Modules natifs
Tous les modules préfixés $ sont injectés à l'activation du runtime. Ils sont implémentés nativement, retournent de façon synchrone (sauf mention contraire) et traitent les entrées chaîne comme de l'UTF-8.
$codec — Encodage & décodage
Base64 / Hex / percent-encoding d'URL pour la conversion de protocole et le transfert de données.
| Méthode | Retour |
|---|---|
$codec.base64Encode(str) | Chaîne Base64. |
$codec.base64Decode(str) | Chaîne décodée ; une entrée invalide renvoie "" (sans lever d'exception). |
$codec.hexEncode(str) | Chaîne hex minuscule. |
$codec.hexDecode(str) | Chaîne décodée ; les caractères invalides sont ignorés. |
$codec.urlEncode(str) | Chaîne encodée en pourcentage. |
$codec.urlDecode(str) | Chaîne décodée ; les séquences invalides sont renvoyées telles quelles. |
$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 — Hachage
Calcul d'empreintes pour les contrôles d'intégrité, l'adressage de contenu et l'anonymisation. Retourne de l'hex minuscule.
| Méthode | Longueur de sortie |
|---|---|
$hash.md5(str) | 32 caractères hex |
$hash.sha1(str) | 40 caractères hex |
$hash.sha256(str) | 64 caractères hex |
$hash.sha384(str) | 96 caractères hex |
$hash.sha512(str) | 128 caractères hex |
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
// integrity check
const checksum = $hash.sha256(JSON.stringify({user: "admin"}));
$hmac — Code d'authentification de message
Hachage avec clé pour la signature d'API et la détection de falsification. (data, key) sont tous deux encodés en UTF-8 ; retourne de l'hex minuscule.
| Méthode | Algorithme |
|---|---|
$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 — Chiffrement symétrique
Chiffrement authentifié AES-GCM (recommandé) et DES (compatibilité historique).
| Méthode | Retour |
|---|---|
$crypto.encryptAES(plaintext, password, options?) | Ciphertext Base64 ; les échecs renvoient une chaîne "Error: <reason>". |
$crypto.decryptAES(ciphertext, password, options?) | Plaintext ; un ciphertext invalide renvoie "Error: Invalid ciphertext". |
$crypto.encryptDES(plaintext, key) | DES-ECB + PKCS7, clé tronquée à 8 octets → Base64. |
$crypto.decryptDES(ciphertext, key) | Plaintext ; une entrée non-Base64 renvoie "". |
options : { keySize: 128 \| 192 \| 256 } (défaut 256). Le format du ciphertext AES est base64(nonce[12] + ciphertext + tag[16]) — à apparier avec decryptAES ; pour interopérer avec d'autres langages, vous devez déballer vous-même ce format.
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
Création, analyse et vérification de signature JWT (famille HMAC) pour les scripts de flux d'authentification.
| Méthode | Retour |
|---|---|
$jwt.sign(payload, secret, algorithm?) | Chaîne JWT ; défaut HS256. |
$jwt.decode(token) | Objet {header, payload} (la signature n'est pas vérifiée) ; renvoie null pour un token malformé. |
$jwt.verify(token, secret, algorithm?) | boolean — résultat de la vérification de signature. |
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 — Formatage de données
Pretty-print et minification JSON/XML pour la journalisation et le débogage. Les clés JSON sont triées alphabétiquement dans la sortie.
| Méthode | Retour |
|---|---|
$format.json(str, indent?) | JSON pretty-printé ; indent borné à 1–8 (défaut 2) ; une entrée invalide renvoie "Error: Invalid JSON". |
$format.minify(str) | JSON minifié (clés triées, sans espaces) ; une entrée invalide renvoie "Error: Invalid JSON". |
$format.xml(str) | XML simplement indenté. |
$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 — Système de fichiers
Lecture/écriture de fichiers légère dans les scripts (config, cache, export). Les chemins prennent en charge l'expansion ~ ; write crée automatiquement les répertoires parents manquants.
| Méthode | Retour |
|---|---|
$fs.read(path) | Contenu UTF-8 ; un échec renvoie "Error: Cannot read file at <path>". |
$fs.readBinary(path) | Octets en Base64 ; un échec renvoie "". |
$fs.write(path, content) | boolean — succès. |
$fs.exists(path) | boolean. |
$fs.delete(path) | boolean ; les fichiers absents renvoient false. |
$fs.list(path) | string[] des entrées du répertoire ; un échec renvoie []. |
$fs.info(path) | Chaîne JSON {size, modified, isDirectory, path} ; les chemins absents renvoient 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
Les formes d'échec diffèrent selon la méthode : read renvoie une chaîne "Error: ...", readBinary renvoie "", list renvoie [] et info renvoie undefined — gérez chaque cas en conséquence.
$env — Variables d'environnement
Variables d'environnement du processus et chemins système. Note : $env est l'environnement du processus (partagé entre les exécutions, vit avec le processus). Pour persister des variables côté utilisateur, utilisez plutôt sdk.setEnvVar ou SharedPreferences.
| Méthode | Retour |
|---|---|
$env.get(key) | Valeur ; les clés absentes renvoient "". |
$env.set(key, value) | boolean — résultat du setenv. |
$env.all() | Chaîne JSON de toutes les variables d'environnement. |
$env.cwd() | Répertoire de travail courant. |
$env.tmpDir() | Répertoire temporaire. |
$env.homeDir() | Répertoire home de l'utilisateur. |
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());
$uuid — UUID
Générer et valider des UUID (ID de requête, clés d'idempotence).
| Méthode | Retour |
|---|---|
$uuid.v4() | UUID v4 standard (majuscule, avec tirets), ex. "550e8400-E29B-41D4-A716-446655440000". |
$uuid.compact() | Forme sans tirets, en minuscules. |
$uuid.validate(str) | Indique si la chaîne est un UUID valide. |
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
validate n'accepte que le format avec tirets — validate($uuid.compact()) renvoie false. Réinsérez les tirets avant de valider une chaîne compacte.
$log — Journalisation structurée
Lignes de log horodatées et nivelées, routées via le système console du moteur (collectées dans la vue de logs du script).
| Méthode | Retour |
|---|---|
$log.log(level, message, tag?) | Ligne de log formatée (aussi imprimée). |
$log.debug / info / warn / error(message) | Méthodes de niveau pratiques, sortie uniquement. |
Format de ligne de log : [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (le segment [tag] est omis quand aucun tag n'est fourni).
$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
Envoie de vraies requêtes HTTP depuis les scripts — le canal principal des workflows façon Postman.
fetch(url: string, options?: object) → Promise<response>
options :
| Champ | Type | Défaut | Description |
|---|---|---|---|
method | string | "GET" | Insensible à la casse ; les valeurs inconnues retombent sur GET. |
timeoutInterval | number | 30 | Secondes. |
headers | [[k, v]] ou [{k: v}] | [] | Les deux formes sont acceptées. |
textBody | string | — | Texte du body de requête. |
encoding | string | — | "hex" signifie que textBody est une chaîne hex. |
La valeur résolue est un objet simple : statusCode (number), headers (tableau d'objets à clé unique, clés dupliquées préservées) et textBody() — une fonction qui renvoie {text, encoding} avec détection automatique du jeu de caractères (les corps indécodables retombent sur {text: <hex>, encoding: "hex"}). La valeur de rejet est une chaîne de message d'erreur.
// 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 envoie des requêtes HTTP depuis n'importe quel script (implémentée au-dessus de fetch). Toutes les méthodes sont async et renvoient un objet de réponse avec statusCode, headers et textBody().
| Méthode | Description |
|---|---|
HTTPClient.get(url, params?) | Envoie une requête GET. |
HTTPClient.post(url, params?) | Envoie une requête POST. |
HTTPClient.put(url, params?) | Envoie une requête PUT. |
HTTPClient.update(url, params?) | Envoie une requête UPDATE. |
HTTPClient.delete(url, params?) | Envoie une requête DELETE. |
HTTPClient.request(url, method, params?) | Envoie une requête avec une méthode personnalisée. |
params est un objet optionnel avec :
headers: objet de headers de requête, ex.{"key1": "value1"}body: corps de la requête — une chaîne, un objet JSON (sérialisé automatiquement) ou un URLSearchParamstimeoutInterval: délai d'attente en secondes (défaut 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);
}
Minuteries (Timers)
setTimeout / setInterval / clearTimeout / clearInterval fonctionnent comme dans les navigateurs. Les callbacks sont dispatchés sur une file série du moteur, donc les timers se déclenchent de façon fiable quel que soit le thread hôte.
| Fonction | Retour |
|---|---|
setTimeout(callback, ms) | Id de timer (string), se déclenche une fois. |
setInterval(callback, ms) | Id de timer, se déclenche en boucle. |
clearTimeout(id) / clearInterval(id) | Annule (idempotent, les ids inconnus sont ignorés). |
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);
Fonctions globales
| Nom | Signature | Description |
|---|---|---|
btoa(str) | (string) → string | Encodage Base64 — sémantique symétrique UTF-8 (les chaînes non Latin-1 sont autorisées, contrairement aux navigateurs). |
atob(str) | (string) → string | Décodage Base64 ; une entrée invalide renvoie "". |
performance.now() | () → number | Millisecondes depuis l'epoch (pas le chargement de page). |
sleep(ms) | (number) → Promise | Se résout après ms ; utilisez await sleep(1000). |
require(id) | (string) → any | Charge une bibliothèque de scripts selon la sémantique CommonJS (module.exports) ; la clé est @libs/<key>, résolue comme identifiant de bibliothèque → nom de bibliothèque (unique) → bibliothèques intégrées ; lève une exception si introuvable. |
TextEncoder | new TextEncoder().encode(str) | Encode en UTF-8 dans un Uint8Array (encoding vaut toujours "utf-8"). |
crypto.getRandomValues(n) | (Array) → number[] | Remplit avec n valeurs UInt32 aléatoires. |
crypto.randomUUID() | () → string | UUID aléatoire (majuscule, avec tirets). |
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]
Les bibliothèques sont gérées dans le gestionnaire de modules de scripts. La clé de require est toujours @libs/<key> : vos bibliothèques de scripts se résolvent d'abord par identifiant (stable lors des renommages), puis par nom (correspondance unique), puis par les bibliothèques intégrées @libs/base64 / @libs/hex. Les bibliothèques exportent via module.exports, peuvent require d'autres bibliothèques, et une clé manquante lève une exception (un échec en pré-envoi interrompt la requête, un échec en post-réponse conserve la réponse d'origine). Voir scripts Quick Request, Require de bibliothèques de scripts pour le guide complet.
console
console.log / info / warn / error imprime des valeurs dans la vue de logs du script. Les arguments multiples sont sérialisés, donc vous pouvez logger directement objets et tableaux :
console.log("headers", {Accept: "application/json"}, [1, 2, 3]);
$log offre une sortie structurée et nivelée (voir $log) — les deux canaux sont visibles dans la vue de logs de script de Hodor.
Classes HTTP
Request
La classe Request est la requête HTTP empaquetée passée à onRequest / onSessionCompleted.
| Membre | Type | Description |
|---|---|---|
scheme | string (get / set) | Le scheme de la requête, ex. https. |
host | string (get / set) | Le host de la requête. |
port | number (get / set) | Le port de la requête. |
path | string (get / set) | Le path de la requête. |
method | string (get / set) | La méthode HTTP, ex. GET. |
queries | URLSearchParams (get) | Les query params de la requête. |
headers | Headers (get) | Les headers de la requête. |
body | Body (get) / string | Map | Array | URLSearchParams (set) | Le body de la requête. |
Les headers doivent être modifiés avec .set() / .append() — l'affectation par index (ex. headers["X-Key"] = v) est ignorée.
Vous pouvez aussi construire une requête vous-même :
const request = new Request({
scheme: 'https',
host: 'example.com',
port: 8080,
path: '/api',
method: 'GET',
queries: 'param1=value1¶m2=value2',
headers: [
['Content-Type', 'application/json'],
['Authorization', 'Bearer token']
],
textBody: '{"key": "value"}'
});
console.log(request.encode());
Response
La classe Response représente la réponse HTTP passée à onResponse / onSessionCompleted.
| Membre | Type | Description |
|---|---|---|
statusCode | number (get / set) | Le code de statut de la réponse. |
statusPhrase | string (get / set) | La phrase de statut de la réponse, ex. OK. |
headers | Headers (get) | Les headers de la réponse. |
body | Body (get) / string | Map | Array | URLSearchParams (set) | Le body de la réponse. |
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 représente le corps d'une requête ou d'une réponse HTTP. Affecter une nouvelle valeur à request.body / response.body remplace tout le corps.
| Méthode | Retour | Description |
|---|---|---|
parseText() | string | null | Analyse le corps comme texte. |
parseJSON() | object | null | Analyse le corps comme JSON. |
parseURLSearchParams() | URLSearchParams | null | Analyse le corps comme paramètres URL-encodés. |
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 représente des headers HTTP.
| Méthode | Retour | Description |
|---|---|---|
append(name, value) | void | Ajoute une valeur au header spécifié. |
set(name, value) | void | Définit (remplace) la valeur du header spécifié. |
get(name) | string | null | Obtient la valeur du header spécifié. |
has(name) | boolean | Vérifie si le header spécifié existe. |
delete(name) | void | Supprime le header spécifié. |
forEach(callback, thisArg?) | void | Appelle une fonction pour chaque header. |
entries() / keys() / values() | Iterator | Itère sur les entrées / clés / valeurs. |
encode() | Array | Encode les headers dans un format sérialisable. |
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 représente les paramètres de query d'URL (ou de body urlencoded).
| Méthode | Retour | Description |
|---|---|---|
append(name, value) | void | Ajoute une valeur au paramètre spécifié. |
set(name, value) | void | Définit (remplace) la valeur du paramètre spécifié. |
get(name) | string | null | Obtient la valeur du paramètre spécifié. |
has(name) | boolean | Vérifie si le paramètre spécifié existe. |
delete(name) | void | Supprime le paramètre spécifié. |
forEach(callback, thisArg?) | void | Appelle une fonction pour chaque paramètre. |
entries() / keys() / values() | Iterator | Itère sur les entrées / clés / valeurs. |
sort() | void | Trie les paramètres. |
toString() | string | Sérialise en chaîne urlencodée. |
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 fournit un stockage clé-valeur local persistant qui survit aux exécutions de scripts et aux redémarrages de l'app (adossé aux user defaults du système).
| Méthode | Retour | Description |
|---|---|---|
SharedPreferences.write(key, value) | void | Écrit une valeur (string / number / boolean / object / array). Écrire null supprime la clé. |
SharedPreferences.read(key) | any | Lit la valeur associée à la clé, ou null si elle n'existe pas. |
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 — Scripts Quick Request
sdk (alias pm) est injecté uniquement dans les scripts pre/post Quick Request. Il fait le pont avec le stockage de variables de l'app (environnements, variables globales et d'exécution) et collecte les assertions, avec une forme d'API façon Postman.
| Membre | Description |
|---|---|
sdk.env.get(key) | Lit une variable d'environnement définie dans l'app. |
sdk.env.set(key, value) | Définit une variable d'environnement (identique à sdk.setEnvVar). |
sdk.setEnvVar(key, value) | Écrit une variable d'env — collectée et persistée vers l'app. |
sdk.setVar(key, value) | Écrit une variable d'exécution (locale). |
sdk.setGlobalVar(key, value) | Écrit une variable globale. |
sdk.getVar(key) | Lit une variable d'exécution. |
sdk.test(name, fn) | Exécute un bloc d'assertion nommé ; les échecs sont collectés et signalés dans l'app. |
sdk.expect(value) | Primitives d'assertion : toBe, toEqual, toBeTruthy. |
sdk.jsonPath(object, path) | Recherche par chemin pointé, ex. "$.data.list[0].id". |
sdk.utils.uuid() | Identique à crypto.randomUUID(). |
sdk.utils.base64Encode(s) / base64Decode(s) | Identique à btoa / atob. |
sdk.utils.md5(s) | Identique à $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;
}
Les résultats d'assertion sont signalés pour les scripts de pré-requête. Dans les scripts de post-réponse, les assertions s'exécutent mais les résultats ne sont pas collectés.
Contextes
RewriteContext
L'objet de contexte passé aux scripts de réécriture (onRequest / onResponse).
| Membre | Type | Description |
|---|---|---|
isEnableOnRequest | boolean (get) | Indique si le point d'entrée onRequest est activé. |
isEnableOnResponse | boolean (get) | Indique si le point d'entrée onResponse est activé. |
parameters | object (get / set) | Un dictionnaire de paramètres partagé entre onRequest et onResponse. |
scriptName | string (get) | Le nom du script. |
CompletedContext
L'objet de contexte passé aux scripts HTTP Completed.
| Membre | Type | Description |
|---|---|---|
session | object (get) | L'objet de session associé au script completed. |
scriptName | string (get) | Le nom du script completed. |
ScheduleContext
L'objet de contexte passé aux scripts planifiés.
| Membre | Type | Description |
|---|---|---|
parameters | object (get / set) | Paramètres passés à la prochaine boucle d'exécution quand définis. |
cron | string (get) | L'expression cron de la planification. |
repeatedCount | number (get) | Combien de fois le script a été répété. |
scriptName | string (get) | Le nom du script planifié. |
Notes de comportement
- Les exceptions non interceptées font échouer le script. Les erreurs (y compris
AbortErrordeabort()) remontent à Hodor et l'exécution est signalée comme échouée — les réécritures partielles faites avant l'erreur sont abandonnées, protégez donc les blocs risqués avectry / catch. - Chien de garde de délai d'attente. Chaque exécution de script a un budget de temps ; un script qui ne se termine jamais (ex. boucle infinie ou
awaitsuspendu) est interrompu de force et signalé comme timeout. - Erreurs comme valeurs de retour. Certaines API ne lèvent jamais d'exception :
$codec.base64Decoderenvoie"",$cryptorenvoie des chaînes"Error: ...",$fs.readrenvoie des chaînes"Error: ..."et$fs.inforenvoieundefined. Vérifiez ces valeurs de retour au lieu de compter surtry / catch. console.logvs$log. Les deux sont visibles dans la vue de logs de script ;$logajoute horodatages et niveaux.- Persistance du runtime de script. Les variables écrites avec
sdk.setVaret les fichiers écrits avec$fsrestent disponibles pour les exécutions suivantes du même script ;SharedPreferencespersiste à travers les redémarrages de l'app.