„output_meta“-Parameter in Transloadit erkunden

Samuel Ogundipe

Technischer Redakteur · Lagos, Nigeria · Bio anzeigen

Wenn Sie jemals die Dokumentation der Robots /upload/handle und /image/resize gelesen haben, ist Ihnen dort vielleicht der Parameter output_meta begegnet. Vielleicht haben Sie sich dann auch gefragt, was er genau bewirkt. Denn anders als bei den meisten anderen Parametern erschließt sich seine Verwendung nicht unbedingt sofort aus dem Namen allein :)

Nehmen wir uns also einen Moment Zeit, um zu erklären, wie dieser Parameter funktioniert und warum er entstanden ist!

Der Parameter output_meta

Die Idee hinter dem Parameter output_meta ist, unseren Kunden die Möglichkeit zu geben, bestimmte Metadaten zu ihren Dateien zu erfassen. Klingt danach, als hätte man das gerne dauerhaft aktiviert, oder? Nun, die Berechnung beansprucht allerdings auch deutlich mehr CPU-Leistung. Damit diese Assemblies also jederzeit schnell laufen, haben wir einen Parameter für das Erfassen einiger Metadaten geschaffen und ihn standardmäßig deaktiviert gelassen.

Sie können den Parameter output_meta in den Steps unserer Robots festlegen, um zu entscheiden, ob Sie zusätzliche Metadaten pro Encoding-Ergebnis erhalten möchten. Das verschafft unseren Nutzern zwar den Luxus feiner Kontrolle und Granularität, führte aber auch zu einem Problem: Wie aktiviert man ihn für hochgeladene Dateien? Wir unterstützen Datei-Uploads seit 2008, doch sie waren immer ein wenig ein Sonderfall, denn Uploads waren früher die einzigen Dateien, die nicht das Ergebnis unserer Robots waren.

Nach der Einführung der feingranularen Kontrolle durch den Parameter output_meta war der nächste logische Schritt also, die Upload-Verarbeitung in einem eigenen Robot zu kapseln und zusammen mit dem neuen Parameter den Robot /upload/handle einzuführen. Jetzt gibt es keine Ausnahmen mehr, und das Verhalten lässt sich bei jedem Step für jede Datei anpassen.

Wie funktioniert das?

Der Parameter output_meta kann optionale Metadaten mithilfe eines Objekts aus booleschen Eigenschaften, eines Arrays von Eigenschaftsnamen oder eines booleschen Werts auswählen. Dieses Beispiel verwendet has_transparency; zu den weiteren unterstützten Eigenschaften zählen dominant_colors und blurhash. Wenn has_transparency auf true gesetzt ist, wird das Bild analysiert und Ihnen mitgeteilt, ob es transparente Bereiche enthält. Da die Berechnung von has_transparency bei bestimmten Dateien lange dauern kann, haben wir sie standardmäßig aus der Ergebnismenge ausgeschlossen. Schließlich möchten wir nicht, dass unsere Kunden einen Aufschlag an Ausführungszeit zahlen, wenn ihnen diese Eigenschaft von vornherein gar nicht wichtig ist.

Wenn Sie beispielsweise doch wissen möchten, ob Ihre hochgeladenen Dateien transparente Bereiche haben, können Sie "output_meta": { "has_transparency": true } beim Robot /upload/handle setzen. Anschließend finden Sie meta.has_transparency in den resultierenden Dateien gesetzt.

Schauen wir uns an, wie sich eine Assembly erstellen lässt, die diesen Parameter verwendet. Machen Sie gerne mit!

Die Assembly erstellen

In diesem Abschnitt erstellen wir zwei separate Assembly Instructions, die uns zeigen, wie der Parameter sowohl im Robot /upload/handle als auch im Robot /image/resize verwendet wird.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle",
      "output_meta": {
        "has_transparency": true
      }
    }
  }
}

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "resized": {
      "use": [":original"],
      "robot": "/image/resize",
      "result": true,
      "background": "white",
      "flatten": false,
      "height": 500,
      "imagemagick_stack": "v2.0.3",
      "resize_strategy": "pad",
      "rotation": false,
      "strip": true,
      "trim_whitespace": true,
      "width": 250,
      "output_meta": {
        "has_transparency": true
      }
    }
  }
}

Hier haben wir zwei unterschiedliche Assembly Instructions. Die einen verwenden nur den Robot /upload/handle, die anderen den Robot /image/resize.

Beachten Sie, dass in den Assembly Instructions mit dem Robot /image/resize die Eigenschaft output_meta nicht im Step :original auftaucht, sondern im Step resized. Denn in diesen Assembly Instructions prüfen wir die Transparenz, wenn die Größe der Datei geändert wird, und nicht, wenn sie hochgeladen wird.

Die Ergebnisse

Wenn wir eine der obigen Assembly Instruction-Varianten ausführen, sehen wir am JSON-Ergebnis für den Robot /upload/handle, dass die Eigenschaft meta des Schlüssels uploads ein Feld namens has_transparency enthält, das auf true gesetzt ist. Diese Eigenschaft gibt nur dann true zurück, wenn das Bild transparente Bereiche enthält.

Ebenso hat im JSON-Ergebnis, das für den Robot /image/resize zurückgegeben wird, die Eigenschaft meta des Schlüssels resized im Abschnitt results ein Feld namens has_transparency, das auf true gesetzt ist.

Wie Sie sehen, kann der Parameter output_meta ausgesprochen praktisch sein! Wir überlegen außerdem, Ihnen die Möglichkeit zu geben, weitere bestehende Meta-Schlüssel abzuwählen, um Assemblies zu beschleunigen. Derzeit berechnen wir zum Beispiel standardmäßig MD5-Hashes für alle Dateien, obwohl viele Anwendungsfälle das gar nicht benötigen. Sobald wir also weitere Eigenschaften haben, die sich mit diesem Parameter angeben lassen, sagen wir Ihnen auf jeden Fall Bescheid! 💖