Descripción General

La API de almacenamiento en StudioCMS proporciona una forma unificada de gestionar e interactuar con varios backends de almacenamiento. Abstrae las complejidades de los diferentes sistemas de almacenamiento, permitiendo a los desarrolladores trabajar con una interfaz consistente independientemente de la tecnología subyacente.

Cómo funciona

La API de almacenamiento está diseñada para ser flexible y extensible. Soporta múltiples backends de almacenamiento, incluyendo sistemas de archivos locales, servicios de almacenamiento en la nube y bases de datos. Los desarrolladores pueden elegir el backend de almacenamiento que mejor se adapte a sus necesidades y cambiar fácilmente entre ellos sin modificar el código de su aplicación.

Plugins de gestión

La API de almacenamiento utiliza plugins de gestión para manejar diferentes backends de almacenamiento. Cada plugin de gestión implementa un sistema de almacenamiento específico y proporciona métodos para operaciones comunes como leer, escribir y eliminar archivos.

Un ejemplo de un gestor integrado en StudioCMS es el gestor no-op, que no realiza ninguna operación e indica a StudioCMS que no active ninguna de sus funciones de almacenamiento.

Ejemplo del gestor No-op

import type {
  
type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType,
  
interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition,
  
type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn,
  
interface StorageApiBuilderDefinition<C, R>
Storage API Builder Definition interface.
This interface defines the structure and methods for building storage API endpoints,
including handling POST and PUT requests.
StorageApiBuilderDefinition,
  
(alias) interface UrlMappingServiceDefinition
import UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition,
} from 'studiocms/storage-manager/definitions';

/**
 * Un servicio No-Op (sin operación) que implementa la interfaz StorageApiBuilderDefinition.
 *
 * Este servicio proporciona implementaciones placeholder para los endpoints de la API de almacenamiento,
 * devolviendo una respuesta 501 No Implementado tanto para solicitudes POST como PUT.
 *
 * @typeParam C - El tipo de contexto.
 * @typeParam R - El tipo de respuesta.
 */

export default class 
class NoOpStorageService<C, R>
Un servicio No-Op (sin operación) que implementa la interfaz StorageApiBuilderDefinition.
Este servicio proporciona implementaciones placeholder para los endpoints de la API de almacenamiento,
devolviendo una respuesta 501 No Implementado tanto para solicitudes POST como PUT.
NoOpStorageService<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R> implements
  
interface StorageApiBuilderDefinition<C, R>
Storage API Builder Definition interface.
This interface defines the structure and methods for building storage API endpoints,
including handling POST and PUT requests.
StorageApiBuilderDefinition<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R> {
    
NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver: 
interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R>;
    
NoOpStorageService<C, R>.urlMappingService: UrlMappingServiceDefinition
urlMappingService: 
(alias) interface UrlMappingServiceDefinition
import UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition;

    constructor(
      
driver: ContextDriverDefinition<C, R>
driver: 
interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R>,
      
urlMappingService: UrlMappingServiceDefinition
urlMappingService: 
(alias) interface UrlMappingServiceDefinition
import UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition
    ) {
      this.
NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver = 
driver: ContextDriverDefinition<C, R>
driver;
      this.
NoOpStorageService<C, R>.urlMappingService: UrlMappingServiceDefinition
urlMappingService = 
urlMappingService: UrlMappingServiceDefinition
urlMappingService;
    }

    #sharedResponse() {
      return { 
data: {
    error: string;
}
data: { 
error: string
error: 'noStorageConfigured' }, 
status: number
status: 501 };
    }

    
NoOpStorageService<C, R>.getPOST(_?: AuthorizationType): StorageAPIEndpointFn<C, R>
getPOST(
_: AuthorizationType | undefined
_?: 
type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType): 
type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R> {
      return this.
NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver.
ContextDriverDefinition<C, R>.handleEndpoint(contextHandler: ContextHandler): ContextHandlerFn<C, R>
handleEndpoint(async () => this.#sharedResponse());
    }

    
NoOpStorageService<C, R>.getPUT(_?: AuthorizationType): StorageAPIEndpointFn<C, R>
getPUT(
_: AuthorizationType | undefined
_?: 
type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType): 
type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R> {
      return this.
NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver.
ContextDriverDefinition<C, R>.handleEndpoint(contextHandler: ContextHandler): ContextHandlerFn<C, R>
handleEndpoint(async () => this.#sharedResponse());
    }
}

Configurando un gestor

Para configurar un gestor de almacenamiento en StudioCMS, debes especificar el plugin de gestión deseado en tu archivo de configuración de StudioCMS. Para hacerlo, debes instalar el paquete del plugin de gestión y luego añadirlo a la propiedad storageManager en tu archivo studiocms.config.*.

import { 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.
StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.
Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';

export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig } from "studiocms/config";
import 
function almacenamientoS3(): StudioCMSStorageManager
Creates and configures a StudioCMS S3 Storage Manager plugin.
This function initializes the S3 storage integration for StudioCMS by defining
a storage manager plugin with the necessary configuration and hooks.
@returns ― A configured storage manager instance that integrates
S3 storage capabilities with StudioCMS.
@example 
import { studiocmsS3Storage } from '@studiocms/s3-storage';

const s3Storage = studiocmsS3Storage();
almacenamientoS3 from '@studiocms/s3-storage';

export default 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.
StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.
Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';

export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig({
    
StudioCMSOptions.storageManager?: StudioCMSStorageManager
Storage Manager Configuration
storageManager: 
function almacenamientoS3(): StudioCMSStorageManager
Creates and configures a StudioCMS S3 Storage Manager plugin.
This function initializes the S3 storage integration for StudioCMS by defining
a storage manager plugin with the necessary configuration and hooks.
@returns ― A configured storage manager instance that integrates
S3 storage capabilities with StudioCMS.
@example 
import { studiocmsS3Storage } from '@studiocms/s3-storage';

const s3Storage = studiocmsS3Storage();
almacenamientoS3(),
    // otras opciones de configuración
})

Para conocer los plugins de gestión de almacenamiento disponibles, consulta el Catálogo de paquetes.