Importer des fichiers depuis des serveurs web

🤖/http/import importe dans Transloadit tout fichier accessible publiquement via une URL web.

Exemple d’utilisation

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "https://demos.transloadit.com/inputs/chameleon.jpg"
    }
  }
}

Paramètres

• interpolate

  boolean | Record<string, boolean>

  Détermine si les Assembly Variables sont interpolées pour chaque champ d’instruction.

  Par défaut, la plupart des champs d’instruction des Robots interpolent les Assembly Variables. Définissez ce paramètre sur false pour traiter tous les champs d’instruction comme du texte littéral, ou définissez le chemin d’un champ individuel sur false pour traiter uniquement ce champ comme du texte littéral. Pour les champs propres à un Robot qui sont littéraux par défaut, définissez ce paramètre sur true ou définissez le chemin de ce champ sur true pour réactiver l’interpolation.

  Utilisez des noms de champs tels que path, ou des chemins avec points tels que ffmpeg.vf pour les objets imbriqués.

• output_meta

  Record<string, boolean> | boolean | Array<string>

  Permet de spécifier un ensemble de métadonnées dont le calcul est plus coûteux en puissance CPU et qui sont donc désactivées par défaut afin que le traitement de vos Assemblies reste rapide.

  Pour les images, vous pouvez ajouter "has_transparency": true dans cet objet pour déterminer si l’image contient des parties transparentes, et "dominant_colors": true pour extraire de l’image un tableau de codes couleur hexadécimaux.

  Pour les images, vous pouvez également ajouter "blurhash": true pour extraire une chaîne BlurHash⁠ — une représentation compacte d’un espace réservé pour l’image, utile pour afficher un aperçu flou pendant le chargement de l’image complète.

  Pour les images, "thumbhash": true extrait plutôt un ThumbHash⁠ encodé en base64 dans meta.thumbhash, accompagné de meta.has_alpha (qui indique si un canal alpha existe, même lorsque l’image est entièrement opaque). Il décrit les pixels orientés selon les données EXIF et utilise la première image des images animées. L’extraction est effectuée au mieux : les images de plus de 40 mégapixels, les formats non pris en charge ou un décodage échoué ou limité ne produisent aucun espace réservé. Une extraction réussie ajoute des frais de métadonnées équivalents à 20 % des octets de ce fichier. Aucun supplément ThumbHash ne s’applique lorsque l’option est désactivée ou lorsqu’aucun hash n’est produit.

  Définissez cette option sur le Step qui produit l’image, par exemple /upload/handle pour les originaux téléversés ou /image/resize pour les sorties traitées. La définir uniquement sur /transloadit/store ne déclenche pas l’extraction : le stockage conserve les métadonnées du Step producteur. Transloadit Storage conserve un hash généré avec sa version immuable et le renvoie dans les résultats stockés et lors des lectures natives de ressources. Les téléversements directs vers S3 ne génèrent pas d’espaces réservés. Un espace réservé contient des informations sur l’image : protégez-le donc avec les mêmes contrôles d’accès que l’image complète.

  Pour les vidéos, vous pouvez ajouter le paramètre "colorspace": true pour extraire l’espace colorimétrique de la vidéo de sortie.

  Pour les vidéos, vous pouvez également ajouter "interlaced": true pour détecter si la vidéo est entrelacée. Cette option combine l’indicateur ffprobe peu coûteux field_order avec une passe d’échantillonnage idet limitée sur les premières images de la source, et expose interlaced, field_order ainsi qu’un objet de diagnostic interlace_detection sous file.meta. Cette opération est coûteuse en calcul et facturée en conséquence.

  Pour l’audio, vous pouvez ajouter "mean_volume": true pour obtenir une valeur unique représentant le volume moyen du fichier audio.

  Vous pouvez également définir cette option sur false pour ignorer l’extraction des métadonnées et accélérer le transcodage.

• user_meta

  Record<string, any>(par défaut : {})

  Ajoute des métadonnées JSON personnalisées à chaque fichier émis sans modifier son contenu. Les objets et tableaux imbriqués sont pris en charge.

  L’héritage dépend du Robot. Les valeurs sont fusionnées avec la valeur user_meta existante du fichier de sortie ; le Step actuel remplace les clés de premier niveau correspondantes. Attribuez explicitement les clés requises lorsqu’un Robot crée de nouvelles sorties.

  Dans les Steps de traitement, ${file.*} désigne la première entrée et ${result.*} le fichier émis. Les valeurs sont évaluées pour chaque sortie après l’exécution du Robot, avant l’extraction ultérieure des métadonnées et le stockage temporaire. Sur :original, les valeurs sont évaluées pour chaque téléversement avant l’extraction des métadonnées.

  Les Steps en aval lisent ${file.user_meta.key}. Consultez Métadonnées personnalisées pour un exemple complet et les règles d’héritage.

• result

  boolean(par défaut : false)

  Indique si les résultats de ce Step doivent figurer dans l’Assembly Status JSON

• queue

  batch

  Définir la file d’attente sur « batch » abaisse manuellement la priorité des Jobs de ce Step afin d’éviter de consommer des emplacements prioritaires de Jobs pour des Jobs qui n’ont pas besoin d’un temps d’attente nul dans la file

• force_accept

  boolean(par défaut : false)

  Forcer un Robot à accepter un type de fichier qu’il aurait ignoré.

  Par défaut, les Robots ignorent les fichiers qu’ils ne connaissent pas. Le Robot 🤖/video/encode, par exemple, ignorera volontiers les images en entrée.

  Avec le paramètre force_accept défini sur true, vous pouvez forcer les Robots à accepter tous les fichiers qui leur sont envoyés. Cela entraîne généralement des erreurs et ne doit être utilisé que pour le débogage ou pour traiter des cas limites.

• ignore_errors

  boolean | Array<meta | import | execute>(par défaut : [])

  Ignore les erreurs pendant certaines phases du traitement.

  Si vous définissez cette valeur sur ["meta"], le Robot ignorera les erreurs lors de l’extraction des métadonnées.

  Si vous définissez cette valeur sur ["execute"], le Robot ignorera les erreurs lors de la phase d’exécution principale.

  Si vous définissez cette valeur sur ["import"], le Robot ignorera les erreurs lors de l’importation du fichier source. La phase "import" n’est disponible que pour les Robots d’importation.

  Définir cette valeur sur true équivaut à ["meta", "import", "execute"] : les erreurs seront alors ignorées dans les trois phases.

• force_name

  string | Array<string> | null(par défaut : null)

  Nom personnalisé du ou des fichiers importés. Par défaut, les noms de fichiers sont dérivés de la source.

• import_on_errors

  Array<meta>(par défaut : [])

  Avec la valeur ["meta"], le fichier est tout de même importé en cas d’erreurs lors de l’extraction des métadonnées. Le paramètre ignore_errors est similaire : il ignore également l’erreur et garantit que le Robot ne s’arrête pas, mais le fichier n’est pas importé.

• url — obligatoire

  string | Array<string>

  L’URL depuis laquelle le fichier à importer peut être récupéré.

  Les URL HTTPS doivent présenter un certificat valide, reconnu comme fiable par Transloadit et correspondant au nom d’hôte demandé. Les certificats autosignés, expirés ou ne correspondant pas au nom d’hôte provoquent HTTP_IMPORT_FAILURE.

  Vous pouvez également spécifier un tableau d’URL ou une chaîne d’URL séparées par | pour importer plusieurs fichiers à la fois. Consultez également le paramètre url_delimiter à ce sujet.

• url_delimiter

  string(par défaut : "|")

  Fournit le délimiteur utilisé pour séparer les URL dans la valeur de votre paramètre url.

• headers

  Array<string> | Array<Record<string, string>> | string(par défaut : [])

  En-têtes personnalisés à envoyer lors de l’importation des fichiers.

  Par défaut, il s’agit d’un tableau vide : seuls les en-têtes nécessaires (par exemple Host) sont envoyés.

  Les en-têtes peuvent être spécifiés sous les formes suivantes :

  • Un tableau de chaînes au format « Header-Name: value »
  • Un tableau d’objets où chaque clé est un nom d’en-tête et chaque valeur est celle de cet en-tête
  • Une chaîne JSON qui sera analysée pour produire un objet

  Les noms d’en-têtes doivent être des jetons HTTP valides. Les valeurs d’en-têtes peuvent contenir des tabulations horizontales, mais les autres caractères de contrôle, y compris les retours chariot et les sauts de ligne, sont rejetés.

  Dans un tableau de chaînes d’en-têtes, "Header-Name;" envoie une valeur d’en-tête vide. Chaque entrée doit être un en-tête littéral ; la lecture d’en-têtes depuis un fichier avec @filename n’est pas prise en charge.

  La même valeur de headers est envoyée avec chaque URL dans ce Step /http/import. Si url est un tableau, headers n’est pas associé aux URL selon l’indice du tableau. Utilisez des Steps /http/import distincts lorsque des URL différentes nécessitent des en-têtes différents.

• fail_fast

  boolean(par défaut : false)

  Désactive le mécanisme interne de nouvelle tentative et entraîne un échec immédiat si une ressource ne peut pas être importée. Cela peut être utile pour les applications où les performances sont essentielles.

• max_file_size

  string | number

  Taille maximale autorisée en octets pour chaque fichier importé. Si le serveur distant indique une taille de fichier supérieure, l’importation est rejetée avant le début du téléchargement. Si le serveur distant n’indique pas de taille à l’avance, le téléchargement est interrompu dès que cette limite est dépassée.

• return_file_stubs

  boolean(par défaut : false)

  Si ce paramètre est défini sur true, le Robot n’importe pas encore les fichiers réels, mais renvoie à la place un stub de fichier vide qui inclut une URL à partir de laquelle les Robots suivants peuvent importer le fichier. C’est utile lorsque les Steps suivants ont besoin de davantage de contrôle sur le processus d’importation, par exemple avec le Robot 🤖/video/ondemand. Ce paramètre ne doit être défini que si tous les Steps suivants utilisent des Robots qui prennent en charge les stubs de fichier.

• range

  string | Array<string>

  Permet de spécifier une ou plusieurs plages d’octets à importer depuis le fichier. Pour que cela fonctionne, le serveur doit prendre en charge les requêtes de plage.

  Plage unique : utilisez une chaîne comme "0-99" pour importer les octets 0-99 (les 100 premiers octets).

  Plages multiples : utilisez un tableau comme ["0-99", "200-299"] pour importer plusieurs plages distinctes. Le fichier obtenu contiendra toutes les plages demandées concaténées, avec des octets nuls (\0) pour combler les intervalles entre les plages non contiguës.

  Formats des plages :

  • "0-99" : octets 0 à 99 (inclus)
  • "100-199" : octets 100 à 199 (inclus)
  • "-100" : les 100 derniers octets du fichier

  Notes importantes :

  • Le serveur doit prendre en charge les requêtes de plage HTTP (répondre avec 206 Partial Content)
  • Si le serveur ne prend pas en charge les requêtes de plage, le fichier entier sera importé à la place
  • Les plages qui se chevauchent sont autorisées et seront incluses telles que demandées
  • La taille du fichier obtenu correspondra à la position d’octet la plus élevée demandée, les intervalles étant remplis d’octets nuls

Démonstrations

Articles de blog associés