Überblick
Wenn du JavaScript-Code für Integrationen, Actions, Trigger oder Workflow-Code-Nodes schreibst, hast du Zugriff auf eine Reihe von integrierten Utility-Funktionen. Diese Funktionen laufen in einer sicheren, isolierten JavaScript-Ausführungsumgebung, die wesentliche Funktionen bereitstellt, ohne externe Bibliotheken zu benötigen.Diese Utilities sind nur in JavaScript-Code verfügbar. Python-Code-Nodes nutzen
eine eigene Laufzeitumgebung und unterstützen keine
ld.*-Funktionen. Das
Python-Verhalten findest du auf der Code-Node-Seite.Was ist die Sandbox?
Die Sandbox ist eine sichere, isolierte JavaScript-Ausführungsumgebung, die:- Nicht vertrauenswürdigen Code sicher ausführt - Speicherbegrenzte und zeitgesteuerte Ausführung
- Wesentliche Utilities bereitstellt - HTTP-Anfragen, Datenkonvertierungen, Kryptographie
- Sicherheitsrisiken verhindert - Kein Dateisystemzugriff, keine gefährlichen Globals wie
evaloderprocess - Keine Abhängigkeiten erfordert - Keine npm-Pakete oder externe Imports erforderlich
Wo diese Utilities verfügbar sind
Die Sandbox-Utilities sind verfügbar in:- Benutzerdefinierten Integrations-Actions - Code, der mit externen APIs interagiert
- Benutzerdefinierten Integrations-Triggern - Code, der auf Events überwacht
- Authentifizierungsflows - OAuth- und API-Key-Validierungscode
- Workflow-Code-Nodes - Benutzerdefiniertes JavaScript in Workflow-Automatisierungen. Für Python siehe die Code-Node-Seite.
HTTP & Networking
ld.request()
Führe HTTP-Anfragen an externe APIs mit automatischer JSON-Verarbeitung und Fehler-Management aus. Parameter:Standardmäßig entfernt
ld.request() den Authorization-Header und andere Credential-Header, wenn eine Anfrage auf eine andere Origin weitergeleitet wird. Setze preserveAuthOnRedirect: true, um sie bei Cross-Origin-Redirects zu behalten. Aktiviere das nur für APIs, bei denen du dem Redirect-Ziel vertraust.responseType: "stream" oder "binary"):
Die Response-Struktur hängt vom
responseType ab. Standardmäßig erhältst du json- und text-Eigenschaften. Bei responseType: "stream" oder "binary" erhältst du stattdessen eine buffer-Eigenschaft — json und text sind in diesem Modus nicht verfügbar.Anfragen an private und interne Netzwerkadressen werden standardmäßig blockiert. Auf dedizierten Deployments, die interne Endpunkte erreichen müssen, können Operatoren diese Prüfung über die Umgebungsvariable
URL_VALIDATION_ENABLED=false deaktivieren. Das gilt auch für HTTP-Request-Nodes in Workflows.ld.awsRequest()
Führe AWS SigV4-signierte Anfragen an AWS-Services wie S3, API Gateway oder benutzerdefinierte AWS-APIs aus. Parameter:Datenformat-Konvertierungen
ld.csv2parquet()
Konvertiere CSV-Text in das Parquet-Format mit optionaler Komprimierung und Array-Unterstützung. Parameter:{ base64: string, success: boolean }
Beispiel:
CSV-Spalten, die Array-ähnliche Strings enthalten (z.B.
"[Python,JavaScript]"), werden automatisch erkannt und in Parquet-List-Spalten konvertiert.ld.parquet2csv()
Konvertiere das Parquet-Format in CSV-Text, wobei List-Spalten entsprechend behandelt werden. Parameter:{ base64: string, success: boolean }
Beispiel:
ld.arrow2parquet()
Konvertiere das Arrow-IPC-Stream-Format in Parquet. Parameter:ld.json2csv()
Konvertiere JSON-Daten in das CSV-Format mithilfe der nodejs-polars-Bibliothek. Parameter:Datenbank & SQL
ld.validateSqlQuery()
Validiere die SQL-Abfrage-Syntax, um sicherzustellen, dass sie nicht leer ist und eine einzelne Anweisung enthält. Parameter:ld.ensureReadOnlySqlQuery()
Stelle sicher, dass eine SQL-Abfrage schreibgeschützt ist, indem du ihren Ausführungstyp überprüfst. Parameter:Kryptographie
ld.signWithRS256()
Erstelle RSA-SHA256-digitale Signaturen, die häufig für JWT-Signierung und OAuth-Flows verwendet werden. Funktionssignatur:data(string): Zu signierende DatenprivateKey(string): PEM-formatierter RSA Private Keyoptions(object, optional):encoding(string): Output-Encoding -'base64'(Standard) oder'hex'
{ signature: string } — Objekt mit der Signatur im angegebenen Encoding
Beispiel: JWT-Signierung
Utility-Funktionen
ld.log()
Gib Debugging-Informationen in die Ausführungslogs aus, die unterhalb des “Test Action”-Buttons sichtbar sind. Parameter:ld.wait()
Pausiere die Ausführung für eine bestimmte Anzahl von Millisekunden. Nützlich für Rate Limiting oder Retry-Logik. Parameter:atob() / btoa()
Base64-Encoding- und -Decoding-Funktionen, global ohne Imports verfügbar. atob() - Dekodiere Base64-String zu binärem String btoa() - Kodiere binären String zu Base64 Beispiel: Base64-URL-DekodierungBuffer.from()
Ein minimaler Polyfill zur Konvertierung zwischen typisierten Array-Formaten. Akzeptiert ein einzelnes Argument (Array, Uint8Array oder ArrayBuffer) und gibt einUint8Array zurück.
Beispiel: ArrayBuffer von ld.request() konvertieren
FormData
Erstelle Multipart-Form-Daten für Datei-Uploads und komplexe Request-Bodies. Beispiel: Datei-Upload mit MetadatenStandard-JavaScript-APIs
Die Sandbox bietet auch Zugriff auf Standard-JavaScript-Built-ins: JSONJSON.stringify()- Konvertiere Objekte zu JSON-StringsJSON.parse()- Parse JSON-Strings zu Objekten
new Date()- Erstelle Date-ObjekteDate.now()- Erhalte aktuellen Timestamp- Alle Standard-Date-Methoden
Math.floor(),Math.ceil(),Math.round()Math.random(),Math.max(),Math.min()- Alle Standard-Math-Methoden
new RegExp()- Erstelle reguläre Ausdrücke- String-Regex-Methoden:
match(),replace(),test()
- Alle Standard-Array-Methoden:
map(),filter(),reduce(), etc. - Alle Standard-Object-Methoden:
keys(),values(),entries(), etc.
Best Practices
Fehlerbehandlung
Wickle API-Aufrufe immer in Try-Catch-Blöcke ein und gib hilfreiche Fehlermeldungen:Input-Validierung
Validiere User-Inputs, bevor du sie verwendest:Performance-Tipps
Minimiere API-AufrufeSicherheitsüberlegungen
Niemals Secrets hartcodierenHäufige Fallstricke
1. Async/Await nicht richtig behandelnNächste Schritte
- Benutzerdefinierte Integrationen erstellen - Erstelle deine erste Integration
- Dateiunterstützung für Actions - Behandle Datei-Inputs und -Outputs
- Integrations-Agent - Erhalte Hilfe beim Schreiben von Integrationscode
- Workflow-Code-Node - Schreibe eigenen Code in Workflows
FAQ
Wann sollte ich Sandbox-Utility-Funktionen nutzen?
Wann sollte ich Sandbox-Utility-Funktionen nutzen?
Nutze Sandbox-Utility-Funktionen, wenn du benutzerdefinierte Integrationen, Aktionen, Trigger oder Workflow-Code-Nodes baust, die häufig benötigte Hilfsfunktionen brauchen. Sie reduzieren Boilerplate und machen eigene Logik leichter wartbar.
Was sollte ich prüfen, wenn eine Utility-Funktion nicht verfügbar ist?
Was sollte ich prüfen, wenn eine Utility-Funktion nicht verfügbar ist?
Prüfe, ob du die Funktion in einem unterstützten Kontext verwendest, ob Funktionsname und Argumente korrekt sind und ob die Laufzeitumgebung das gewünschte Verhalten unterstützt.