Stocker téléversements et résultats sans configurer de bucket

Kevin van Zonneveld

Cofondateur · Amsterdam, Pays-Bas · Afficher la bio

Conserver les fichiers traités implique souvent de configurer un stockage à part : créer un bucket S3, rédiger une politique IAM et ajouter des informations d’identification à un Template. C’est du travail en plus avant de pouvoir vous consacrer au problème qui vous amène.

Transloadit Storage propose une alternative pour les Workspaces admis. Le Robot /transloadit/store conserve les fichiers dans le stockage de votre Workspace, et une URL Smart CDN signée sert l’original ou un dérivé généré à la volée. La Bibliothèque de fichiers de la Console et un point de terminaison compatible S3 permettent de gérer ces fichiers lorsque la Bibliothèque de fichiers est activée pour votre Workspace.

Transloadit Storage est en préversion privée. Si vous souhaitez l’essayer avant la disponibilité générale, renseignez-vous auprès de nous sur l’accès pour votre Workspace. Ce tutoriel nécessite aussi l’accès à la Bibliothèque de fichiers, que notre équipe active séparément. Activer Storage ne suffit pas à accorder cet accès.

Ce tutoriel fait passer un fichier de votre disque à Transloadit Storage, puis le ressort via le Smart CDN, en quatre courtes étapes, avec Node.js et le SDK officiel. Aucun bucket n’est créé à aucun moment.

Ce dont vous avez besoin

• Node.js 22 ou une version plus récente.
• Un Workspace admis à la préversion de Storage, avec l’accès à la Bibliothèque de fichiers activé.
• Deux Auth Keys, depuis Informations d’identification dans la Console : une clé d’API avec assemblies:write, dam:read, templates:read et templates:write pour les exemples ci-dessous, et une clé de signature Smart CDN distincte. Pour cette seconde clé, choisissez Nouvelle Auth Key et Diffusion d’images privées (signature Smart CDN), qui active Smart CDN et ne sélectionne que smart_cdn:sign. Le téléversement direct via S3 nécessite aussi dam:write.
• L’AWS CLI pour les commandes S3 facultatives de l’étape 2.
• Le slug de votre Workspace, c’est-à-dire la partie après /c/ dans l’URL de la Console, par exemple mytransloadit-toystory-app.

Les Assemblies autorisées par assemblies:write peuvent stocker et importer des fichiers via les Robots de Storage. Les portées dam:read et dam:write contrôlent l’accès S3 direct, pas ces opérations d’Assembly.

Activer Smart CDN sur une clé ne limite pas ce qu’elle peut faire par ailleurs ; ce sont ses permissions qui le font. Avec seulement smart_cdn:sign, la clé ne peut ni créer d’Assemblies autonomes ni gérer Storage. Quiconque détient son Auth Secret peut néanmoins signer des URL qui exécutent des transformations sur votre compte et servent vos fichiers stockés : conservez-le donc sur votre serveur, comme tout autre Auth Secret. En cas de fuite, supprimez la clé et créez-en une nouvelle.

Créez un projet et un fichier .env :

mkdir zero-config-storage && cd zero-config-storage
npm init -y && npm pkg set type=module
npm install @transloadit/node @transloadit/utils
curl --fail --location --output photo.jpg https://demos.transloadit.com/inputs/chameleon.jpg

TRANSLOADIT_KEY=your-api-auth-key
TRANSLOADIT_SECRET=your-api-auth-secret
TRANSLOADIT_CDN_KEY=your-smart-cdn-auth-key
TRANSLOADIT_CDN_SECRET=your-smart-cdn-auth-secret
TRANSLOADIT_WORKSPACE=your-workspace-slug

Node le lit avec --env-file, il n’y a donc aucune dépendance à dotenv. Pour les commandes shell de l’étape 2, chargez-le avec set -a; . ./.env; set +a et utilisez ce même terminal. Pendant la préversion, vous avez peut-être aussi reçu de notre part des surcharges de points de terminaison (TRANSLOADIT_ENDPOINT, TRANSLOADIT_STORAGE_S3_ENDPOINT, TRANSLOADIT_SMART_CDN_BASE_URL, TRANSLOADIT_SMART_CDN_EXTRA_PARAMS) ; les scripts ci-dessous les prennent en compte lorsqu’elles sont présentes et utilisent sinon les valeurs par défaut de production. Mettez entre guillemets les valeurs qui contiennent des espaces ou des caractères shell tels que & dans .env, afin que le fichier puisse aussi être chargé sans risque avec la commande shell.

Étape 1 : stocker un fichier avec /transloadit/store

/transloadit/store est un Robot de stockage comme /s3/store, à ceci près qu’il ne nécessite ni informations d’identification ni bucket : il écrit dans le stockage de votre Workspace. path indique l’emplacement final du fichier ; les dossiers sont créés à la demande, et ${file.name} est remplacé pour chaque fichier.

import { Transloadit } from '@transloadit/node'

const client = new Transloadit({
  authKey: process.env.TRANSLOADIT_KEY,
  authSecret: process.env.TRANSLOADIT_SECRET,
  endpoint: process.env.TRANSLOADIT_ENDPOINT,
})

const assembly = await client.createAssembly({
  files: { photo: './photo.jpg' },
  params: {
    steps: {
      stored: {
        robot: '/transloadit/store',
        use: ':original',
        path: 'uploads/${file.name}',
        // Uploading the same name again creates a new version instead of failing.
        conflict_strategy: 'overwrite',
      },
    },
  },
  waitForCompletion: true,
})

// Storing Robots do not add a result key of their own: they annotate the file they stored,
// which is still listed under the step that produced it — here the upload, `:original`.
const [stored] = assembly.results[':original']
console.log(`Stored ${stored.path} (${stored.size} bytes, asset ${stored.asset_id})`)

node --env-file=.env store.js
# Stored uploads/photo.jpg (9309370 bytes, asset 8kLg…)

C’est toute la partie « configurer le stockage » de ce tutoriel. Le fichier se trouve désormais à uploads/photo.jpg dans votre Workspace. Si vous stockez à nouveau le même chemin, vous obtenez une nouvelle version (conflict_strategy: 'overwrite'). Vous pouvez récupérer une version antérieure tant qu’elle est conservée ; le versionnage n’est ni une promesse de conservation permanente ni un substitut à votre politique de sauvegarde.

Étape 2 : le voir dans la Console ou avec les outils S3 que vous avez déjà

La Bibliothèque de fichiers doit être activée pour votre Workspace par notre équipe. Un propriétaire, un administrateur ou un membre standard du Workspace peut ensuite l’ouvrir ; un administrateur de facturation ne le peut pas. Activer Storage ne suffit pas à déverrouiller la page ni son point de terminaison S3.

Une fois l’accès activé, ouvrez la Console, choisissez votre Workspace et accédez à Bibliothèque de fichiers (https://transloadit.com/c/<workspace-slug>/file-library/). Le dossier uploads s’y trouve, avec photo.jpg à l’intérieur. Vous pouvez y parcourir et gérer vos fichiers stockés.

Vous préférez un terminal ? Transloadit Storage est compatible S3, et votre Auth Key et votre Auth Secret en sont les informations d’identification. Le slug de votre Workspace fait office de bucket :

set -a; . ./.env; set +a
export AWS_ACCESS_KEY_ID="$TRANSLOADIT_KEY" AWS_SECRET_ACCESS_KEY="$TRANSLOADIT_SECRET"
export AWS_DEFAULT_REGION=us-east-1
aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
  s3 ls "s3://$TRANSLOADIT_WORKSPACE/uploads/"
# 2026-08-31 10:12:04    9309370 photo.jpg

Les exemples suivants utilisent le listage S3 et les téléchargements versionnés. Vérifiez les opérations et les permissions dont votre client a besoin plutôt que de supposer que toutes les fonctionnalités d’AWS S3 sont disponibles. Après avoir exécuté store.js deux fois, vous pouvez lister les deux versions via l’API S3 :

aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
  s3api list-object-versions --bucket "$TRANSLOADIT_WORKSPACE" --prefix uploads/photo.jpg \
  --query 'Versions[?Key==`uploads/photo.jpg`].[VersionId,IsLatest,LastModified]' --output text
# 9G2…   True    2026-08-31T10:12:04+00:00
# 7Kq…   False   2026-08-31T10:05:41+00:00

Après avoir téléversé deux fois vers le même chemin, récupérez la version antérieure grâce à son ID de version. Le filtre sur la clé exacte évite de sélectionner un autre fichier dont le nom commence par uploads/photo.jpg :

if PREVIOUS=$(aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
  s3api list-object-versions --bucket "$TRANSLOADIT_WORKSPACE" --prefix uploads/photo.jpg \
  --query 'Versions[?Key==`uploads/photo.jpg` && IsLatest==`false`] | [0].VersionId' --output text); then
  if [ -n "$PREVIOUS" ] && [ "$PREVIOUS" != None ]; then
    aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
      s3api get-object --bucket "$TRANSLOADIT_WORKSPACE" --key uploads/photo.jpg \
      --version-id "$PREVIOUS" photo-previous.jpg
  else
    printf '%s\n' 'No previous version exists. Upload the same path again first.'
  fi
else
  printf '%s\n' 'Could not list object versions; no download was attempted.' >&2
fi

Étape 3 : le servir via le Smart CDN

Gardez privé le répertoire uploads/ du tutoriel. Pour transmettre un fichier à un navigateur, signez une URL Smart CDN pour le Template intégré builtin/storage-serve@0.0.1, qui lit le fichier depuis votre stockage et le sert. La signature comporte une date d’expiration qui limite la durée pendant laquelle Transloadit accepte cette signature. L’expiration ne peut pas rappeler les octets qu’un destinataire a déjà téléchargés ou mis en cache.

import { getSignedSmartCdnUrl } from '@transloadit/utils/node'

const url = getSignedSmartCdnUrl({
  workspace: process.env.TRANSLOADIT_WORKSPACE,
  template: 'builtin/storage-serve@0.0.1',
  input: 'uploads/photo.jpg',
  authKey: process.env.TRANSLOADIT_CDN_KEY,
  authSecret: process.env.TRANSLOADIT_CDN_SECRET,
  expiresAt: Date.now() + 60 * 60 * 1000, // valid for one hour
  // Preview environments only; omit in production.
  baseUrl: process.env.TRANSLOADIT_SMART_CDN_BASE_URL,
  urlParams: Object.fromEntries(
    new URLSearchParams(process.env.TRANSLOADIT_SMART_CDN_EXTRA_PARAMS ?? ''),
  ),
})

console.log(url)

curl --fail --silent --show-error --output photo-served.jpg "$(node --env-file=.env serve.js)"

L’URL ressemble à https://your-workspace-slug.tlcdn.com/builtin%2Fstorage-serve%400.0.1/uploads%2Fphoto.jpg?auth_key=…&exp=…&sig=sha256%3A…. Traitez-la comme des informations d’identification : quiconque la détient peut utiliser l’autorisation qu’elle porte. Passez-la donc via un pipe à curl ou transmettez-la à un navigateur plutôt que de la journaliser. La même URL sans ses paramètres auth_key, exp et sig est refusée pour ce répertoire privé, quel que soit le réglage Signature Authentication de votre Workspace. Storage prend aussi en charge des préfixes explicitement publiés et des Built-ins distincts dédiés à la diffusion publique. Ce tutoriel ne publie aucun préfixe ; ne publiez pas de fichiers privés simplement pour éviter de signer des URL.

Cela sert l’original, soit l’intégralité de ses 9,3 MB, même à un téléphone. L’étape 4 montre comment servir plutôt une version redimensionnée ; dans une vraie page, vous l’utiliseriez pour tout ce qui dépasse la taille d’une miniature.

Étape 4 (facultative) : dérivés à la volée

builtin/storage-serve sert l’original. Pour des miniatures, des filigranes ou des conversions de format, vous créez votre propre Template avec /transloadit/import, un Robot de traitement et /file/serve. Celui-ci utilise /image/resize pour redimensionner à une largeur transmise dans l’URL :

import { Transloadit } from '@transloadit/node'

const client = new Transloadit({
  authKey: process.env.TRANSLOADIT_KEY,
  authSecret: process.env.TRANSLOADIT_SECRET,
  endpoint: process.env.TRANSLOADIT_ENDPOINT,
})

const name = 'storage-thumb'
const template = {
  steps: {
    imported: { robot: '/transloadit/import', path: '${fields.input}' },
    resized: { robot: '/image/resize', use: 'imported', width: '${fields.w}', imagemagick_stack: 'v3.0.0' },
    served: { robot: '/file/serve', use: 'resized' },
  },
}

// Search every page so rerunning the script also works in Workspaces with many Templates.
let existing
for await (const item of client.streamTemplates()) {
  if (item.name === name) {
    existing = item
    break
  }
}
if (existing) {
  await client.editTemplate(existing.id, { name, template })
  console.log(`Template ${name} updated`)
} else {
  await client.createTemplate({ name, template })
  console.log(`Template ${name} created`)
}

Signer une URL pour celui-ci repose sur le même appel, avec le nom de votre propre Template et la largeur comme paramètre d’URL :

import { getSignedSmartCdnUrl } from '@transloadit/utils/node'

const url = getSignedSmartCdnUrl({
  workspace: process.env.TRANSLOADIT_WORKSPACE,
  template: 'storage-thumb',
  input: 'uploads/photo.jpg',
  authKey: process.env.TRANSLOADIT_CDN_KEY,
  authSecret: process.env.TRANSLOADIT_CDN_SECRET,
  expiresAt: Date.now() + 60 * 60 * 1000,
  baseUrl: process.env.TRANSLOADIT_SMART_CDN_BASE_URL, // preview environments only
  urlParams: {
    w: 300,
    ...Object.fromEntries(new URLSearchParams(process.env.TRANSLOADIT_SMART_CDN_EXTRA_PARAMS ?? '')),
  },
})

console.log(url)

node --env-file=.env create-template.js && \
  curl --fail --silent --show-error --output photo-thumb.jpg "$(node --env-file=.env serve-thumb.js)"
# Template storage-thumb created

Le Smart CDN renvoie une version de 300 pixels de large de uploads/photo.jpg.

Le Step /transloadit/import du Template personnalisé exige également un accès authentifié. Désactiver la Signature Authentication du Workspace ne rend pas cet import privé public. Pour d’autres Templates, consultez la documentation sur l’authentification avant d’autoriser une utilisation non signée.

Référence : les deux Robots

• /transloadit/store accepte un path facultatif, dont la valeur par défaut est ${file.url_name}. Si la destination existe déjà, l’opération échoue, sauf si vous choisissez overwrite ou rename. Enregistrez les valeurs workspace, asset_id, version_id et le path final renvoyés dans le résultat du Step producteur. Consultez la référence du Robot Storage pour toutes les options.
• /transloadit/import accepte un path de fichier ou de dossier, ou un asset_id avec un version_id facultatif pour sélectionner des octets conservés. Les imports de dossier n’incluent que les enfants directs, sauf si recursive: true est défini. Sa sortie est un fichier normal qu’un autre Robot peut référencer avec use. Consultez la référence du Robot d’import pour l’authentification et les sélecteurs.

Ce qui vient de se passer

• Un seul Robot, /transloadit/store, a conservé le fichier dans le stockage de votre Workspace. Pas de bucket, pas d’IAM, pas d’informations d’identification dans les Templates.
• Une Bibliothèque de fichiers de la Console activée et les opérations S3 prises en charge exposent les mêmes fichiers stockés.
• Une URL Smart CDN signée sert l’original, et un petit Template à vous sert les dérivés.

Pour aller plus loin

• Pour des interfaces de téléversement dans le navigateur, découvrez Uppy. Gardez les Auth Secrets et les exemples de signature de cet article sur votre serveur, pas dans le code du navigateur.
• Utilisez /transloadit/import avec un chemin de dossier et recursive: true pour inclure les sous-dossiers lors du retraitement d’une collection, par exemple pour créer de nouvelles miniatures pour toute une campagne.