Écrire un fichier dans le stockage depuis un script

Objectif

Faire construire par une API personnalisée un fichier — un export CSV, un dépôt JSON destiné à un autre système — et le placer à un endroit où un système externe peut venir le chercher.

Pourquoi cela existe

La plateforme offre trois endroits où un fichier peut vivre, et ils ne sont pas interchangeables.

	Pour	Exemple
Ressources web	Les fichiers qui font partie de l’application	Un logo, une feuille de style
Fichiers d’enregistrement	Un fichier appartenant à un enregistrement	La photo d’un contact, un contrat signé
Stockage d’objets	Les fichiers n’appartenant à aucun enregistrement	Un export mensuel, un dépôt d’intégration

Le fichier d’un enregistrement est attaché à cet enregistrement et voyage avec lui. Un export n’appartient à l’enregistrement de personne — il n’y a aucune ligne à laquelle le rattacher — et c’est à cela que sert le stockage d’objets.

Avant de commencer

Il vous faut un nom de compartiment. Vous n’avez pas besoin de le créer : la première écriture le crée.

Les noms de compartiment se composent de lettres minuscules, de chiffres et de tirets, de 3 à 63 caractères. Ils sont partagés entre tous les locataires, comme ceux de S3 : un nom simple comme exports est donc peut-être déjà pris — préfixez-le par quelque chose qui vous est propre, comme le fait par-exports ci-dessous.

Ce qu’un script peut faire

putFile(bucket, key, text)	Écrit un fichier. Répond true, ou false s’il n’a pas pu
putFileAs(bucket, key, text, contentType)	La même chose, en précisant le type de fichier
getFile(bucket, key)	Le relit sous forme de texte — la chaîne vide s’il n’existe pas
fileExists(bucket, key)	true ou false
listFiles(bucket, prefix)	Les fichiers sous un préfixe, chacun avec key, size, contentType et uploadedAt
deleteFile(bucket, key)	En supprime un

La clé est le chemin du fichier dans le compartiment — claims/2026-09.csv. Les barres obliques qu’elle contient font simplement partie du nom, mais elles apparaissent comme des dossiers dans l’écran de stockage : regrouper les fichiers par l’une d’elles vaut donc la peine.

Étapes

1. Ouvrez votre solution et choisissez API personnalisées, puis Nouveau.

2. Donnez-lui une route — claims/export/{period} — et choisissez Post.

3. Dans le script, construisez le fichier sous forme de texte et écrivez-le :

   var claims = runQuery({ entity: 'par_claim', select: ['par_name', 'par_amount'] });
   
   var csv: string = 'reference,amount\n';
   for (var i: int = 0; i < claims.length(); i++) {
     csv = csv + `${claims[i].par_name},${claims[i].par_amount}` + '\n';
   }
   
   putFileAs('par-exports', 'claims/' + getInput('period') + '.csv', csv, 'text/csv');

4. Enregistrez, puis appelez-la.

Trois pièges fréquents

• length() a besoin de ses parenthèses. claims.length n’est pas une erreur — c’est rien : une boucle qui en dépend ne s’exécute jamais, et votre export ne contient qu’une ligne d’en-tête et aucune donnée. C’est la seule erreur de cette page qui ne se signale pas d’elle-même.
• Vous ne pouvez pas additionner un nombre et une chaîne. 'Total: ' + amount est refusé. Placez plutôt le nombre dans un modèle entre accents graves — `Total: ${amount}` — c’est la seule façon de le convertir en texte.
• Précisez le type de fichier. putFile le stocke en texte brut, et un navigateur affiche le texte brut dans l’onglet au lieu de l’enregistrer. Utilisez putFileAs avec text/csv, application/json ou le type réel du fichier.

Vérifier que cela a fonctionné

Allez dans Administration → Stockage, ouvrez le compartiment : le fichier s’y trouve, avec sa taille et son type. Téléchargez-le et vérifiez son contenu.

Ce à quoi cela ne sert pas

• Les gros fichiers binaires. Le fichier d’un script est un texte qu’il a construit. Les images, les PDF et les archives sont gérés par la plateforme elle-même, qui les diffuse en flux.
• Un fichier qui appartient à un enregistrement. Ajoutez plutôt une colonne Fichier ou Image à la table — elle est servie selon les autorisations propres à l’enregistrement, et supprimer l’enregistrement emporte le fichier avec lui.
• Donner un lien à quelqu’un. Ces fonctions remettent le texte à votre script ; elles ne génèrent pas d’URL. Un lien qui fonctionne sans connexion est une clé que n’importe qui peut transmettre : c’est donc une étape délibérée, ailleurs, et non quelque chose qu’un script fait en passant.

Dépannage

« Bucket was not found. » Vous lisez ou listez un compartiment qui n’existe pas encore — seule l’écriture en crée un. Écrivez d’abord, ou vérifiez l’orthographe.

Le fichier ne contient que l’en-tête. length sans les parenthèses. Voir ci-dessus.

« Only numbers or strings are allowed in this expression. » Vous avez additionné un nombre et une chaîne. Utilisez un modèle entre accents graves.

« This run has no caller. » Le script est une étape de plug-in asynchrone. Celles-ci s’exécutent une fois terminée la requête qui les a mises en file d’attente : il n’y a donc personne au nom de qui agir. Utilisez une étape synchrone, ou une API personnalisée.

Voir aussi

• Publier une API personnalisée
• La solution d’exemple custom-api-object-storage-export, qui reprend cette page sous une forme que vous pouvez importer et exécuter.