Direkt zum Hauptinhalt

Aus einem Skript eine Datei in den Speicher schreiben

Ziel​

Eine benutzerdefinierte API eine Datei erzeugen lassen – einen CSV-Export, eine JSON-Übergabe für ein anderes System – und sie dort ablegen, wo ein externes System sie abholen kann.

Warum es das gibt​

Die Plattform kennt drei Orte, an denen eine Datei liegen kann, und sie sind nicht austauschbar.

FürBeispiel
WebressourcenDateien, die Teil der Anwendung sindEin Logo, ein Stylesheet
DatensatzdateienEine Datei, die zu einem Datensatz gehörtDas Foto eines Kontakts, ein unterschriebener Vertrag
ObjektspeicherDateien, die zu keinem Datensatz gehörenEin Monatsexport, eine Integrationsübergabe

Die Datei eines Datensatzes hängt an einem Datensatz und reist mit ihm. Ein Export gehört zu keinem Datensatz – es gibt keine Zeile, an die er sich hängen ließe –, und genau dafür ist der Objektspeicher da.

Bevor Sie beginnen​

Sie brauchen einen Bucket-Namen. Sie müssen den Bucket nicht anlegen: Der erste Schreibvorgang legt ihn an.

Bucket-Namen bestehen aus Kleinbuchstaben, Ziffern und Bindestrichen, 3–63 Zeichen. Sie werden, wie bei S3, von allen Mandanten gemeinsam genutzt; ein schlichter Name wie exports ist daher womöglich schon vergeben – setzen Sie etwas Eigenes davor, wie par-exports unten.

Was ein Skript tun kann​

putFile(bucket, key, text)Schreibt eine Datei. Antwortet true, oder false, wenn es nicht möglich war
putFileAs(bucket, key, text, contentType)Dasselbe, mit Angabe der Dateiart
getFile(bucket, key)Liest sie als Text zurück – die leere Zeichenfolge, wenn es keine gibt
fileExists(bucket, key)true oder false
listFiles(bucket, prefix)Die Dateien unter einem Präfix, jeweils mit key, size, contentType und uploadedAt
deleteFile(bucket, key)Entfernt eine Datei

Der Schlüssel ist der Pfad der Datei im Bucket – claims/2026-09.csv. Schrägstriche darin sind einfach Teil des Namens, werden im Speicher-Bildschirm aber als Ordner angezeigt; eine Gruppierung danach lohnt sich also.

Schritte​

  1. Öffnen Sie Ihre Lösung, wählen Sie Benutzerdefinierte APIs und dann Neu aus.

  2. Geben Sie ihr eine Route – claims/export/{period} – und wählen Sie Post.

  3. Bauen Sie die Datei im Skript als Text auf und schreiben Sie sie:

    var claims = runQuery({ entity: 'par_claim', select: ['par_name', 'par_amount'] });

    var csv: string = 'reference,amount\n';
    for (var i: int = 0; i < claims.length(); i++) {
      csv = csv + `${claims[i].par_name},${claims[i].par_amount}` + '\n';
    }

    putFileAs('par-exports', 'claims/' + getInput('period') + '.csv', csv, 'text/csv');

  4. Wählen Sie Speichern aus und rufen Sie die API auf.

Drei typische Stolperfallen​

  • length() braucht seine Klammern. claims.length ist kein Fehler – es ist nichts, sodass eine davon abhängige Schleife nie läuft und Ihr Export aus einer Kopfzeile ohne Zeilen besteht. Das ist der eine Fehler hier, der sich nicht selbst meldet.
  • Sie können keine Zahl zu einer Zeichenfolge addieren. 'Total: ' + amount wird abgelehnt. Setzen Sie die Zahl stattdessen in eine Backtick-Vorlage – `Total: ${amount}` –, der einzige Weg, eine Zahl in Text umzuwandeln.
  • Geben Sie an, welche Art Datei es ist. putFile speichert sie als reinen Text, und ein Browser zeigt reinen Text im Tab an, statt ihn zu speichern. Verwenden Sie putFileAs mit text/csv, application/json oder was es tatsächlich ist.

Prüfen, ob es funktioniert hat​

Wechseln Sie zu Administration → Speicher, öffnen Sie den Bucket, und die Datei ist dort mit ihrer Größe und ihrem Typ. Laden Sie sie herunter und prüfen Sie den Inhalt.

Wofür das nicht gedacht ist​

  • Große Binärdateien. Die Datei eines Skripts ist Text, den es aufgebaut hat. Bilder, PDFs und Archive verarbeitet die Plattform selbst, die sie streamt.
  • Eine Datei, die zu einem Datensatz gehört. Geben Sie der Tabelle stattdessen eine Datei- oder Bildspalte – sie wird mit den eigenen Berechtigungen des Datensatzes ausgeliefert, und das Löschen des Datensatzes nimmt die Datei mit.
  • Jemandem einen Link geben. Diese Funktionen geben Ihrem Skript den Text; sie erzeugen keine URL. Ein Link, der ohne Anmeldung funktioniert, ist ein Schlüssel, den jeder weitergeben kann, daher ist er ein bewusster Schritt an anderer Stelle und nichts, was ein Skript nebenbei tut.

Fehlerbehebung​

„Bucket wurde nicht gefunden.“ Sie lesen oder listen einen Bucket, der noch nicht existiert – nur Schreiben legt einen an. Schreiben Sie zuerst oder prüfen Sie die Schreibweise.

In der Datei steht nur die Kopfzeile. length ohne Klammern. Siehe oben.

„In diesem Ausdruck sind nur Zahlen oder Zeichenfolgen erlaubt.“ Sie haben eine Zahl zu einer Zeichenfolge addiert. Verwenden Sie eine Backtick-Vorlage.

„Dieser Lauf hat keinen Aufrufer.“ Das Skript ist ein asynchroner Plug-in-Schritt. Diese laufen, nachdem die Anfrage, die sie eingereiht hat, abgeschlossen ist; es gibt also niemanden, als der sie handeln könnten. Verwenden Sie einen synchronen Schritt oder eine benutzerdefinierte API.

Siehe auch​