Zum Hauptinhalt springen

Ü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 eval oder process
  • Keine Abhängigkeiten erfordert - Keine npm-Pakete oder externe Imports erforderlich
Benutzerdefinierter Integrationscode läuft in einer sicheren Sandbox-Umgebung. Du kannst keine externen Bibliotheken installieren oder importieren (npm, pip, etc.) - nur die hier dokumentierten integrierten JavaScript/Node.js-APIs sind verfügbar. Für erweiterte Verarbeitung (z.B. PDF-Parsing, Bildmanipulation) verwende externe APIs oder Services und rufe sie aus deinem Integrationscode auf.

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.
Rückgabewert (Standard):
Rückgabewert (mit 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.
Beispiel: GET-Anfrage
Beispiel: POST-Anfrage mit Body
Beispiel: Datei-Download
Beispiel: FormData-Upload
Der body-Parameter wird automatisch stringifiziert, wenn du ein Objekt übergibst. Für application/x-www-form-urlencoded Content-Type wird der Body automatisch in das entsprechende Format konvertiert.
Antwort-Bodys sind auf 100 MB begrenzt. Anfragen, die mehr Daten zurückgeben — einschließlich Chunked-Responses ohne Content-Length-Header und übergroßer Fehlerantworten — schlagen mit einem Response too large-Fehler fehl. Wenn du größere Dateien abrufen musst, streame sie in einen externen Speicher (zum Beispiel S3), anstatt sie über ld.request() zurückzugeben.
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:
Beispiel: S3-Datei-Upload

Datenformat-Konvertierungen

ld.csv2parquet()

Konvertiere CSV-Text in das Parquet-Format mit optionaler Komprimierung und Array-Unterstützung. Parameter:
Rückgabewert: { 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:
Rückgabewert: { base64: string, success: boolean } Beispiel:

ld.arrow2parquet()

Konvertiere das Arrow-IPC-Stream-Format in Parquet. Parameter:
Rückgabewert: Base64-kodierte Parquet-Datei Beispiel:

ld.json2csv()

Konvertiere JSON-Daten in das CSV-Format mithilfe der nodejs-polars-Bibliothek. Parameter:
Rückgabewert: CSV-Text Beispiel:

Datenbank & SQL

ld.validateSqlQuery()

Validiere die SQL-Abfrage-Syntax, um sicherzustellen, dass sie nicht leer ist und eine einzelne Anweisung enthält. Parameter:
Rückgabewert: Der bereinigte Abfrage-String wenn gültig, wirft sonst einen Fehler Beispiel:

ld.ensureReadOnlySqlQuery()

Stelle sicher, dass eine SQL-Abfrage schreibgeschützt ist, indem du ihren Ausführungstyp überprüfst. Parameter:
Rückgabewert: Der bereinigte Abfrage-String wenn schreibgeschützt, wirft sonst einen Fehler Beispiel:
Diese Funktion überprüft den Abfrage-Ausführungstyp, um sicherzustellen, dass er nur LISTING oder INFORMATION ist. Abfragen, die Daten ändern (INSERT, UPDATE, DELETE), werden abgelehnt.

Kryptographie

ld.signWithRS256()

Erstelle RSA-SHA256-digitale Signaturen, die häufig für JWT-Signierung und OAuth-Flows verwendet werden. Funktionssignatur:
Parameter:
  • data (string): Zu signierende Daten
  • privateKey (string): PEM-formatierter RSA Private Key
  • options (object, optional):
    • encoding (string): Output-Encoding - 'base64' (Standard) oder 'hex'
Rückgabewert: { signature: string } — Objekt mit der Signatur im angegebenen Encoding Beispiel: JWT-Signierung
Der Private Key muss im PEM-Format vorliegen. Ungültige Keys werfen benutzerfreundliche Fehlermeldungen. Gib niemals Private Keys in Logs oder Rückgabewerten preis.

Utility-Funktionen

ld.log()

Gib Debugging-Informationen in die Ausführungslogs aus, die unterhalb des “Test Action”-Buttons sichtbar sind. Parameter:
Beispiel:
Verwende ld.log() großzügig während der Entwicklung, um deinen Integrationscode zu debuggen. Logs werden automatisch bereinigt, um sensible Authentifizierungswerte zu verbergen.

ld.wait()

Pausiere die Ausführung für eine bestimmte Anzahl von Millisekunden. Nützlich für Rate Limiting oder Retry-Logik. Parameter:
Beispiel:

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-Dekodierung
Beispiel: Basic Authentication

Buffer.from()

Ein minimaler Polyfill zur Konvertierung zwischen typisierten Array-Formaten. Akzeptiert ein einzelnes Argument (Array, Uint8Array oder ArrayBuffer) und gibt ein Uint8Array zurück.
Dies ist NICHT der vollständige Node.js Buffer. Es akzeptiert nur Array, Uint8Array oder ArrayBuffer — keine Strings. Buffer.from("hello") wird einen Fehler auslösen. Das zurückgegebene Uint8Array hat keine .toString("base64")-Methode. Verwende stattdessen btoa()/atob() für Base64-Encoding/Decoding.
Beispiel: ArrayBuffer von ld.request() konvertieren
Beispiel: Heruntergeladene Datei in Base64 encodieren

FormData

Erstelle Multipart-Form-Daten für Datei-Uploads und komplexe Request-Bodies. Beispiel: Datei-Upload mit Metadaten

Standard-JavaScript-APIs

Die Sandbox bietet auch Zugriff auf Standard-JavaScript-Built-ins: JSON
  • JSON.stringify() - Konvertiere Objekte zu JSON-Strings
  • JSON.parse() - Parse JSON-Strings zu Objekten
Date
  • new Date() - Erstelle Date-Objekte
  • Date.now() - Erhalte aktuellen Timestamp
  • Alle Standard-Date-Methoden
Math
  • Math.floor(), Math.ceil(), Math.round()
  • Math.random(), Math.max(), Math.min()
  • Alle Standard-Math-Methoden
RegExp
  • new RegExp() - Erstelle reguläre Ausdrücke
  • String-Regex-Methoden: match(), replace(), test()
Array & Object
  • Alle Standard-Array-Methoden: map(), filter(), reduce(), etc.
  • Alle Standard-Object-Methoden: keys(), values(), entries(), etc.
Beispiel: Datentransformation

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-Aufrufe
Verwende Paginierung

Sicherheitsüberlegungen

Niemals Secrets hartcodieren
Bereinige User-Input
Behandle Rate Limits

Häufige Fallstricke

1. Async/Await nicht richtig behandeln
2. Auf verschachtelte Properties ohne Prüfung zugreifen
3. JSON-Strings nicht parsen
4. Eingefrorene Objekte modifizieren

Nächste Schritte

FAQ

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.
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.