Script-API-Referenz
Hodor führt Ihre Skripte in einer eingebauten JavaScript-Engine aus. Je nach Skripttyp ruft Hodor eine der Einstiegsfunktionen unten zum richtigen Zeitpunkt auf — Sie implementieren nur die Logik, die Sie brauchen. Wenn Sie nichts verändern, löschen Sie die ungenutzte Einstiegsfunktion, um unnötige Aufrufe zu vermeiden.
Verfügbare globale Objekte und Klassen:
| Kategorie | Namen |
|---|---|
| Einstiegsfunktionen | onRequest, onResponse, onSessionCompleted, onSchedule, abort() |
Native $-Module | $codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log |
| Web-Standard-APIs | fetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console |
| HTTP-Klassen | Request, Response, Body, Headers, URLSearchParams |
| Speicher | SharedPreferences, sdk-Variablen |
| Kontexte | RewriteContext, CompletedContext, ScheduleContext |
Verwenden Sie console.log(...) an beliebiger Stelle im Skript, um Werte zu inspizieren — die Ausgabe erscheint in der Log-Ansicht des Skripts.
Einstiegsfunktionen
Skripte werden erkannt, indem nach async function-Deklarationen gesucht wird — die Parameterzahl jeder Einstiegsfunktion ist fix (onRequest/onResponse nehmen 3, onSessionCompleted nimmt 4, onSchedule nimmt 1). Arrow-Function-Zuweisungen (let onRequest = async (...) => {}) werden nicht erkannt. Parameternamen sind frei wählbar.
onRequest(context, url, request)
Gedacht für Umschreib-Skripte und Quick-Request-Pre-Send-Skripte. Diese Funktion wird aufgerufen, bevor die HTTP-Anfrage an den Server gesendet wird. Geben Sie den (ggf. veränderten) request zurück.
| Parameter | Typ | Beschreibung |
|---|---|---|
context | RewriteContext | Das Kontextobjekt. |
url | string | Die URL der HTTP-Anfrage. |
request | Request | Das HTTP-Anfrageobjekt. |
// 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)
Gedacht für Umschreib-Skripte und Quick-Request-Post-Response-Skripte. Diese Funktion wird aufgerufen, bevor die HTTP-Antwort an den Client ausgeliefert wird. Geben Sie die (ggf. veränderte) response zurück.
| Parameter | Typ | Beschreibung |
|---|---|---|
context | RewriteContext | Das Kontextobjekt. |
url | string | Die URL der HTTP-Antwort. |
response | Response | Das HTTP-Antwortobjekt. |
// 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)
Gedacht für HTTP-Completed-Skripte. Wird asynchron aufgerufen, nachdem die HTTP-Antwort zurückkam, ohne die Datenübertragung zwischen App und Server zu beeinflussen. Nützlich für Datensammlung und -weiterleitung.
| Parameter | Typ | Beschreibung |
|---|---|---|
context | CompletedContext | Das Kontextobjekt. |
url | string | Die URL der HTTP-Anfrage. |
request | Request | Das HTTP-Anfrageobjekt. |
response | Response | Das HTTP-Antwortobjekt. |
// 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)
Gedacht für Zeitplan-Skripte. Wird zum geplanten Auslösezeitpunkt aufgerufen (5- oder 6-teilige Cron-Ausdrücke werden unterstützt). Mit abort() beenden Sie die Zeitplan-Schleife.
| Parameter | Typ | Beschreibung |
|---|---|---|
context | ScheduleContext | Das Kontextobjekt. |
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()
Rufen Sie in Kanal-Skripten (onRequest / onResponse / onSchedule) abort() auf, um das Skript zu stoppen und die laufende Ausführung sofort abzubrechen — es wirft einen AbortError, den Hodor Ihnen meldet.
// ✅ correct — abort() is injected into the script scope
async function onRequest(context, url, request) {
if (url.includes("/tracking")) abort();
return request;
}
Deklarieren Sie onRequest(context, url, request, aborter) nicht mit einem 4. Parameter. Die Parameterzahl der Einstiegsfunktionen ist fix — ein 4. Parameter macht den Einstiegspunkt unerkennbar.
Native Module
Alle $-präfixierten Module werden bei Aktivierung der Laufzeit injiziert. Sie sind nativ implementiert, liefern synchron zurück (sofern nicht anders angegeben) und behandeln String-Eingaben als UTF-8.
$codec — Kodieren & Dekodieren
Base64 / Hex / URL-Percent-Encoding für Protokollkonvertierung und Datenübertragung.
| Methode | Rückgabe |
|---|---|
$codec.base64Encode(str) | Base64-String. |
$codec.base64Decode(str) | Dekodierter String; ungültige Eingabe liefert "" (wirft nicht). |
$codec.hexEncode(str) | Kleinbuchstaben-Hex-String. |
$codec.hexDecode(str) | Dekodierter String; ungültige Zeichen werden übersprungen. |
$codec.urlEncode(str) | Percent-kodierter String. |
$codec.urlDecode(str) | Dekodierter String; ungültige Sequenzen werden unverändert zurückgegeben. |
$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
Digest-Berechnung für Integritätsprüfungen, Content-Addressing und Anonymisierung. Liefert Kleinbuchstaben-Hex.
| Methode | Ausgabelänge |
|---|---|
$hash.md5(str) | 32 Hex-Zeichen |
$hash.sha1(str) | 40 Hex-Zeichen |
$hash.sha256(str) | 64 Hex-Zeichen |
$hash.sha384(str) | 96 Hex-Zeichen |
$hash.sha512(str) | 128 Hex-Zeichen |
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
// integrity check
const checksum = $hash.sha256(JSON.stringify({user: "admin"}));
$hmac — Message Authentication Code
Schlüsselbasiertes Hashing für API-Signaturen und Manipulationserkennung. Sowohl (data, key) werden UTF-8-kodiert; Rückgabe ist Kleinbuchstaben-Hex.
| Methode | Algorithmus |
|---|---|
$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 — Symmetrische Verschlüsselung
AES-GCM authentifizierte Verschlüsselung (empfohlen) und DES (Legacyleft-Kompatibilität).
| Methode | Rückgabe |
|---|---|
$crypto.encryptAES(plaintext, password, options?) | Base64-Ciphertext; Fehler liefern einen "Error: <reason>"-String. |
$crypto.decryptAES(ciphertext, password, options?) | Klartext; ungültiger Ciphertext liefert "Error: Invalid ciphertext". |
$crypto.encryptDES(plaintext, key) | DES-ECB + PKCS7, Schlüssel auf 8 Bytes gekürzt → Base64. |
$crypto.decryptDES(ciphertext, key) | Klartext; Nicht-Base64-Eingabe liefert "". |
options: { keySize: 128 \| 192 \| 256 } (Standard 256). Das AES-Ciphertext-Format ist base64(nonce[12] + ciphertext + tag[16]) — verwenden Sie es paarweise mit decryptAES; bei Interoperabilität mit anderen Sprachen müssen Sie dieses Format selbst entpacken.
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
JWT-Erzeugung, -Parsen und -Signaturprüfung (HMAC-Familie) für Authentifizierungsfluss-Skripte.
| Methode | Rückgabe |
|---|---|
$jwt.sign(payload, secret, algorithm?) | JWT-String; Standard HS256. |
$jwt.decode(token) | {header, payload}-Objekt (Signatur wird nicht geprüft); liefert null bei malformed Tokens. |
$jwt.verify(token, secret, algorithm?) | boolean — Ergebnis der Signaturprüfung. |
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 — Datenformatierung
JSON/XML-Pretty-Printing und Minifizierung für Logging und Debugging. JSON-Schlüssel werden in der Ausgabe alphabetisch sortiert.
| Methode | Rückgabe |
|---|---|
$format.json(str, indent?) | Hübsch formatiertes JSON; Einzug auf 1–8 begrenzt (Standard 2); ungültige Eingabe liefert "Error: Invalid JSON". |
$format.minify(str) | Minifiziertes JSON (sortierte Schlüssel, ohne Whitespace); ungültige Eingabe liefert "Error: Invalid JSON". |
$format.xml(str) | Einfach eingerücktes XML. |
$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 — Dateisystem
Leichtgewichtiges Datei-Lesen/-Schreiben in Skripten (Konfiguration, Cache, Export). Pfade unterstützen ~-Expansion; write legt fehlende übergeordnete Verzeichnisse automatisch an.
| Methode | Rückgabe |
|---|---|
$fs.read(path) | UTF-8-Inhalt; Fehler liefert "Error: Cannot read file at <path>". |
$fs.readBinary(path) | Bytes als Base64; Fehler liefert "". |
$fs.write(path, content) | boolean — Erfolg. |
$fs.exists(path) | boolean. |
$fs.delete(path) | boolean; fehlende Dateien liefern false. |
$fs.list(path) | string[] der Verzeichniseinträge; Fehler liefert []. |
$fs.info(path) | JSON-String {size, modified, isDirectory, path}; fehlende Pfade liefern 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
Die Fehlerformen unterscheiden sich je Methode: read liefert einen "Error: ..."-String, readBinary liefert "", list liefert [] und info liefert undefined — entsprechend behandeln.
$env — Umgebungsvariablen
Prozess-Umgebungsvariablen und Systempfade. Hinweis: $env ist die Prozessumgebung (über Ausführungen geteilt, lebt mit dem Prozess). Um nutzerseitige Variablen zu persistieren, verwenden Sie stattdessen sdk.setEnvVar oder SharedPreferences.
| Methode | Rückgabe |
|---|---|
$env.get(key) | Wert; fehlende Schlüssel liefern "". |
$env.set(key, value) | boolean — setenv-Ergebnis. |
$env.all() | JSON-String aller Umgebungsvariablen. |
$env.cwd() | Aktuelles Arbeitsverzeichnis. |
$env.tmpDir() | Temporäres Verzeichnis. |
$env.homeDir() | Benutzerverzeichnis. |
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());
$uuid — UUID
UUIDs erzeugen und prüfen (Request-IDs, Idempotenz-Schlüssel).
| Methode | Rückgabe |
|---|---|
$uuid.v4() | Standard-v4-UUID (Großbuchstaben, mit Bindestrichen), z. B. "550e8400-E29B-41D4-A716-446655440000". |
$uuid.compact() | Bindestrichfreie, kleingeschriebene Form. |
$uuid.validate(str) | Ob der String eine gültige UUID ist. |
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
validate akzeptiert nur das Bindestrich-Format — validate($uuid.compact()) liefert false. Fügen Sie vor dem Prüfen eines kompakten Strings die Bindestriche wieder ein.
$log — Strukturiertes Logging
Zeitgestempelte, stufenweise Logzeilen, geroutet über das Konsolensystem der Engine (in der Log-Ansicht des Skripts gesammelt).
| Methode | Rückgabe |
|---|---|
$log.log(level, message, tag?) | Formatierte Logzeile (wird auch ausgegeben). |
$log.debug / info / warn / error(message) | Komfort-Methoden je Stufe, nur Ausgabe. |
Logzeilenformat: [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (das Segment [tag] entfällt, wenn kein Tag angegeben ist).
$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
Web-APIs
fetch
Echte HTTP-Anfragen aus Skripten senden — der Hauptkanal für Postman-artige Workflows.
fetch(url: string, options?: object) → Promise<response>
options:
| Feld | Typ | Standard | Beschreibung |
|---|---|---|---|
method | string | "GET" | Groß-/Kleinschreibung egal; unbekannte Werte fallen auf GET zurück. |
timeoutInterval | number | 30 | Sekunden. |
headers | [[k, v]] oder [{k: v}] | [] | Beide Formen werden akzeptiert. |
textBody | string | — | Request-Body-Text. |
encoding | string | — | "hex" bedeutet, textBody ist ein Hex-String. |
Der aufgelöste Wert ist ein schlichtes Objekt: statusCode (number), headers (Array aus Objekten mit je einem Schlüssel, doppelte Schlüssel bleiben erhalten) und textBody() — eine Funktion, die {text, encoding} liefert, mit automatischer Zeichensatzerkennung (nicht dekodierbare Bodies fallen auf {text: <hex>, encoding: "hex"} zurück). Der Rejection-Wert ist ein Fehlermeldungs-String.
// 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
Die Klasse HTTPClient sendet HTTP-Anfragen aus jedem Skript (auf fetch implementiert). Alle Methoden sind async und liefern ein Response-Objekt mit statusCode, headers und textBody() zurück.
| Methode | Beschreibung |
|---|---|
HTTPClient.get(url, params?) | GET-Anfrage senden. |
HTTPClient.post(url, params?) | POST-Anfrage senden. |
HTTPClient.put(url, params?) | PUT-Anfrage senden. |
HTTPClient.update(url, params?) | UPDATE-Anfrage senden. |
HTTPClient.delete(url, params?) | DELETE-Anfrage senden. |
HTTPClient.request(url, method, params?) | Anfrage mit eigener Methode senden. |
params ist ein optionales Objekt mit:
headers: Request-Header-Objekt, z. B.{"key1": "value1"}body: Request-Body — ein String, JSON-Objekt (automatisch serialisiert) oder URLSearchParamstimeoutInterval: Timeout in Sekunden (Standard 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 funktionieren wie im Browser. Callbacks werden auf einer seriellen Engine-Queue ausgeliefert, sodass Timer unabhängig vom Host-Thread zuverlässig feuern.
| Funktion | Rückgabe |
|---|---|
setTimeout(callback, ms) | Timer-ID (string), feuert einmal. |
setInterval(callback, ms) | Timer-ID, feuert wiederholt. |
clearTimeout(id) / clearInterval(id) | Abbrechen (idempotent, unbekannte IDs werden ignoriert). |
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);
Globale Funktionen
| Name | Signatur | Beschreibung |
|---|---|---|
btoa(str) | (string) → string | Base64-Kodierung — UTF-8-symmetrische Semantik (nicht-Latin1-Strings sind erlaubt, anders als im Browser). |
atob(str) | (string) → string | Base64-Dekodierung; ungültige Eingabe liefert "". |
performance.now() | () → number | Millisekunden seit der Epoche (nicht seit Seitenladung). |
sleep(ms) | (number) → Promise | Resolve nach ms; verwenden Sie await sleep(1000). |
require(id) | (string) → any | Lädt eine Skriptbibliothek nach CommonJS-Semantik (module.exports); der Schlüssel ist @libs/<key>, aufgelöst als Skriptbibliotheks-Identifier → Skriptbibliotheks-Name (eindeutig) → eingebaute Bibliotheken; wirft, wenn nicht gefunden. |
TextEncoder | new TextEncoder().encode(str) | UTF-8-Kodierung in ein Uint8Array (encoding ist immer "utf-8"). |
crypto.getRandomValues(n) | (Array) → number[] | Füllt mit n zufälligen UInt32-Werten. |
crypto.randomUUID() | () → string | Zufällige UUID (Großbuchstaben, mit Bindestrichen). |
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]
Bibliotheken werden im Skriptmodul-Manager verwaltet. Der require-Schlüssel ist immer @libs/<key>: Ihre Skriptbibliotheken werden zuerst per Identifier aufgelöst (stabil über Umbenennungen), dann per Name (eindeutiger Treffer), dann die eingebauten Bibliotheken @libs/base64 / @libs/hex. Bibliotheken exportieren über module.exports, dürfen andere Bibliotheken laden, und ein fehlender Schlüssel wirft (Pre-Send-Fehler brechen die Anfrage ab, Post-Response-Fehler behalten die ursprüngliche Antwort). Die vollständige Anleitung: Quick-Request-Skripte, Require-Script-Libraries.
console
console.log / info / warn / error gibt Werte in der Log-Ansicht des Skripts aus. Mehrere Argumente werden serialisiert, sodass sich Objekte und Arrays direkt loggen lassen:
console.log("headers", {Accept: "application/json"}, [1, 2, 3]);
$log bietet strukturierte Ausgabe mit Stufen (siehe $log) — beide Kanäle sind in Hodor-Skript-Logansicht sichtbar.
HTTP-Klassen
Request
Die Klasse Request ist die verpackte HTTP-Anfrage, die an onRequest / onSessionCompleted übergeben wird.
| Member | Typ | Beschreibung |
|---|---|---|
scheme | string (get / set) | Das Scheme der Anfrage, z. B. https. |
host | string (get / set) | Der Host der Anfrage. |
port | number (get / set) | Der Port der Anfrage. |
path | string (get / set) | Der Pfad der Anfrage. |
method | string (get / set) | Die HTTP-Methode, z. B. GET. |
queries | URLSearchParams (get) | Die Query-Parameter der Anfrage. |
headers | Headers (get) | Die Header der Anfrage. |
body | Body (get) / string | Map | Array | URLSearchParams (set) | Der Body der Anfrage. |
Headers müssen per .set() / .append() geändert werden — Index-Zuweisung (z. B. headers["X-Key"] = v) wird ignoriert.
Sie können eine Anfrage auch selbst konstruieren:
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
Die Klasse Response repräsentiert die HTTP-Antwort, die an onResponse / onSessionCompleted übergeben wird.
| Member | Typ | Beschreibung |
|---|---|---|
statusCode | number (get / set) | Der Statuscode der Antwort. |
statusPhrase | string (get / set) | Die Status-Phrase der Antwort, z. B. OK. |
headers | Headers (get) | Die Header der Antwort. |
body | Body (get) / string | Map | Array | URLSearchParams (set) | Der Body der Antwort. |
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
Die Klasse Body repräsentiert den Body einer HTTP-Anfrage oder -Antwort. Eine neue Zuweisung an request.body / response.body ersetzt den gesamten Body.
| Methode | Rückgabe | Beschreibung |
|---|---|---|
parseText() | string | null | Body als Text parsen. |
parseJSON() | object | null | Body als JSON parsen. |
parseURLSearchParams() | URLSearchParams | null | Body als URL-kodierte Parameter parsen. |
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
Die Klasse Headers repräsentiert HTTP-Header.
| Methode | Rückgabe | Beschreibung |
|---|---|---|
append(name, value) | void | Einen Wert an den angegebenen Header anhängen. |
set(name, value) | void | Den Wert des angegebenen Headers setzen (ersetzen). |
get(name) | string | null | Den Wert des angegebenen Headers holen. |
has(name) | boolean | Prüfen, ob der angegebene Header existiert. |
delete(name) | void | Den angegebenen Header löschen. |
forEach(callback, thisArg?) | void | Für jeden Header eine Funktion aufrufen. |
entries() / keys() / values() | Iterator | Über Einträge / Schlüssel / Werte iterieren. |
encode() | Array | Die Header in ein serialisierbares Format kodieren. |
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
Die Klasse URLSearchParams repräsentiert URL-Query- (oder urlencoded-Body-)Parameter.
| Methode | Rückgabe | Beschreibung |
|---|---|---|
append(name, value) | void | Einen Wert an den angegebenen Parameter anhängen. |
set(name, value) | void | Den Wert des angegebenen Parameters setzen (ersetzen). |
get(name) | string | null | Den Wert des angegebenen Parameters holen. |
has(name) | boolean | Prüfen, ob der angegebene Parameter existiert. |
delete(name) | void | Den angegebenen Parameter löschen. |
forEach(callback, thisArg?) | void | Für jeden Parameter eine Funktion aufrufen. |
entries() / keys() / values() | Iterator | Über Einträge / Schlüssel / Werte iterieren. |
sort() | void | Die Parameter sortieren. |
toString() | string | Zu einem urlencoded-String serialisieren. |
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
Die Klasse SharedPreferences bietet lokalen persistenten Key-Value-Speicher, der Skriptläufe und App-Neustarts überdauert (unterstützt durch System-User-Defaults).
| Methode | Rückgabe | Beschreibung |
|---|---|---|
SharedPreferences.write(key, value) | void | Einen Wert schreiben (string / number / boolean / object / array). null schreiben löscht den Schlüssel. |
SharedPreferences.read(key) | any | Den mit dem Schlüssel verknüpften Wert lesen, oder null, wenn er nicht existiert. |
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 — Quick-Request-Skripte
sdk (Alias pm) wird nur in Quick-Request-Pre-/Post-Skripten injiziert. Es verbindet die Variablenspeicherung der App (Umgebungen, globale und Laufzeitvariablen) und sammelt Assertions — mit einer Postman-ähnlichen API-Form.
| Member | Beschreibung |
|---|---|
sdk.env.get(key) | Eine in der App definierte Umgebungsvariable lesen. |
sdk.env.set(key, value) | Eine Umgebungsvariable setzen (wie sdk.setEnvVar). |
sdk.setEnvVar(key, value) | Eine Umgebungsvariable schreiben — gesammelt und in die App zurückpersistiert. |
sdk.setVar(key, value) | Eine Laufzeit- (lokale) Variable schreiben. |
sdk.setGlobalVar(key, value) | Eine globale Variable schreiben. |
sdk.getVar(key) | Eine Laufzeitvariable lesen. |
sdk.test(name, fn) | Einen benannten Assertions-Block ausführen; Fehler werden gesammelt und in der App berichtet. |
sdk.expect(value) | Assertions-Primitiven: toBe, toEqual, toBeTruthy. |
sdk.jsonPath(object, path) | Dot-Pfad-Lookup, z. B. "$.data.list[0].id". |
sdk.utils.uuid() | Wie crypto.randomUUID(). |
sdk.utils.base64Encode(s) / base64Decode(s) | Wie btoa / atob. |
sdk.utils.md5(s) | Wie $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;
}
Assertion-Ergebnisse werden für Pre-Send-Skripte berichtet. In Post-Response-Skripten laufen Assertions, aber Ergebnisse werden nicht gesammelt.
Kontexte
RewriteContext
Das Kontextobjekt, das an Umschreib-Skripte (onRequest / onResponse) übergeben wird.
| Member | Typ | Beschreibung |
|---|---|---|
isEnableOnRequest | boolean (get) | Ob der onRequest-Einstieg aktiviert ist. |
isEnableOnResponse | boolean (get) | Ob der onResponse-Einstieg aktiviert ist. |
parameters | object (get / set) | Ein Parameter-Dictionary, das zwischen onRequest und onResponse geteilt wird. |
scriptName | string (get) | Der Name des Skripts. |
CompletedContext
Das Kontextobjekt, das an HTTP-Completed-Skripte übergeben wird.
| Member | Typ | Beschreibung |
|---|---|---|
session | object (get) | Das Sitzungsobjekt, das zum Completed-Skript gehört. |
scriptName | string (get) | Der Name des Completed-Skripts. |
ScheduleContext
Das Kontextobjekt, das an Zeitplan-Skripte übergeben wird.
| Member | Typ | Beschreibung |
|---|---|---|
parameters | object (get / set) | Parameter, die beim Setzen an den nächsten Runloop übergeben werden. |
cron | string (get) | Der Cron-Ausdruck des Zeitplans. |
repeatedCount | number (get) | Wie oft das Skript bereits wiederholt wurde. |
scriptName | string (get) | Der Name des Zeitplan-Skripts. |
Verhaltenshinweise
- Unbehandelte Exceptions lassen das Skript fehlschlagen. Fehler (einschließlich
AbortErrorvonabort()) reichen an Hodor weiter und die Ausführung wird als fehlgeschlagen berichtet — Teil-Umschreibungen vor dem Fehler werden verworfen, schützen Sie riskante Blöcke also mittry / catch. - Timeout-Wächter. Jeder Skriptlauf hat ein Zeitbudget; ein Skript, das nie fertig wird (z. B. Endlosschleife oder hängendes
await), wird zwangsweise unterbrochen und als Timeout berichtet. - Fehler als Rückgabewerte. Einige APIs werfen nie:
$codec.base64Decodeliefert"",$cryptoliefert"Error: ..."-Strings,$fs.readliefert"Error: ..."-Strings und$fs.infoliefertundefined. Prüfen Sie diese Rückgabewerte, statt sich auftry / catchzu verlassen. console.logvs.$log. Beide sind in der Skript-Logansicht sichtbar;$logergänzt Zeitstempel und Stufen.- Persistenz der Skriptlaufzeit. Mit
sdk.setVargeschriebene Variablen und mit$fsgeschriebene Dateien bleiben für spätere Ausführungen desselben Skripts verfügbar;SharedPreferencespersistiert über App-Neustarts.