# Dateien filtern

Robot: `/file/filter`

🤖/file/filter leitet Dateien anhand Ihrer Bedingungen an verschiedene Encoding-Steps weiter.

Betrachten Sie diesen <dfn>Robot</dfn> als eine `if/else`-Bedingung zum Erstellen fortgeschrittener Workflows für die Dateikonvertierung. Damit können Sie bestimmte hochgeladene Dateien anhand ihrer Metadaten filtern und weiterleiten.

Der <dfn>Robot</dfn> bietet zwei Betriebsmodi:

* Bedingungen aus Arrays mit jeweils 3 Elementen erstellen. Beispiel: `["${file.size}", "<=", "720"]`
* Bedingungen in JavaScript schreiben. Beispiel: `${file.size <= 720}`. Siehe auch [Dynamische Auswertung](/de/docs/topics/dynamic-evaluation.md).

Wenn ein `/file/filter`-Step jede Eingabedatei unverändert durchreichen soll, lassen Sie `accepts` und
`declines` ungesetzt oder setzen Sie beide auf `null`. Verwenden Sie hierfür nicht `"accepts": "true"`: Einfache Zeichenfolgen
werden nur dann als JavaScript-Ausdrücke behandelt, wenn sie die Form `${...}` verwenden, beispielsweise `"${true}"`.

Mit JavaScript können Sie beliebig komplexe Logik implementieren. Dies ist jedoch langsamer als das Kombinieren von Bedingungs-Arrays und wird bei jedem Aufruf über [🤖/script/run](/de/docs/robots/script-run.md) abgerechnet.

### Bedingungen als Arrays

Die Parameter `accepts` und `declines` können jeweils auf ein Array aus Arrays mit drei Elementen gesetzt werden:

1. Ein Wert oder eine Job-Variable, beispielsweise `${file.mime}`
2. Einer der folgenden Operatoren: `=`, `==`, `===`, `<`, `>`, `<=`, `>=`, `!=`, `!==`, `regex`, `!regex`, `includes`, `!includes`, `empty`, `!empty`
3. Ein Wert oder eine Job-Variable, beispielsweise `50` oder `"foo"`

Beispiele:

* `[["${file.meta.width}", ">", "${file.meta.height}"]]`
* `[["${file.size}", "<=", "720"]]`
* `[["${file.size}", ">", "20mb"]]`
* `[["720", ">=", "${file.size}"]]`
* `[["${file.mime}", "regex", "image"]]`

Bei einem Abgleich mit `${file.mime}` basiert der Wert im normalen Upload-Ablauf üblicherweise auf der serverseitigen Metadatenextraktion von Transloadit und nicht ausschließlich auf dem vom Client oder Browser gemeldeten MIME-Typ. Dadurch eignet sich `/file/filter` dazu, falsch gekennzeichnete Dateien abzulehnen. Abhängig vom Dateicontainer und den beteiligten Erkennungswerkzeugen können einige Formate unter eng verwandten MIME-Typen wie `image/heic` oder `image/heif` gemeldet werden.

Wenn Sie ausschließlich Formate zulassen möchten, die Browser zuverlässig darstellen, verwenden Sie vorzugsweise eine explizite Positivliste wie `^(image/jpeg|image/png|image/gif|image/webp|image/avif)$` anstelle einer weit gefassten Regel wie `^image/`.

Für numerische Vergleiche (`<`, `>`, `<=`, `>=`) können Sie menschenlesbare Byte-Werte wie `"20mb"`, `"1gb"` oder `"512kb"` verwenden. Diese verwenden binäre Multiplikatoren auf Basis von 1024. Unterstützte Einheiten: `b`, `kb`, `mb`, `gb`, `tb`, `pb` (sowie deren IEC-Entsprechungen `kib`, `mib`, `gib`, `tib`, `pib`).

Die Operatoren `includes` und `!includes` funktionieren mit Arrays oder Zeichenfolgen (bei Zeichenfolgen werden Teilzeichenfolgen geprüft).

> [!Warning]
> Wenn Sie einen Abgleich mit dem Wert `null` oder mit einem nicht vorhandenen Wert durchführen möchten (beispielsweise wenn eine Audiodatei in ihren Metadaten keine Eigenschaft `video_codec` besitzt), gleichen Sie stattdessen mit `""` (einer leeren Zeichenfolge) ab. Künftig werden wir einen korrekten Abgleich mit `null` unterstützen. Derzeit ist dies jedoch nicht ohne Weiteres möglich, ohne die Abwärtskompatibilität zu beeinträchtigen.

### Bedingungen als JavaScript

Die Parameter `accepts` und `declines` können jeweils auf JavaScript-Zeichenfolgen gesetzt werden, die einen booleschen Wert zurückgeben.

Beispiele:

* `${file.meta.width > file.meta.height}`
* `${file.size <= 720}`
* `${/image/.test(file.mime)}`
* `${Math.max(file.meta.width, file.meta.height) > 100}`

Wie beschrieben rechnen wir dies über [🤖/script/run](/de/docs/robots/script-run.md) ab. Weitere Einzelheiten zur zulässigen Syntax und zum Verhalten finden Sie unter [Dynamische Auswertung](/de/docs/topics/dynamic-evaluation.md).

Phase: ga

## Anwendungsbeispiel

Dateien ablehnen, die größer als 20 MB sind:

```json
{
  "steps": {
    "filtered": {
      "robot": "/file/filter",
      "use": ":original",
      "declines": [
        [
          "${file.size}",
          ">",
          "20mb"
        ]
      ],
      "error_on_decline": true,
      "error_msg": "File size must not exceed 20 MB"
    }
  }
}
```

## Parameter

* `interpolate`: Steuert, ob einzelne Robot-Anweisungsfelder Assembly Variables interpolieren.

  Standardmäßig interpolieren die meisten Robot-Anweisungsfelder Assembly Variables. Mit dem Wert `false` behandeln Sie alle Anweisungsfelder als Literaltext. Wenn Sie stattdessen einen einzelnen Feldpfad auf `false` setzen, wird nur dieses Feld als Literaltext behandelt. Bei Feldern eines bestimmten Robots, die standardmäßig als Literaltext behandelt werden, aktivieren Sie die Interpolation wieder, indem Sie hierfür `true` festlegen oder für den jeweiligen Feldpfad den Wert `true` verwenden.

  Verwenden Sie Feldnamen wie `path` oder für verschachtelte Objekte Punktpfade wie `ffmpeg.vf` als Pfadangabe.

* `output_meta`: Damit können Sie eine Reihe von Metadaten festlegen, deren Berechnung mehr CPU-Ressourcen beansprucht. Sie sind daher standardmäßig deaktiviert, damit Ihre Assemblies schnell verarbeitet werden.

  Für Bilder können Sie diesem Objekt den Eintrag `"has_transparency": true` hinzufügen, um zu ermitteln, ob das Bild transparente Bereiche enthält. Mit dem Eintrag `"dominant_colors": true` können Sie außerdem ein Array mit hexadezimalen Farbcodes aus dem Bild extrahieren.

  Für Bilder können Sie auch den Eintrag `"blurhash": true` hinzufügen, um einen [BlurHash](https://blurha.sh) zu extrahieren – eine kompakte Darstellung eines Platzhalters für das Bild, mit der Sie eine unscharfe Vorschau anzeigen können, während das vollständige Bild geladen wird.

  Für Videos können Sie den Parameter `"colorspace": true` hinzufügen, um den Farbraum des Ausgabevideos zu extrahieren.

  Für Videos können Sie außerdem den Eintrag `"interlaced": true` hinzufügen, um zu erkennen, ob das Video im Zeilensprungverfahren vorliegt. Dazu wird die ressourcenschonende ffprobe-Option `field_order` mit einem begrenzten Stichprobendurchlauf mithilfe von `idet` über die ersten Frames der Quelle kombiniert. Die Ergebnisse `interlaced` und `field_order` sowie das Diagnoseobjekt `interlace_detection` werden dabei unter `file.meta` ausgegeben. Dies ist rechenintensiv und wird entsprechend abgerechnet.

  Für Audio können Sie den Eintrag `"mean_volume": true` hinzufügen, um einen einzelnen Wert für die durchschnittliche Lautstärke der Audiodatei zu erhalten.

  Sie können diesen Parameter auch auf `false` setzen, um die Metadatenextraktion zu überspringen und das Transcoding zu beschleunigen.

* `user_meta`: Fügt jeder von diesem Robot ausgegebenen Datei benutzerdefinierte Metadaten hinzu, ohne den Dateiinhalt zu verändern.

  Die Werte werden mit allen bereits in der Eingabedatei enthaltenen `user_meta` zusammengeführt. Wenn beide Objekte denselben Schlüssel enthalten, hat der Wert dieses Robots Vorrang. Assembly Variables werden unterstützt, zum Beispiel `{ "internal_file_id": "${file.id}" }`.

* `result`: Ob die Ergebnisse dieses Steps im Assembly Status JSON enthalten sein sollen

* `queue`: Wenn Sie die Queue auf „batch“ setzen, wird die Priorität der Jobs für diesen Step manuell herabgestuft. So vermeiden Sie, Priority Job Slots für Jobs zu belegen, die keine Wartezeit von null in der Queue benötigen.

* `force_accept`: Erzwingt, dass ein Robot einen Dateityp akzeptiert, den er sonst ignorieren würde.

  Standardmäßig ignorieren Robots Dateien, deren Typ sie nicht kennen.
  [🤖/video/encode](/de/docs/robots/video-encode.md) ignoriert beispielsweise problemlos Eingabebilder.

  Wenn Sie den Parameter `force_accept` auf `true` setzen, können Sie erzwingen, dass Robots alle übergebenen Dateien akzeptieren.
  Dies führt in der Regel zu Fehlern und sollte nur zur Fehlersuche oder zur Behandlung von Grenzfällen verwendet werden.

* `ignore_errors`: Fehler in bestimmten Verarbeitungsphasen ignorieren.

  Wenn Sie hierfür `["meta"]` festlegen, ignoriert der Robot Fehler bei der Metadatenextraktion.

  Wenn Sie hierfür `["execute"]` festlegen, ignoriert der Robot Fehler während der Hauptausführungsphase.

  Wenn Sie hierfür `true` festlegen, entspricht dies `["meta", "execute"]` und Fehler in beiden Phasen werden ignoriert.

* `use`: Gibt an, welche Steps als Eingabe verwendet werden sollen.

  * Sie können beliebige Namen für Steps wählen, außer `":original"` (reserviert für von Transloadit verarbeitete Benutzer-Uploads)
  * Sie können mehrere Steps mithilfe von Arrays als Eingabe angeben:
    ```json
    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    ```
  * Sie können Eingabe-Steps außerdem mit `as` kennzeichnen, um Robots die semantische Funktion zu übermitteln:
    ```json
    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    ```

  > [!Tip]
  > Das ist wahrscheinlich alles, was Sie über `use` wissen müssen. Sie können sich jedoch auch die [erweiterten Anwendungsfälle](/de/docs/topics/use-parameter.md) ansehen.

* `accepts`: Dateien, die mindestens eine Anforderung erfüllen, werden akzeptiert, alle anderen werden abgelehnt. Ist der Wert `null`, werden alle Dateien akzeptiert. Ist das Array leer, werden keine Dateien akzeptiert. Lassen Sie diesen Parameter weg oder setzen Sie ihn auf `null`, wenn der Step jede Datei durchreichen soll. Beispiele:

  `[["${file.mime}", "==", "image/gif"]]`
  `[["${file.size}", "<", "5kb"]]`

  Für numerische Vergleiche (`<`, `>`, `<=`, `>=`) werden menschenlesbare Byte-Werte wie `"20mb"`, `"1gb"` oder `"512kb"` unterstützt.

  Wenn der Parameter `condition_type` auf `"and"` gesetzt ist, müssen alle Anforderungen erfüllt sein, damit die Datei akzeptiert wird.

  Wenn sowohl `accepts` als auch `declines` angegeben sind, werden zuerst die Anforderungen in `accepts` und anschließend die Bedingungen in `declines` ausgewertet.

* `declines`: Dateien, die mindestens eine Anforderung erfüllen, werden abgelehnt, andernfalls werden sie akzeptiert. Wenn der Wert `null` oder ein leeres Array ist, werden keine Dateien abgelehnt. Beispiele:

  `[["${file.size}", ">", "1024"]]`
  `[["${file.size}", ">", "20mb"]]`

  Für numerische Vergleiche (`<`, `>`, `<=`, `>=`) werden menschenlesbare Byte-Werte wie `"20mb"`, `"1gb"` oder `"512kb"` unterstützt.

  Wenn der Parameter `condition_type` auf `"and"` gesetzt ist, müssen alle Anforderungen erfüllt sein, damit die Datei abgelehnt wird.

  Wenn sowohl `accepts` als auch `declines` angegeben sind, werden zuerst die Anforderungen in `accepts` und anschließend die Bedingungen in `declines` ausgewertet.

* `condition_type`: Legt den Bedingungstyp fest, nach dem die Einträge der Arrays `accepts` oder `declines` ausgewertet werden sollen. Mögliche Werte sind `"or"` und `"and"`.

* `error_on_decline`: Wenn dies auf `true` gesetzt ist und eine oder mehrere Dateien abgelehnt werden, wird die Assembly angehalten und als fehlerhaft markiert.

* `error_msg`: Die Fehlermeldung, die Ihren Benutzern angezeigt wird, beispielsweise durch Uppy, wenn eine Datei abgelehnt wird und `error_on_decline` auf `true` gesetzt ist.