# Dateien aus Amazon S3 importieren

Robot: `/s3/import`

🤖/s3/import importiert ganze Dateiverzeichnisse aus Ihrem S3-Bucket.

Wenn Amazon S3 neu für Sie ist, lesen Sie unser Tutorial zur [Verwendung Ihres eigenen S3-Buckets](/de/docs/faq/how-to-set-up-an-amazon-s3-bucket.md).

Die URL der Ergebnisdatei in Ihrem S3-Bucket wird im <dfn>Assembly Status JSON</dfn> zurückgegeben.

> [!Warning]
> **Verwenden Sie DNS-konforme Bucket-Namen**. Der Name Ihres Buckets [muss DNS-konform sein](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) und darf keine Großbuchstaben enthalten. Alle nicht alphanumerischen Zeichen in den Dateinamen werden durch einen Unterstrich und Leerzeichen durch Bindestriche ersetzt. Wenn Ihr vorhandener S3-Bucket Großbuchstaben enthält oder aus anderen Gründen nicht DNS-konform ist, schreiben Sie die Ergebnis-URLs mithilfe des zum <dfn>Robot</dfn> gehörenden Parameters `url_prefix` um.

<span id="minimum-s3-iam-permissions" aria-hidden="true"></span>

## Zugriff beschränken

Sie müssen Ihrem Bucket außerdem Berechtigungen hinzufügen, damit Transloadit ordnungsgemäß darauf zugreifen kann. Hier sehen Sie eine beispielhafte IAM-Richtlinie, die Sie verwenden können. Gemäß dem [Prinzip der geringsten Rechte](https://en.wikipedia.org/wiki/Principle_of_least_privilege) enthält sie die **mindestens erforderlichen Berechtigungen**, um mit Transloadit eine Datei aus Ihrem S3-Bucket zu importieren. Abhängig von Ihrer Anwendung benötigen Sie möglicherweise weitere Berechtigungen, insbesondere Leseberechtigungen.

Passen Sie `{BUCKET_NAME}` in den Werten für `Sid` und `Resource` entsprechend an. Diese Richtlinie gewährt außerdem allen Ihren Benutzern die mindestens erforderlichen Berechtigungen. Wir empfehlen Ihnen, einen separaten Amazon-IAM-Benutzer zu erstellen und dessen Benutzer-ARN, die Sie im Tab „Zusammenfassung“ eines Benutzers [hier](https://console.aws.amazon.com/iam/home#users) finden, als Wert für `Principal` zu verwenden. Weitere Informationen dazu finden Sie [hier](https://docs.aws.amazon.com/AmazonS3/latest/dev/AccessPolicyLanguage_UseCases_s3_a.html).

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowTransloaditToImportFilesIn{BUCKET_NAME}Bucket",
      "Effect": "Allow",
      "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
      "Resource": ["arn:aws:s3:::{BUCKET_NAME}", "arn:aws:s3:::{BUCKET_NAME}/*"]
    }
  ]
}
```

Der Wert `Sid` ist lediglich eine Kennung, anhand derer Sie die Regel später wiedererkennen können. Sie können ihn beliebig benennen.

Die Richtlinie muss in zwei Teile aufgeteilt werden, da die Aktion `ListBucket` Berechtigungen für den Bucket erfordert, während die anderen Aktionen Berechtigungen für die Objekte im Bucket benötigen. Wenn die Objekte das Ziel sind, enthält der Parameter `Resource` am Ende einen Schrägstrich und ein Sternchen. Wenn die Richtlinie hingegen auf den Bucket abzielt, werden der Schrägstrich und das Sternchen weggelassen.

Um korrekte Ergebnis-URLs zu erstellen, müssen wir wissen, in welcher Region sich Ihr S3-Bucket befindet. Dafür benötigen wir die Berechtigung `GetBucketLocation`. Wenn wir die Region Ihres Buckets auf diese Weise ermitteln, werden Ihre Assemblies außerdem langsamer. Um dies erheblich zu beschleunigen und die Berechtigung `GetBucketLocation` nicht mehr zu benötigen, haben wir den Parameter `bucket_region` zu den Robots /s3/store und /s3/import hinzugefügt. Wir empfehlen, ihn stets zu verwenden.

Beachten Sie bitte, dass Sie bei Verwendung einer Bucket-Verschlüsselung möglicherweise auch `"sts:*"` und `"kms:*"` zur Bucket-Richtlinie hinzufügen müssen. Falls bei der Verwendung unserer beispielhaften Bucket-Richtlinie Probleme auftreten, lesen Sie bitte [hier](https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html) und [hier](https://aws.amazon.com/blogs/security/how-to-restrict-amazon-s3-bucket-access-to-a-specific-iam-role/) weiter.

Phase: ga

## Anwendungsbeispiel

Dateien aus dem Verzeichnis \`path/to/files\` und seinen Unterverzeichnissen importieren:

```json
{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "path/to/files/",
      "recursive": true
    }
  }
}
```

## 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 `["import"]` festlegen, ignoriert der Robot Fehler beim Importieren der Quelldatei. Die Phase `"import"` ist nur für Import-Robots verfügbar.

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

* `force_name`: Benutzerdefinierter Name für die importierte Datei bzw. die importierten Dateien. Standardmäßig werden die Dateinamen von der Quelle abgeleitet.

* `import_on_errors`: Wenn Sie dies auf `["meta"]` setzen, wird die Datei auch bei Fehlern während der Metadatenextraktion importiert. Ähnlich verhält es sich mit dem Parameter `ignore_errors`: Der Fehler wird ebenfalls ignoriert und der Robot wird nicht angehalten, die Datei wird jedoch nicht importiert.

* `credentials`: Erstellen Sie bitte die zugehörigen <dfn>Template-Zugangsdaten</dfn> in Ihrem Transloadit-Konto und verwenden Sie den Namen dieser <dfn>Template-Zugangsdaten</dfn> als Wert für diesen Parameter. Sie enthalten die Werte für Ihre S3-Parameter `bucket`, `key`, `secret` und `bucket_region`.

  Wir empfehlen, stets <dfn>Template-Zugangsdaten</dfn> zu verwenden. Einige Anwendungsfälle erfordern jedoch dynamische Zugangsdaten, für die <dfn>Template-Zugangsdaten</dfn> aufgrund ihrer statischen Natur zu umständlich sind. Wenn dies auf Ihren Anwendungsfall zutrifft, können Sie stattdessen die folgenden Parameter verwenden: `"bucket"`, `"bucket_region"` (zum Beispiel: `"us-east-1"` oder `"eu-west-2"`), `"key"`, `"secret"`.

* `bucket`

* `bucket_region`

* `key`

* `secret`

* `path`: Der Pfad in Ihrem Bucket zur jeweiligen Datei oder zum jeweiligen Verzeichnis. Wenn der Pfad auf eine Datei verweist, wird nur diese Datei importiert. Beispiel: `images/avatar.jpg`.

  Wenn er auf ein Verzeichnis verweist, erkennbar an einem abschließenden Schrägstrich (`/`), werden alle Dateien importiert, die sich direkt in diesem Verzeichnis befinden. Beispiel: `images/`.

  Verzeichnisse werden **nicht** rekursiv importiert. Wenn Sie Dateien aus Unterverzeichnissen und tiefer verschachtelten Unterverzeichnissen importieren möchten, aktivieren Sie den Parameter `recursive`.

  Wenn Sie alle Dateien aus dem Stammverzeichnis importieren möchten, verwenden Sie hier bitte `/` als Wert. Stellen Sie in diesem Fall sicher, dass alle Ihre Objekte zu einem Pfad gehören. Wenn sich im Stammverzeichnis Ihres Buckets Objekte befinden, denen `/` nicht vorangestellt ist, erhalten Sie folgenden Fehler: `A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist.`

  Sie können hier auch ein Array aus Pfad-Strings verwenden, um mehrere Pfade in einem <dfn>Step</dfn> zu importieren, der zu demselben <dfn>Robot</dfn> gehört.

* `recursive`: Wenn Sie dies auf `true` setzen, können Dateien aus Unterverzeichnissen und weiteren darunterliegenden Verzeichnissen (usw.) des angegebenen Pfads importiert werden.

  Verwenden Sie hierbei die Paginierungsparameter `page_number` und `files_per_page` mit Bedacht.

* `page_number`: Die Seitennummer der Paginierung. Um die Abwärtskompatibilität bei nicht rekursiven Importen nicht zu beeinträchtigen, funktioniert dies derzeit nur, wenn für recursive der Wert `true` gesetzt ist.

  Stellen Sie bei umfangreichen Importen sicher, dass keine anderen Skripte Dateien innerhalb Ihres Speicherorts hinzufügen oder entfernen. Andernfalls kann die Paginierung unerwartete Ergebnisse liefern.

* `files_per_page`: Die Seitengröße der Paginierung. Dies funktioniert derzeit nur, wenn recursive den Wert `true` hat, um die Abwärtskompatibilität bei nicht rekursiven Importen nicht zu beeinträchtigen.

* `return_file_stubs`: Wenn Sie dies auf `true` setzen, importiert der Robot die eigentlichen Dateien noch nicht, sondern gibt stattdessen einen leeren Datei-Stub mit einer URL zurück, über die nachfolgende Robots die Datei importieren können. Dies ist nützlich, wenn nachfolgende Steps mehr Kontrolle über den Importvorgang benötigen, beispielsweise wenn 🤖/video/ondemand zum Einsatz kommt. Dieser Parameter sollte nur festgelegt werden, wenn alle nachfolgenden Steps Robots verwenden, die Datei-Stubs unterstützen.

* `range`: Ermöglicht es Ihnen, einen oder mehrere Bytebereiche anzugeben, die aus der Datei importiert werden sollen. Damit dies funktioniert, muss S3 Bereichsanfragen unterstützen.

  **Einzelner Bereich**: Verwenden Sie eine Zeichenfolge wie `"0-99"`, um die Bytes von 0 bis 99 zu importieren (die ersten 100 Bytes).

  **Mehrere Bereiche**: Verwenden Sie ein Array wie `["0-99", "200-299"]`, um mehrere separate Bereiche zu importieren. Die resultierende Datei enthält alle angeforderten Bereiche zusammengefügt. Lücken zwischen nicht zusammenhängenden Bereichen werden mit Null-Bytes (\0) gefüllt.

  **Bereichsformate**:

  * `"0-99"`: Bytes von 0 bis einschließlich 99
  * `"100-199"`: Bytes von 100 bis einschließlich 199
  * `"-100"`: Die letzten 100 Bytes der Datei

  **Wichtige Hinweise**:

  * S3 unterstützt Bereichsanfragen standardmäßig
  * Überlappende Bereiche sind zulässig und werden wie angefordert einbezogen
  * Die Größe der resultierenden Datei entspricht der höchsten angeforderten Byteposition; Lücken werden mit Null-Bytes gefüllt
  * Jeder Bereich wird in einer separaten Anfrage abgerufen, um die Kompatibilität mit S3 sicherzustellen