Escribir un archivo en el almacenamiento desde un script

Objetivo

Hacer que una API personalizada genere un archivo (una exportación CSV, un envío JSON para otro sistema) y lo deje en un lugar donde un sistema externo pueda recogerlo.

Por qué existe

La plataforma tiene tres lugares donde puede vivir un archivo, y no son intercambiables.

	Para	Ejemplo
Recursos web	Archivos que forman parte de la aplicación	Un logotipo, una hoja de estilos
Archivos de registro	Un archivo que pertenece a un registro	La foto de un contacto, un contrato firmado
Object Storage	Archivos que no pertenecen a ningún registro	Una exportación mensual, un envío de integración

El archivo de un registro está asociado a ese registro y viaja con él. Una exportación no pertenece al registro de nadie (no hay ninguna fila de la que colgarla), y para eso sirve Object Storage.

Antes de empezar

Necesita un nombre de bucket. No hace falta crearlo: la primera escritura lo crea.

Los nombres de bucket tienen letras minúsculas, dígitos y guiones, de 3 a 63 caracteres. Se comparten entre todos los inquilinos, igual que los de S3, así que puede que un nombre simple como exports ya esté ocupado: anteponga algo suyo, como hace par-exports más abajo.

Qué puede hacer un script

putFile(bucket, key, text)	Escribe un archivo. Devuelve true, o false si no pudo
putFileAs(bucket, key, text, contentType)	Lo mismo, indicando qué tipo de archivo es
getFile(bucket, key)	Lo vuelve a leer como texto; la cadena vacía si no existe
fileExists(bucket, key)	true o false
listFiles(bucket, prefix)	Los archivos bajo un prefijo, cada uno con key, size, contentType y uploadedAt
deleteFile(bucket, key)	Quita uno

La clave es la ruta del archivo dentro del bucket: claims/2026-09.csv. Las barras que contiene son simplemente parte del nombre, pero en la pantalla de almacenamiento se leen como carpetas, así que merece la pena agrupar por una.

Pasos

1. Abra su solución y elija API personalizadas y después Nuevo.

2. Asígnele una ruta (claims/export/{period}) y elija Post.

3. En el script, construya el archivo como texto y escríbalo:

   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. Guarde y llámela.

Tres cosas que suelen pillar a la gente

• length() necesita los paréntesis. claims.length no es un error: es nada, así que un bucle que depende de él nunca se ejecuta y su exportación sale con una fila de encabezado y ninguna fila más. Es el único error de esta página que no se anuncia solo.
• No puede sumar un número a una cadena. 'Total: ' + amount se rechaza. Ponga el número en una plantilla con acentos graves (`Total: ${amount}`), que es la única manera de convertirlo en texto.
• Indique qué tipo de archivo es. putFile lo guarda como texto sin formato, y un navegador muestra el texto sin formato en la pestaña en lugar de guardarlo. Use putFileAs con text/csv, application/json o lo que sea realmente.

Confirmar que ha funcionado

Vaya a Administración → Almacenamiento, abra el bucket y ahí estará el archivo con su tamaño y su tipo. Descárguelo y compruebe el contenido.

Para qué no sirve

• Archivos binarios grandes. El archivo de un script es texto que el script construyó. Las imágenes, los PDF y los archivos comprimidos los gestiona la propia plataforma, que los transmite por secuencias.
• Un archivo que pertenece a un registro. Ponga una columna Archivo o Imagen en la tabla: se sirve con los permisos del propio registro, y al eliminar el registro se elimina también el archivo.
• Dar un vínculo a alguien. Estas funciones entregan el texto a su script; no generan una URL. Un vínculo que funciona sin iniciar sesión es una llave que cualquiera puede pasar a otros, así que es un paso deliberado en otro lugar, no algo que un script hace de pasada.

Solución de problemas

«No se encontró el bucket». Está leyendo o enumerando un bucket que todavía no existe; solo la escritura crea uno. Escriba primero o compruebe cómo lo ha escrito.

El archivo solo tiene el encabezado. length sin los paréntesis. Consulte más arriba.

«En esta expresión solo se permiten números o cadenas». Ha sumado un número a una cadena. Use una plantilla con acentos graves.

«Esta ejecución no tiene quien llama». El script es un paso de complemento asíncrono. Esos pasos se ejecutan cuando ya ha terminado la solicitud que los puso en cola, así que no hay nadie en cuyo nombre actuar. Use un paso síncrono o una API personalizada.

Consulte también

• Publicar una API personalizada
• La solución de ejemplo custom-api-object-storage-export, que es esta página convertida en algo que puede importar y ejecutar.