Zum Inhalt

Dateien in ZIP verpacken

Der Service Task „Dateien in ZIP verpacken" fasst mehrere Datei-Referenzen – etwa aus vorangegangenen Service Tasks, Upload-Aktivitäten oder Formularfeldern – zu einem einzelnen ZIP-Archiv zusammen und gibt eine neue Datei-Referenz auf das erstellte Archiv zurück. So lassen sich mehrere generierte Dokumente als ein Download bereitstellen oder vor der Ablage gebündelt archivieren.

Der Service ist das Gegenstück zu „ZIP-Datei entpacken": Dessen Ausgabe (files und groups) kann unverändert als Eingabe übernommen werden. Damit sind Round-Trips wie „ZIP entpacken → einzelne Dateien verarbeiten → wieder zu einem neuen ZIP zusammenführen" direkt möglich.

Wann wird dieser Service-Task verwendet?

  • Sammel-Download generierter Dokumente: Mehrere erzeugte PDFs (z. B. Rechnungen eines Monats) werden zu einem einzigen Archiv gebündelt und zum Download bereitgestellt.
  • Archivierung: Am Ende eines Prozesses werden alle anfallenden Belege, Protokolle und Exporte in einem ZIP zusammengefasst und abgelegt.
  • Export mit Ordnerstruktur: Ein Datenexport enthält mehrere Kategorien (Rechnungen, Buchungen, Belege), die im ZIP als separate Ordner abgebildet werden.
  • Round-Trip mit „ZIP entpacken": Ein eingehendes Archiv wird zerlegt, einzelne Dateien werden transformiert, und das Ergebnis wird erneut als ZIP verpackt – ohne die ursprüngliche Struktur manuell nachbauen zu müssen.

Input-Parameter

Die folgenden Felder werden als Eingabe für den Task genutzt:

{
  "files": [
    {
      "referenceId": "...",
      "filename": "rechnung-001.pdf",
      "contentType": "application/pdf"
    }
  ],
  "groups": {
    "rechnungen": [
      {
        "referenceId": "...",
        "filename": "rechnung-002.pdf",
        "contentType": "application/pdf"
      }
    ]
  },
  "output_filename": "archive.zip",
  "compressionLevel": 5,
  "maxFiles": 5000,
  "maxTotalBytes": 2147483648
}

Erläuterung:

  • files: Liste von Datei-Referenzen, die direkt in das Wurzelverzeichnis des ZIP-Archivs gelegt werden (optional). Jeder Eintrag enthält referenceId, filename und contentType.
  • groups: Objekt, bei dem jeder Schlüssel einem Ordnerpfad innerhalb des ZIPs entspricht. Die zugeordnete Liste enthält Datei-Referenzen, die unter ordnername/dateiname abgelegt werden (optional).
  • output_filename: Name des erzeugten Archivs (optional, Standard: "archive.zip"). Die Endung .zip wird automatisch sichergestellt.
  • compressionLevel: Kompressionsstufe zwischen 0 und 9 (optional, Standard: 5).
    • 0 – keine Kompression, schnellste Verarbeitung, größte Datei.
    • 5 – ausgewogen (Standard).
    • 9 – maximale Kompression, langsamste Verarbeitung, kleinste Datei.
  • maxFiles: Maximale Anzahl an Dateien, die in das Archiv aufgenommen werden dürfen (optional, Standard: 5000).
  • maxTotalBytes: Maximale unkomprimierte Gesamtgröße in Bytes (optional, Standard: 2147483648 = 2 GB).

Mindestens eine Quelle erforderlich

Es muss entweder files oder groups (oder beides) mit mindestens einem Eintrag übergeben werden. Ohne Eingabedateien bricht der Task mit einem Fehler ab.

Output

Der Task liefert eine einzelne Datei-Referenz auf das erstellte ZIP-Archiv:

{
  "referenceId": "...",
  "filename": "archive.zip",
  "contentType": "application/zip"
}

Erläuterung:

  • referenceId: Referenz auf die erzeugte Datei im Daten-Lake. Kann direkt an Folge-Tasks übergeben werden, etwa zum Versand per E-Mail, zum Upload auf SharePoint/FTP oder zur Ablage in einem Datenobjekt.
  • filename: Der tatsächlich verwendete Dateiname (immer mit .zip-Endung).
  • contentType: Immer application/zip.

JSONata-Beispiele

Einfachfall – alle Dateien flach ins ZIP:

{
  "files": $.allePdfs,
  "output_filename": "rechnungen_2026.zip"
}

Mit Ordnerstruktur:

{
  "groups": {
    "rechnungen": $.rechnungsDateien,
    "buchungen": $.buchungsDateien
  },
  "output_filename": "export.zip"
}

Round-Trip – Ergebnis aus „ZIP entpacken" direkt wieder verpacken:

{
  "files": $.unzipResult.files,
  "groups": $.unzipResult.groups,
  "output_filename": "neu.zip"
}

Maximale Kompression für kleine Archive:

{
  "files": $.dokumente,
  "compressionLevel": 9,
  "output_filename": "klein.zip"
}

Hinweise

  • Round-Trip-kompatibel: Die Eingabe-Struktur entspricht exakt der Ausgabe von „ZIP-Datei entpacken". Felder wie count oder skipped, die im Unzip-Ergebnis zusätzlich enthalten sind, werden ignoriert.
  • Streaming-Verarbeitung: Dateien werden einzeln aus dem Daten-Lake gelesen und direkt in das ZIP geschrieben. Dadurch bleibt der Speicherverbrauch auch bei vielen oder großen Dateien konstant.
  • Namenskonflikte: Landen mehrere Dateien auf demselben Pfad im Archiv (z. B. zwei rechnung.pdf in derselben Gruppe), wird automatisch ein Zähler angehängt: rechnung.pdf, rechnung_2.pdf, rechnung_3.pdf.
  • Pfad-Bereinigung: Führende Schrägstriche sowie Path-Traversal-Muster (..) werden aus den Dateinamen entfernt, bevor die Datei ins Archiv geschrieben wird.
  • Dateiendung erzwungen: Wird output_filename ohne .zip-Endung angegeben, wird diese automatisch ergänzt.
  • compressionLevel = 0: Keine Kompression, Dateien werden nur gebündelt. Sinnvoll für Archive mit bereits komprimierten Formaten (PDF, JPG, PNG), bei denen zusätzliche Kompression kaum Einsparung bringt und nur Zeit kostet.

Limits und warum es sie gibt

Die Parameter maxFiles und maxTotalBytes dienen als Schutzgrenzen gegen unabsichtlich übergroße Archive:

  • Speicher- und Laufzeitschutz: Sehr große ZIPs können die maximale Ausführungszeit des Service Tasks überschreiten oder nachgelagerte Systeme (E-Mail-Anhänge, Uploads) an ihre Grenzen bringen.
  • Schutz vor Konfigurationsfehlern: JSONata-Ausdrücke, die versehentlich sehr viele Datei-Referenzen liefern, werden frühzeitig abgefangen.
  • maxTotalBytes prüft die unkomprimierte Gesamtgröße aus den Metadaten der Quell-Dateien. Dadurch greift das Limit auch dann, wenn der Kompressionsfaktor hoch wäre.

Die Default-Werte (5000 Dateien, 2 GB) sind großzügig bemessen und sollten für typische Sammel-Exporte nicht verändert werden müssen. Für besonders große Archive können die Limits explizit hochgesetzt werden – unter Beachtung der technischen Rahmenbedingungen der nachfolgenden Schritte.

Tipp

In Kombination mit „ZIP-Datei entpacken" lässt sich ein vollständiger Verarbeitungs-Loop modellieren: Ein eingehendes Archiv wird entpackt, die einzelnen Dateien werden in einem Multi-Instance-Subprozess transformiert oder geprüft, und das Ergebnis wird mit identischer Ordnerstruktur wieder zu einem ZIP verpackt. Da beide Services dasselbe Schema teilen, genügt es, files und groups direkt durchzureichen.