1. Dateieingabe in Aktionen
Dateieingaben ermöglichen es Nutzern, Dateien hochzuladen, die deine Aktion dann verarbeiten oder an externe APIs senden kann.1.1 Wann du Dateieingaben verwenden solltest
- Dateien zu externen Tools hochladen: Sende von Nutzern hochgeladene Dokumente an APIs, Cloud-Speicher oder externe Dienste wie E-Mail oder Ticket-Systeme.
- Nutzerdateien verarbeiten: Analysiere, konvertiere oder transformiere von Nutzern hochgeladene Dateien
1.2 Dateieingabefelder hinzufügen
Einzelne Dateieingabe
Füge ein Eingabefeld vom Typ “FILE” hinzu, um eine Datei zu akzeptieren:
Mehrere Dateieingaben
Für mehrere Dateien aktiviere Mehrere Dateien erlauben:
1.3 Auf Dateidaten im Code zugreifen
Jede hochgeladene Datei wird alsFileData
-Objekt mit diesem exakten Format geliefert:
Wichtig: Dateieingaben enthalten KEINEtext
-Eigenschaft. Dietext
-Abkürzung existiert nur für Dateiausgaben.
Zugriff auf einzelne Datei
Zugriff auf mehrere Dateien
Datenstruktur: Wenn “Mehrere Dateien erlauben” aktiviert ist, ist data.input.fieldName
ein Array. Andernfalls ist es ein einzelnes Objekt.
1.4 Häufige Eingabemuster
1.5 Eingabevalidierung & Fehlerbehandlung
2. Dateiausgabe in Aktionen
Dateiausgaben ermöglichen es deiner Aktion, Dateien zu generieren und zurückzugeben, die Nutzer herunterladen oder in nachfolgenden Aktionen verwenden können.2.1 Wann du Dateiausgaben verwenden solltest
- Berichte generieren: PDFs, Tabellenkalkulationen oder Dokumente aus Daten erstellen
- Dateien von APIs abrufen: Dateien von externen Diensten herunterladen
- Dateien transformieren: Zwischen Formaten konvertieren oder hochgeladene Dateien verarbeiten
- Daten exportieren: CSV-Exporte, Backup-Dateien oder Daten-Dumps erstellen
2.2 Dateiausgabeformat
Gib Dateien unter einemfiles
-Schlüssel in deiner Antwort zurück:
Dateiausgabe-Eigenschaften
Feld | Erforderlich | Hinweise |
---|---|---|
fileName | ✓ | Richtige Dateierweiterung einschließen |
mimeType | ✓ | Genauer MIME-Typ für ordnungsgemäße Verarbeitung |
base64 | ✓* | Base64-kodierter Binärinhalt |
text | ✓* | UTF-8 Textinhalt (Alternative zu base64) |
lastModified | – | ISO-Datumsstring (Standard ist aktuelle Zeit) |
base64
ODER text
an, niemals beides.
2.3 Häufige Ausgabemuster
3. Dateiausgabe in Triggern
Trigger können auch Dateien zurückgeben, wenn sie Ereignisse erkennen, die Dateianhänge enthalten, oder wenn sie Dateien basierend auf Trigger-Daten generieren.Wichtiger Unterschied: Im Gegensatz zu Aktionen, die Objekte direkt zurückgeben, müssen Trigger ein Array von Ereignissen zurückgeben. Jedes Ereignis benötigtid
,timestamp
unddata
Eigenschaften, mit Dateien innerhalb desdata
-Objekts.
3.1 Wann du Dateiausgaben in Triggern verwenden solltest
- E-Mail-Anhänge: Anhänge von eingehenden E-Mails weiterleiten
- Dateiänderungsereignisse: Modifizierte oder neue Dateien von überwachten Systemen zurückgeben
- Generierte Benachrichtigungen: Zusammenfassungsdateien oder Berichte erstellen, wenn Ereignisse auftreten
- API-Webhook-Dateien: Dateien aus Webhook-Payloads verarbeiten und weiterleiten
3.2 Trigger-Dateiausgabeformat
Trigger müssen ein Array von Objekten mitid
, timestamp
und data
Eigenschaften zurückgeben. Dateien kommen innerhalb des data
-Objekts:
Wichtig: Im Gegensatz zu Aktionen müssen Trigger ein Array von Ereignissen zurückgeben, undfiles
muss innerhalb desdata
-Objekts sein, nicht auf oberster Ebene.
3.3 Häufige Trigger-Muster
4. Plattform-Einschränkungen & Limits
Einschränkung | Limit |
---|---|
Gesamte Dateigröße pro Aktion | 100 MB |
Maximale Dateien pro Aktion | 20 Dateien |
Einzelne Dokumente | ≤ 256 MB* |
Einzelne Bilder | ≤ 20 MB |
Einzelne Tabellenkalkulationen | ≤ 30 MB |
Einzelne Audiodateien | ≤ 200 MB* |
Einzelne Videodateien | ≤ 20 MB |
Andere Dateitypen | ≤ 10 MB |
Aktions-Ausführungs-Timeout | 2 Minuten |
Validierung: Das Überschreiten von Limits löst einen Fehler aus bevor dein Code ausgeführt wird.
4.1 Sandbox-Bibliotheksbeschränkungen
Nutzerdefinierter Aktions- und Trigger-Code läuft in einer sicheren Sandbox-Umgebung.
Du kannst keine externen Bibliotheken installieren oder importieren (npm, pip, etc.) – nur eine begrenzte Anzahl von eingebauten JavaScript/Node.js APIs ist verfügbar.
Für erweiterte Dateiverarbeitung (z.B. PDF-Parsing, Bildmanipulation), verwende externe APIs oder Dienste und rufe sie aus deinem Code auf.
5. Best Practices
Best Practices für Dateieingaben
- Dateitypen früh validieren: Prüfe MIME-Typen vor der Verarbeitung
- Fehlende Dateien elegant behandeln: Verwende
|| []
für optionale Datei-Arrays - Dateimetadaten protokollieren: Hilft beim Debuggen von Problemen ohne Inhalt preiszugeben
- Klare Fehlermeldungen bereitstellen: Sage Nutzern genau, was schiefgelaufen ist
Best Practices für Dateiausgaben
- Aussagekräftige Dateinamen verwenden: Füge Daten, IDs oder beschreibende Namen hinzu
- Genaue MIME-Typen setzen: Ermöglicht ordnungsgemäße Dateiverarbeitung und Vorschauen
- Text-Abkürzung für UTF-8 verwenden: Effizienter als base64 für Textdateien
- Verarbeitungsstatus einschließen: Hilf Nutzern zu verstehen, was passiert ist
Performance Best Practices
- Dateien nach Möglichkeit parallel verarbeiten: Verwende
Promise.all()
für unabhängige Vorgänge - Vermeide alle Dateien in den Speicher zu laden: Verarbeite eine nach der anderen bei großen Batches
- Fortschritt protokollieren: Verwende
ld.log()
um den Verarbeitungsstatus zu verfolgen - Fehler elegant behandeln: Fahre mit der Verarbeitung anderer Dateien fort, wenn eine fehlschlägt
6. Fehlerbehebung
Problem | Wahrscheinliche Ursache | Lösung |
---|---|---|
”Datei nicht gefunden” | Nutzer hat keine Datei angehängt | Mache Dateieingabe erforderlich oder füge Validierung hinzu |
Größenlimit-Fehler | Dateien überschreiten 100 MB gesamt | Bitte um kleinere oder weniger Dateien |
”Ungültiger Dateityp” | Falscher MIME-Typ | Validiere file.mimeType in deinem Code |
Leerer Dateiinhalt | Base64-Kodierungsproblem | Überprüfe, dass file.base64 gültig ist |
Timeout-Fehler | Große Dateien oder langsame Verarbeitung | Optimiere Verarbeitung oder reduziere Dateigrößen |
Speicherfehler | Zu viele große Dateien | Verarbeite Dateien sequenziell, nicht parallel |